Apple iOS and macOS

Papertrail can accept logs from any iOS or macOS application using one of the following methods. For each method, your code determines the name Papertrail uses to identify each log sender. After setup, see choosing sender name below.

PaperTrailLumberjack

PaperTrailLumberjack is a CocoaLumberjack logger that supports logging via messages sent over UDP and TCP. It can be easily integrated into your Cocoa project via CocoaPods or Carthage.

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa Projects. To install PaperTrailLumberjack, add the following lines (as appropriate) to your PodFile:

// Objective-C
use_frameworks!
target "YourTargetName" do
  pod "PaperTrailLumberjack"
end

/// Swift
use_frameworks!
target "YourTargetName" do
  pod "PaperTrailLumberjack/Swift"
end

�and import the PaperTrailLumberJack header:

// Objective-C
import <PaperTrailLumberjack/PaperTrailLumberjack.h>

/// Swift
import PaperTrailLumberjack

Carthage

Carthage is a lightweight dependency manager for Cocoa applications. Detailed instructions on using Carthage are available here. To import PaperTrailLumberjack, add the following line to your Cartfile:

git "https://bitbucket.org/rmonkey/papertraillumberjack.git"

Usage

PaperTrailLumberjack is extremely simple to use. Logging is as simple as calling CocoaLumberjack's various logging statements, once you have a Papertrail logger configured and added to it.

Objective-C

RMPaperTrailLogger *paperTrailLogger = [RMPaperTrailLogger sharedInstance];
paperTrailLogger.host = @"logsN.papertrailapp.com"; //Your host here
paperTrailLogger.port = XXXXX; //Your port number here    
[DDLog addLogger:paperTrailLogger];
DDLogVerbose(@"Hi papertrailapp.com);

By default, logging is via TCP with TLS. To disable TLS, add the following line before adding the logger to DDLog:

paperTrailLogger.useTLS = NO;

To log via UDP instead of TCP, add the following line before adding the logger to DDLog:

paperTrailLogger.useTcp = NO;

If you would like to set either a custom machine name or program name for your log messages, override the following properties:

paperTrailLogger.machineName = @"CustomMachineName";
paperTrailLogger.programName = @"CustomProgramName";

Swift

let paperTrailLogger = RMPaperTrailLogger.sharedInstance() as RMPaperTrailLogger!
paperTrailLogger.host = "logsN.papertrailapp.com" //Your host here
paperTrailLogger.port = XXXXX //Your port number here
DDLog.addLogger(paperTrailLogger)
DDLogVerbose("Hi papertrailapp.com")

To disable TLS, add the following line before adding the logger to DDLog:

paperTrailLogger.useTLS = false

To log via UDP instead of TCP, add the following line (before adding the logger to DDLog)

paperTrailLogger.useTcp = false 

If you would like to set either a custom machine name or program name for your log messages, override the following properties:

paperTrailLogger.machineName = "CustomMachineName"
paperTrailLogger.programName = "CustomProgramName" 

In both cases, change XXXXX and logsN to the values shown on log destinations.

Flutter

Flutter is a mobile UI framework by Google for creating native experiences on iOS and Android. The Flutter Papertrail plugin (GitHub, Dart Pub) extends the ability to send logs directly to Papertrail from within the framework.

Configuration

Import the flutter_paper_trail package and initalize the logger, replacing logsN and XXXXX with the appropriate destination and port:

import 'package:flutter_paper_trail/flutter_paper_trail.dart';
FlutterPaperTrail.initLogger(
        hostName: "logsN.papertrailapp.com",
        programName: "flutter-test-app",
        port: XXXXX,
        machineName: "Simulator(iPhone8)");
    //for machine name use Flutter DeviceInfoPlugin

Log messages are triggered using .logError, .logWarning, .logInfo, or .logDebug:

FlutterPaperTrail.logError("My message");

Special thanks to MetaFlow LTD for creating this plugin!

CocoaAsyncSocket

Here's an example of how to transmit log data using CocoaAsyncSocket and its sendData method:

GCDAsyncUdpSocket *udpSocket ;
udpSocket = [[GCDAsyncUdpSocket alloc] initWithDelegate:self delegateQueue:dispatch_get_main_queue()];
NSData *data = [
  [NSString stringWithFormat:@"the syslog message will go here"]
  dataUsingEncoding:NSUTF8StringEncoding
];
[udpSocket sendData:data toHost:@"logsN.papertrailapp.com" port:XXXXX withTimeout:-1 tag:1];

• Change the logsN and XXXXX to the values shown on log destinations
• Generate the actual log message using stringWithFormat.

Log formatting

Papertrail supports both common syslog formats. Examples below use the newer RFC 5424 format.

An example syslog string is:

<22>1 2014-06-18T09:56:21Z sendername componentname - - - the log message

Instead of:

[NSString stringWithFormat:@"the syslog message will go here"]

do this to get an ISO 8601 timestamp on a device in any locale:

NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
NSLocale *enUSPOSIXLocale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
[dateFormatter setLocale:enUSPOSIXLocale];
[dateFormatter setDateFormat:@"yyyy-MM-dd'T'HH:mm:ssZZZZZ"];

and then this to generate the message:

[NSString stringWithFormat:@"<22>1 %@ some-app some-component - - - the log message",[dateFormatter stringFromDate:[NSDate date]]];

Of course, parts of this can be reused across multiple calls or log messages, and variables can be used to provide the app and component names and log message contents.

Choosing sender name

In addition to the log message, your code provides 2 values to Papertrail: the sender name and the program/component name.

We recommend using one or a small number of distinct values for the sender name (which is some-app in the example above). Most iOS apps are deployed on tens of thousands of devices, and with that many, the device isn�t really the most meaningful identifier. Having tens of thousands of unique senders in Papertrail doesn�t do anything except clutter the interface.

Instead, use a sender name which is not device- or user-specific.

If you have a user-specific value (such as a user ID, device UUID, or IP address), use the component/program name for that value.

Here's a sample message which uses the iOS version as the sender name and your app's own user ID for the component/program name:

<22>1 2014-06-18T09:56:21Z iOS-5.1 user-123456789 - - - the log message

Or a simpler example which uses the app name as the sender:

<22>1 2014-06-18T09:56:21Z my-app user-123456789 - - - the log message

The user ID will still be fully searchable in Papertrail, and your internal staff dashboard can even link to requests from a given user. In the example above, your dashboard could link to the query program:user-123456789 to see logs generated by that user�s device(s).

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.