Birch

Simple, lightweight remote logging for Android.

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

Add jitpack to your project build.gradle.

allprojects {
    repositories {
        ...
        maven { url 'https://www.jitpack.io' }
    }
}

Add birch to your module build.gradle.

implementation 'com.ryanfung.birch-android:birch:1.8.0'
implementation 'com.ryanfung.birch-android:birch-timber:1.8.0' // (optional Tree to plug into Timber)

Setup

In your application class, initialize the logger.

class MyApp: Application() {

  override fun onCreate() {
    super.onCreate()
      
    // This is a sample of how you might want to configure the logger between development and production builds.
    if (BuildConfig.DEBUG) {
      Birch.level = 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.
    }

    Birch.debug = true // This line should be removed after you've successfully integrated.
    Birch.init(this, "YOUR_API_KEY", "YOUR_PUBLIC_ENCRYPTION_KEY")
    Birch.identifier = "your_user_id" // this is optional but highly recommended
  }
}

Logging

Use the logger as you would with the default Android 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 {
  var message = "hello"
  repeat(10000) { message = message + "hello" }
  return message
}

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 (Logcat)

During local development, it is useful to see the logs in the console (Logcat). 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 = 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. By setting debug to true, Birch will log its operations. The default value is false. You should NOT set this to true in a production build.

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.

fun onLogin(user: User) {
  Birch.identifier = user.id
  Birch.customProperties = mapOf("country" to 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 interface and initialize the logger with all the scrubbers you want to use.

import com.gruffins.birch.Scrubber

class YourScrubber: Scrubber {
    override fun scrub(input: String): String {
        return input.replace("your_regex".toRegex(), "[FILTERED]")
    }
}

Birch.init(
    this,
    "API_KEY", 
    "YOUR_PUBLIC_ENCRYPTION_KEY",
    Options().also {
        it.scrubbers = listOf(PasswordScrubber(), EmailScrubber(), YourScrubber())
    }
)

Timber

You can use the supplied tree if you want to send your logs from Timber to Birch.

Timber.plant(BirchTree())

gruffins / birch-android