Logsene for iOS Applications

Logsene is ELK as a Service. This library lets you collect mobile analytics and log data from your iOS applications using Logsene. If you don't have a Logsene account, you can register for free to get your app token.

Getting Started

Logsene log shipping library for iOS is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "Logsene"

Run pod install
Call LogseneInit() from your application delegate in didFinishLaunchingWithOptions:. For example:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        try! LogseneInit("<yourtoken>", type: "example")
    }
}

You can optionaly provide the receiverUrl parameter if you are using Logsene On Premises, and maxOfflineMessages to configure how many messages are stored while device is offline (5,000 by default).

Note: We highly recommend creating a write-only token in your application settings for use in your mobile apps.

Example Application

You can try out the example application with Cocoapods:

cd ~/Desktop
pod try Logsene

Make sure to set your own application token in AppDelegate.swift.

Mobile Application Analytics

You can collect application analytics using Logsene. To do that, use the LLogEvent() function to send custom events. For example, you might want to send an event each time the user completes a game level:

LLogEvent(["event": "level_completed", "message": "Level 3 completed", "value": "3"])

To visualize the collected data, you would use the integrated Kibana dashboard.

If you don't see the events in the dashboard immediately, note that this library sends data in batches to preserve the battery (every 60s), or if there are more than 10 messages queued up. Messages are saved while the device is offline, so you don't have to worry about losing any data.

When it comes to the structure of your events, you are free to choose your own, the above is just an example. You can use any number of fields, and you can use nested fields. Basically, any valid JSON object will work fine. Note that the library reserves the meta field for meta information (see below). If you set a value for this field when sending an event, no meta information will be included for that event.

Meta Fields

A few predefined meta fields are included in each event sent to Logsene. The fields are stored inside the "meta" field.

versionName (app version string, eg. 1.0)
versionCode (app build number, eg. 92)
osRelease (iOS version, eg. 9.3.0)
uuid (device identifier)

You can set your own meta fields with LogseneSetDefaultMeta. For example:

LogseneSetDefaultMeta(["user": "user@example.com", "plan": "free"])

Note that these meta fields are global, and will be attached to every event sent to Logsene.

Centralized Logging

The library offers some basic functions for centralized logging:

LLogDebug
LLogInfo
LLogWarn
LLogError

For integrating with existing logging frameworks, see below.

CocoaLumberjack

If you're using CocoaLumberjack for logging, you can use the custom Logsene logger to send log messages to Logsene automatically. You should configure CocoaLumberjack to use the Logsene logger:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        // NOTE: Set your token below
        try! LogseneInit("<yourtoken>", type: "example")

        // Here we setup CocoaLumberjack to log to both XCode console and Logsene
        DDLog.addLogger(DDTTYLogger.sharedInstance())
        DDLog.addLogger(LogseneLogger())
        DDLogInfo("hello world from CocoaLumberjack!")
        return true
    }
}

LogseneLogger is not included in the pod, but you can find the implementation here. Feel free to use it in your own project.

NSLog

The library provides a mechanism for intercepting NSLog messages and sending them to Logsene. It uses undocumented APIs to accomplish this, so you should probably use CocaLumberjack instead. To send all NSLog messages to Logsene, call LLogNSLogMessages() just after LogseneInit().

How to log unhandled exceptions

You can log any unhandled Foundation exceptions by defining your own uncaught exception handler. For example:

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?

    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
        // NOTE: Set your token below
        try! LogseneInit("<yourtoken>", type: "example")

        NSSetUncaughtExceptionHandler { exception in
            // log unhandled exception message
            LLogError(exception)
        }
        return true
    }
}

MoathOthman/sematext-logsene-ios