{"id":13609823,"url":"https://github.com/gruffins/birch-android","last_synced_at":"2025-04-12T20:32:33.037Z","repository":{"id":63528635,"uuid":"555679677","full_name":"gruffins/birch-android","owner":"gruffins","description":"Remote logger used with the Birch logging platform","archived":false,"fork":false,"pushed_at":"2025-04-07T03:07:30.000Z","size":237,"stargazers_count":16,"open_issues_count":6,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-07T04:22:39.567Z","etag":null,"topics":["android","kotlin","logger","logging","timber","timber-logs"],"latest_commit_sha":null,"homepage":"https://birch.ryanfung.com","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gruffins.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-22T04:19:15.000Z","updated_at":"2025-04-07T03:06:06.000Z","dependencies_parsed_at":"2023-02-18T17:30:21.667Z","dependency_job_id":"1bc3995a-87bb-47da-b227-0764efa94f8b","html_url":"https://github.com/gruffins/birch-android","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruffins%2Fbirch-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruffins%2Fbirch-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruffins%2Fbirch-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gruffins%2Fbirch-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gruffins","download_url":"https://codeload.github.com/gruffins/birch-android/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248630112,"owners_count":21136381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","kotlin","logger","logging","timber","timber-logs"],"created_at":"2024-08-01T19:01:38.437Z","updated_at":"2025-04-12T20:32:32.597Z","avatar_url":"https://github.com/gruffins.png","language":"Kotlin","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/381273/204187386-ec93e173-a6fa-40b1-8b74-c52a0c5048b3.png\" /\u003e\n\u003c/p\u003e\n\n# Birch\n![Tests](https://github.com/gruffins/birch-android/actions/workflows/tests.yml/badge.svg)\n![Release](https://jitpack.io/v/com.gruffins/birch-android.svg)\n[![codecov](https://codecov.io/gh/gruffins/birch-android/branch/main/graph/badge.svg?token=CZ0HQ8VI6T)](https://codecov.io/gh/gruffins/birch-android)\n\nSimple, lightweight remote logging for Android.\n\nSign up for your free account at [Birch](https://birch.ryanfung.com).\n\nBirch 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.\n\nBirch can drain to\n- New Relic\n- Datadog\n- Logtail\n- Loggly\n- Elasticsearch\n- Papertrail\n- Logz\n- CloudWatch\n- S3\n- Wasabi\n- Google Cloud Logging\n- A custom webhook\n\n# Installation\n\nAdd jitpack to your project build.gradle.\n```\nallprojects {\n    repositories {\n        ...\n        maven { url 'https://www.jitpack.io' }\n    }\n}\n```\n\nAdd birch to your module build.gradle.\n```\nimplementation 'com.ryanfung.birch-android:birch:1.8.0'\nimplementation 'com.ryanfung.birch-android:birch-timber:1.8.0' // (optional Tree to plug into Timber)\n```\n\n# Setup\n\nIn your application class, initialize the logger.\n```kotlin\nclass MyApp: Application() {\n\n  override fun onCreate() {\n    super.onCreate()\n      \n    // This is a sample of how you might want to configure the logger between development and production builds.\n    if (BuildConfig.DEBUG) {\n      Birch.level = Level.TRACE // This overrides the server configuration during local development. The default is null.\n      Birch.synchronous = true // This makes the logger log synchronously. The default is false.\n    } else {\n      Birch.console = false // Disable console logging in production.\n    }\n\n    Birch.debug = true // This line should be removed after you've successfully integrated.\n    Birch.init(this, \"YOUR_API_KEY\", \"YOUR_PUBLIC_ENCRYPTION_KEY\")\n    Birch.identifier = \"your_user_id\" // this is optional but highly recommended\n  }\n}\n```\n\n# Logging\nUse the logger as you would with the default Android logger.\n\n```kotlin\nBirch.t(\"trace message\") // simplest\nBirch.t { \"trace message\" } // most performant especially if it's expensive to build the log message.\n\nBirch.d(\"debug message\")\nBirch.d { \"debug message\" }\n\nBirch.i(\"info message\")\nBirch.i { \"info message\" }\n\nBirch.w(\"warn message\")\nBirch.w { \"warn message\" }\n\nBirch.e(\"error message\")\nBirch.e { \"error message\" }\n```\n\nBlock 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:\n\n```kotlin\nBirch.d {\n  var message = \"hello\"\n  repeat(10000) { message = message + \"hello\" }\n  return message\n}\n```\n\nIf the current log level is `INFO`, the log will not get constructed.\n\n# Configuration\nDevice 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.\n\n### Console (Logcat)\nDuring 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`.\n```kotlin\nBirch.console = true\n```\n\n### Remote\nDuring 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`.\n```kotlin\nBirch.remote = false\n```\n\n### Level\nDuring 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.\n```kotlin\nBirch.level = Level.TRACE\n```\n\n### Synchronous\nDuring 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.\n```kotlin\nBirch.synchronous = true\n```\n\n### Debug\nWhen 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.\n```kotlin\nBirch.debug = true\n```\n\n### Encryption\n\nWe **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.\n\nAn invalid public key will throw an exception.\n\nTo learn more, see our [Encryption](https://github.com/gruffins/birch-android/wiki/Encryption) documentation.\n\n# Identification\nYou 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`.\n\nYou can also set custom properties on the source that will propagate to all drains.\n\n```kotlin\nfun onLogin(user: User) {\n  Birch.identifier = user.id\n  Birch.customProperties = mapOf(\"country\" to user.country)\n}\n```\n\n# Opt Out\n\nTo comply with different sets of regulations such as GDPR or CCPA, you may be required to allow users to opt out of log collection.\n\n```kotlin\nBirch.optOut = true\n```\n\n# Log Scrubbing\n\nBirch 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.\n\nIf you wish to configure additional scrubbers, implement the `Scrubber` interface and initialize the logger with all the scrubbers you want to use.\n\n```kotlin\nimport com.gruffins.birch.Scrubber\n\nclass YourScrubber: Scrubber {\n    override fun scrub(input: String): String {\n        return input.replace(\"your_regex\".toRegex(), \"[FILTERED]\")\n    }\n}\n```\n\n```kotlin\nBirch.init(\n    this,\n    \"API_KEY\", \n    \"YOUR_PUBLIC_ENCRYPTION_KEY\",\n    Options().also {\n        it.scrubbers = listOf(PasswordScrubber(), EmailScrubber(), YourScrubber())\n    }\n)\n```\n\n# Timber\nYou can use the supplied tree if you want to send your logs from Timber to Birch.\n\n```kotlin\nTimber.plant(BirchTree())\n```\n","funding_links":[],"categories":["Kotlin"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgruffins%2Fbirch-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgruffins%2Fbirch-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgruffins%2Fbirch-android/lists"}