README.md

Birch

Simple, lightweight remote logging for Swift iOS / macOS / tvOS.

Sign up for your free account at Birch.

Birch allows you to log to a variety of drains regardless of whether they have a native implementation or not. On top of that, Birch provides the ability to remotely adjust log configurations on any of your apps in production.

Birch can drain to

• New Relic
• Datadog
• Logtail
• Loggly
• Elasticsearch
• Papertrail
• Logz
• CloudWatch
• S3
• Wasabi
• Google Cloud Logging
• A custom webhook

Installation

Using CocoaPods

pod 'Birch'
pod 'BirchLumberjack' # optional. only used if you use CocoaLumberjack
pod 'BirchXCGLogger' # optional. only used if you use XCGLogger

Using Carthage

github "gruffins/birch-swift"

Using Swift Package Manager

.package(url: "https://github.com/gruffins/birch-swift.git", majorVersion: 1)

Setup

In your app delegate class, initialize the logger.

import Birch

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
    #if DEBUG
      Birch.level = .trace // This overrides the server configuration during local development. The default is null.
      Birch.synchronous = true // This makes the logger log synchronously. The default is false.
    #else
      Birch.console = false // Disable console logging in production.
    #endif

    Birch.debug = true // This line should be removed after you've successfully integrated.
    Birch.initialize("YOUR_API_KEY", publicKey: "YOUR_PUBLIC_ENCRYPTION_KEY")

    return true
  }
}

Logging

Use the logger as you would with any logger.

Birch.t("trace message") // simplest
Birch.t { "trace message" } // most performant especially if it's expensive to build the log message.

Birch.d("debug message")
Birch.d { "debug message" }

Birch.i("info message")
Birch.i { "info message" }

Birch.w("warn message")
Birch.w { "warn message" }

Birch.e("error message")
Birch.e { "error message" }

Block based logging is more performant since the blocks do not get executed unless the current log level includes the level of the log. See the following example:

Birch.d {
  return "hello" + someExpensiveFunction()
}

If the current log level is INFO, the log will not get constructed.

Configuration

Device level configuration is left to the server so you can remotely control it. There are a few things you can control on the client side.

Console

During local development, it is useful to see the logs in the console. These console logs are not useful in production since you cannot read them remotely. The default is true.

Birch.console = true

Remote

During local development, it's unlikely that you'll need remote logging. You can optionally turn it off to minimize your usage on Birch. The default is true.

Birch.remote = false

Level

During local development, you may want to quickly override the server configuration. The default is null which allows the server to set the remote level. Setting a value will ALWAYS override the server and prevent you from being able to remotely adjust the level.

Birch.level = .trace

Synchronous

During local development, you may want logs to print immediately when you're stepping through with a debugger. To do this, you'll need to use synchronous logging. The default value is false. Synchronous logging is slower since it has to perform the logging inline.

Birch.synchronous = true

Debug

When integrating the library, you may be curious to see the logger at work.

Birch.debug = true

Encryption

We HIGHLY recommend using encryption to encrypt your logs at rest. If you leave out the public encryption key, Birch will save logs on the device in clear text.

An invalid public key will throw an exception.

To learn more, see our Encryption documentation.

Identification

You should set an identifier so you can identify the source in the dashboard. If you do not set one, you will only be able to find devices by the assigned uuid via Birch.uuid.

You can also set custom properties on the source that will propagate to all drains.

func onLogin(user: User) {
  Birch.identifier = user.id
  Birch.customProperties = ["country": user.country]
}

Opt Out

To comply with different sets of regulations such as GDPR or CCPA, you may be required to allow users to opt out of log collection.

Birch.optOut = true

Log Scrubbing

Birch comes preconfigured with an email and password scrubber to ensure sensitive data is NOT logged. Emails and passwords are replaced with [FILTERED] at the logger level so the data never reaches Birch servers.

If you wish to configure additional scrubbers, implement the Scrubber protocol and initialize the logger with all the scrubbers you want to use.

import Birch

class YourScrubber: Scrubber {

    init() {}

    public func scrub(input: String) -> String {
        return input.replacingOccurrences(
            of: "YOUR_REGEX",
            with: "[FILTERED]",
            options: [.regularExpression, .caseInsensitive]
        )
    }
}

let options = Options()
options.scrubbers = [PasswordScrubber(), EmailScrubber(), YourScrubber()]

Birch.initialize("API_KEY", publicKey: "YOUR_PUBLIC_ENCRYPTION_KEY", options: options)

CocoaLumberjack

You can use the supplied wrapper if you want to send your logs from CocoaLumberjack to Birch.

See Birch-Lumberjack for more details.

import BirchLumberjack

DDLog.add(DDBirchLogger())

XCGLogger

You can use the supplied wrapper if you want to send your logs from XCGLogger to Birch.

See Birch-XCGLogger for more details.

import BirchXCGLogger

let logger = XCGLogger(identifier: "your_identifier", includeDefaultDestinations: false)
logger.add(destination: BirchXCGLogger())