{"id":26360122,"url":"https://github.com/volvo-cars/sensible-logging-for-android","last_synced_at":"2025-03-16T16:35:31.149Z","repository":{"id":63756190,"uuid":"456490654","full_name":"volvo-cars/sensible-logging-for-android","owner":"volvo-cars","description":"Extendable log utils for Android projects","archived":false,"fork":false,"pushed_at":"2025-02-21T13:01:24.000Z","size":745,"stargazers_count":34,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-09T10:38:25.138Z","etag":null,"topics":["android","android-library","logging","tracing"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/volvo-cars.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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-02-07T12:11:24.000Z","updated_at":"2025-02-21T13:01:28.000Z","dependencies_parsed_at":"2023-02-16T11:16:17.599Z","dependency_job_id":"b667b51c-4a1a-4ce5-b6b3-b85538ede515","html_url":"https://github.com/volvo-cars/sensible-logging-for-android","commit_stats":null,"previous_names":["volvo-cars/sensible-logging-for-android"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volvo-cars%2Fsensible-logging-for-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volvo-cars%2Fsensible-logging-for-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volvo-cars%2Fsensible-logging-for-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/volvo-cars%2Fsensible-logging-for-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/volvo-cars","download_url":"https://codeload.github.com/volvo-cars/sensible-logging-for-android/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243898163,"owners_count":20365703,"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","android-library","logging","tracing"],"created_at":"2025-03-16T16:35:24.788Z","updated_at":"2025-03-16T16:35:31.123Z","avatar_url":"https://github.com/volvo-cars.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"![header-image](header.png)\nSensible logging for Android aim to provide no-nonsense logging frontend API that is easily extended. \nThe goal of this library is *not* to be rich in features, but to provide a stable baseline for you to build on in your own projects.\n\n## Core concepts\nThe library consists of a few fundamental elements:\n\n### Log class\nThe `Log` class is the main interaction point of this library. \nInside it you will find the familiar log statement methods such as `Log.d()`\n ```kotlin\n Log.d(\"Initialising the flux capacitor\", Categories.UI, Channels.CrashReporting)\n```\n\n\n### Channels\n`Log` directs the log statements to `Channel` implementations. Think of Channels as sinks you print your statements to.\nCurrently, the library includes `LogCatChannel` and `StandardOutChannel` (for unit tests).\n\nDepending on your use-case, either implement a subtype of `ReleaseChannel` or `DebugChannel`.\n\n - `DebugChannel`s are meant to be used during development. Additional to the log-line, it includes the following information:\n ```kotlin\ndata class Meta(\n    val className: String,\n    val simpleClassName: String,\n    val functionName: String,\n    val lineNumber: Int,\n    val threadName: String,\n    val fileName: String\n)\n```\n_It retrieves this data using `Throwable().stackTrace`. Be aware that it can have negative impact to performance, so default to only use it in debug builds._\n \n- `ReleaseChannel`s only include the log-line and are meant to be used in release-builds.\n\n#### Channel ids\nA channel has a integer identifier. You can optionally specify a channel ID in your log statement to also print to that channel.\n\nAs an example, you can log non-fatal exceptions and messages to your crash reporting service via a `CrashReportingChannel`.\nUsing that you can easily log to your crash reporting service from wherever in your code.\n```kotlin\n    Log.e(\"Something fatal occurred\", exception, 4 /*CrashReportingChannel*/)\n```\n\nWhile the channel parameter is an integer. We recommend organising your channels in one file, for auto-completeness. Like so:\n```kotlin\ntypealias Channel = Int\n\nobject Channels {\n    const val LogCat: Channel = LogCatChannel.ID\n    const val CrashReporting: Channel = CrashReportingChannel.ID\n}\n\n// then you can autocomplete your way to the channel\nLog.e(\"Something fatal occurred\", exception, Channels.CrashReporting)\n```\n#### Default channels\nDuring setup, you can mark a Channel as default. Log statements are always forwarded to default channels, meaning you don't have to specify them explicitly in your log statements.\n\nAn example where this is useful; you can mark the LogCat channel as default in a debug build, but not in a release build.\n\n### Filters\n```kotlin\ninterface Filter {\n    fun matches(line: Line): Boolean\n}\n```\nTo control what a `Channel` should output you pass an instance of `Filter`. You can combine different filters by using the infix functions\n`and` \u0026 `or`:\n```kotlin\n    SimpleLogLevelFilter(Level.ERROR) and SimpleCategoryFilter(Categories.UI)\n```\nwould only print messages with level *error* and above, and of the category *UI*.\nIf you don't care about filters, you can pass the `AllowAllFilter` to your `Channel`.\n\n### Formatters\n```kotlin\ninterface Formatter {\n    fun format(line: Line, meta: Meta?): String\n}\n```\nA `Channel` uses a `Formatter` to control the format of the output. If you are directing your output to a file, we recommend using `SimpleFormatter`\n\n### Categories\nAll log statement methods inside `Log` allow the passing of a log category. This can be used to order your statements into high level areas of interest.\nWant to know what is going on with your backend? Direct your network client log statements to the `Network` category, and enable only that category.\n\nSimilar to channels, the category parameter is a string. Here we also recommend organising your categories in one file. Like so:\n\n```kotlin\nobject Categories {\n    const val Default = sh.vcm.sensiblelogging.util.Constants.DEFAULT_CATEGORY\n    const val Analytics = Category(\"Analytics\")\n    const val Network = Category(\"Network\")\n    const val Process = Category(\"Process\")\n    const val Activity = Category(\"Activity\")\n    const val Service = Category(\"Service\")\n    const val Fragment = Category(\"Fragment\")\n    const val RxJava = Category(\"RxJava\")\n    const val FluxCapacitorFeature = Category(\"FluxCapacitorFeature\")\n    const val Push = Category(\"Push\")\n    const val UI = Category(\"UI\")\n}\n```\n\n## Usage\n\n### Step 1\n\n```kotlin\n    if (BuildConfig.DEBUG) {\n    // Sane defaults filter\n    val categoriesFilter = Filter.categories(listOf(\n        Categories.Default,\n        Categories.Network,\n        Categories.FluxCapacitorFeature,\n        Categories.Process,\n        Categories.Activity,\n        Categories.Fragment\n    ))\n    val filterCombination = Filter.level(Level.WARN) or categoriesFilter\n    val channels = Log.Setup.Configuration()\n        .addLogCatChannel(filter = filterCombination, default = true)\n        .create()\n    Log.Setup.addChannels(channels)\n\n    // optionally opt-in to logging out Process, Activity and Fragment lifecycle methods from the :lifecycle dependency\n    registerLifecycleLoggers(\n        processCategory = Categories.Process,\n        activityCategory = Categories.Activity,\n        fragmentCategory = Categories.Fragment\n    )\n}\n```\n\n### Step 2\n```kotlin\n // Log from your code\n // Passing \"Default\" as category is optional, if no category is passed, default will be used \n // Passing \"LogCat\" as channel is optional, if no channel is passed, default will be used \n Log.d(\"Initialising the flux capacitor\", Categories.Default, Channels.LogCat)\n```\n\n### Step 3\nBuild your own Channels, Filters \u0026 Formatters to solve your project needs.\n\nFor example: you can log non-fatal exceptions to your crash reporting service via a `CrashReportingChannel`.\nThe `CrashReportingChannel` can be configured with a `Filter` that only pass a subset of your categories and all logged errors.\nUsing that you can easily log to this channel from wherever in your code.\n\nWant persisted logs? Implement a `SQLiteChannel` using your favourite ORM library. You can then display those statements from\nyour debug UI. Or provide a shortcut from your app settings to dump the database to a text file that your users can email to you.\n\nWant to control the log categories in runtime? Use the `SharedPreferencesCategoryFilter` with your `LogCatChannel` and enable updating of it from your debug UI.\n\nDownload\n--------\n\n```groovy\n// in your root build.gradle\nrepositories {\n  mavenCentral()\n}\n\n// in your app build.gradle\ndependencies {\n  implementation 'sh.vcm.sensiblelogging:sensible-logging:1.2.1'\n  implementation 'sh.vcm.sensiblelogging:lifecycle:1.2.1'\n}\n```\n\n## Requirements\n\n - `minSdk` is currently set to `16`\n - The base library is only dependant on the Android SDK and kotlin stdlib\n - The lifecycle extensions are dependant on `androidx.appcompat` and `androidx.lifecycle` libraries\n\n## License\n\n    Copyright 2022 Volvo Cars Corporation\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolvo-cars%2Fsensible-logging-for-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvolvo-cars%2Fsensible-logging-for-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvolvo-cars%2Fsensible-logging-for-android/lists"}