# nRF Logger API writes app logs straight into the nRF Logger database > The nRF Logger API is a Java library from Nordic Semiconductor that lets an Android app create log sessions and append entries that show up in the nRF Logger app, with a Timber integration and a local content provider fallback for devices where nRF Logger is not installed. It suits developers of Bluetooth and IoT companion apps on Android, and it is a logging sink rather than a logging framework. **nordicsemi/nRF-Logger-API** — The public library with nRF Logger API. Allows to log custom logs into the nRF Logger database. - Repository: https://github.com/nordicsemi/nRF-Logger-API - Stars: 556 · Forks: 202 - Language: Java - License: BSD-3-Clause - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/nordicsemi-nrf-logger-api ## Logs aimed at the person holding the device The nRF Logger API is a public library from Nordic Semiconductor, and the README states its purpose plainly: it allows to easily create custom log entries from your application in the nRF Logger app, and those entries land in the nRF Logger database. The use case behind that is specific. Logcat is the normal Android logging channel, but the README notes the logger may be used for debugging purposes, as LogCat is not always available. When an app talks to a Bluetooth peripheral, the person who needs to read the log is often the one holding the kit, in a lab or at a site, with no USB cable and no adb session. nRF Logger is the app that Nordic ships for exactly that, and this library is the way an application writes into it. The library is already the mechanism behind two well known companion apps, since the README says it is being used by nRF Connect and nRF Toolbox, both available on Google Play. The package is Java, the licence is BSD-3-Clause, the repository is not archived, and the last push was on 2026-08-12, with release 2.6.0 published the same day, after 2.5.0 and 2.4.0 in August 2024. ## Adding the dependency to an Android project The library is distributed on Maven Central and the README gives the dependency line for an Android Studio project, to be added to the component's gradle.build.kts file. ```bash implementation('no.nordicsemi.android:log:') ``` There is a second artefact for teams that already log through Timber 5.0.1, and the README points at it for easy integration. ```bash implementation('no.nordicsemi.android:log-timber:') ``` Two compatibility notes sit right next to those lines and both matter in practice. If your project is NOT migrated to AndroidX, the README says to use version 2.2.0, which pins you to an older line of the library and its older behaviour. If you use ProGuard, the README states that a keep rule for the no.nordicsemi.android.log package is added automatically to your ProGuard rules, so the classes survive shrinking and the log calls do not silently disappear in a release build. The API documentation is generated and hosted at nordicsemi.github.io/nRF-Logger-API, and the repository carries a sample/ directory with a simple application plus a proguard-rules.pro file, which is the fastest way to see the intended usage. ## Sessions, keys and the grouping model The data model has three ideas in it, and the README walks through them one by one with code. A session is created with a context, a key and a name. ```java logSession = Logger.newSession(context, key, name); ``` The name is what appears as the title, and if name is null then No name is shown. The key groups log sessions from the same day together, and the README is explicit that the key parameter may not be null. When you create your first log session from your application its name is added to the nRF Logger drop-down menu, so the sessions from your app become selectable entries rather than a wall of text. A profile name gives you a second grouping dimension, and the README explains that you may create multiple folders for different components of your application by creating a session with a profile name, which is concatenated with the application name and visible as a different entry in the drop-down menu. ```java logSession = Logger.newSession(context, "Profile Name", key, name); ``` Sessions can also carry a description and a mark, which is how you annotate a run in the field. ```java Logger.setSessionDescription(logSession, "This is a comment"); ``` ```java Logger.setSessionMark(logSession, Logger.MARK_FLAG_RED); ``` ## Appending entries and the six log levels Once a session exists, entries are appended to it, and the README shows both a plain text call and a formatted string resource call. ```java Logger.log(logSession, Level.INFO, text); ``` ```java Logger.e(logSession, R.string.error, someArg); ``` There are six levels available, listed in the features as DEBUG, VERBOSE, INFO, APPLICATION, WARNING and ERROR, with the APPLICATION level added in version 2.0 of the library. That APPLICATION level is the one worth understanding, because it is the level the library reserves for messages that come from the application itself rather than from a dependency, which lets a reader separate your own diagnostics from framework noise. The feature list also includes opening the log in nRF Logger for viewing, which is the step that takes a session from the device to a screen where a person can read it. There is a caveat that shapes the whole integration, and the README states it directly: if the nRF Logger application is not installed on the device those methods do nothing. That is the single most important sentence in the document for anyone integrating this into a shipping app, because it means the library is safe to leave in place but gives you nothing on devices where the companion app is absent. ## The Timber integration and its level mismatches The log-timber artefact plugs nRF Logger into Timber, which most Android projects already use as their logging facade. The README instructs you to plant the nRFLoggerTree after importing the dependency, following the Timber website. The Important section then lists six caveats, and they are worth reading closely because they are all consequences of mapping one severity model onto another. The log-timber library uses the @NonNull and @Nullable annotations from androidx.annotation instead of the ones from org.jetbrains.annotations that Timber uses. Timber's log levels are incompatible with those in nRF Logger: in Timber the APPLICATION level is missing, and DEBUG has higher priority than VERBOSE. Using Timber's API it is not possible to log on APPLICATION level at all. Logs logged with the Log.VERBOSE priority will be upgraded to VERBOSE level, and logs logged with Log.DEBUG priority will be downgraded to DEBUG level, so the priorities shift in opposite directions depending on the level. Finally, tags are added before the message in the form [TAG] message, and this can be turned off with tree.setLoggingTagsEnabled(false), a feature available since 2.5. If your Timber configuration relies on priority ordering, that ordering is not preserved on the nRF Logger side. ## LocalLogContentProvider for devices without nRF Logger Version 2.0 added the LocalLogContentProvider class, which exists to keep logs even if the nRF Logger application is not installed. The README is candid about what the local database gives up: it is a limited version of the one in nRF Logger, it does not support multiple applications because the new provider is designed to work only in one application, and marking a session with a flag or a star and adding a description are not supported. To use it you must extend the class in your project and add its definition to the AndroidManifest.xml file. ```xml ``` The exported attribute is not incidental. The README explains that if you want to use the local logger in threads that are owned by other applications, for example Bluetooth scanner callbacks, you must set the exported attribute to true, otherwise the Bluetooth application will not have the permission to add log events. You may also use a Handler object to log in the UI thread of your application. Version 2.0 also introduced the ILogSession interface, implemented by both LogSession and LocalLogSession, and the README notes that you need to change the type of your log session object to ILogSession when migrating to version 2.0 of the library. That is the breaking change to plan for if you upgrade from an earlier line. ## Where the nRF Logger API is the wrong choice The limits are clear once you see that this is a local sink for a human. The first is that nothing is collected remotely. Entries go into a database on the device, and getting them off the device means a person opens the nRF Logger app and shares them manually, so a production telemetry or crash reporting pipeline is a different tool entirely, and the library does not attempt to be one. The second is that the log store has no stated retention, rotation or size limit, which means a long running app that logs in a loop writes to the device database without a documented bound. The third is the dependency on a companion app being installed, which is fine for a developer tool and wrong for a consumer app, and the LocalLogContentProvider fallback exists precisely because that is hard to guarantee. The fourth is the AndroidX boundary at version 2.2.0, which is a real constraint for a project that has not migrated. The fifth is the Android platform floor, since the README says nRF Logger is available for Android 4.2 and newer, so the log app itself sets the minimum device the workflow supports. And the sixth is scope: the library covers sessions, entries and levels, with no filtering, no query API and no export format of its own. If you need structured logs you can search and ship to a server, you are looking at a different dependency, and the sensible comparison is with a logging framework such as Timber or SLF4J backed by a file writer that your own code ships, which gives you control of format and destination at the cost of building the viewer yourself. ## Conclusion Adopt the nRF Logger API if your Android application needs to hand structured logs to a person looking at a device, since it produces named, grouped, markable sessions in the nRF Logger app that Logcat output cannot match, and if your users are the kind who run Bluetooth and IoT tooling. Do not adopt it as a general purpose logging system for production crash reporting, because there is no remote collection, no rotation policy and no structured export beyond what nRF Logger offers. Verify two things first: that your build is on AndroidX, because the README says projects not migrated to AndroidX must use version 2.2.0, and that your users have the nRF Logger app installed, since without it the Logger calls do nothing unless you extend the LocalLogContentProvider and register it in the AndroidManifest.xml. The practical first step is to add the no.nordicsemi.android:log dependency to your gradle.build.kts file, create one session with Logger.newSession(context, key, name), and log a single entry before wiring up the rest. ## FAQ ### What is the nRF Logger API? It is a Java library from Nordic Semiconductor that lets an Android application create custom log entries in the nRF Logger app and its database. It is already used by nRF Connect and nRF Toolbox, is BSD-3-Clause licensed, and is published on Maven Central. ### How do I add the nRF Logger API to my Android project? Add the dependency to the component's gradle.build.kts file, using implementation('no.nordicsemi.android:log:'), or implementation('no.nordicsemi.android:log-timber:') if you integrate through Timber 5.0.1. If your project is not migrated to AndroidX, the README says to use version 2.2.0. ### How do I create a log session and add entries with the nRF Logger API? Create the session with Logger.newSession(context, key, name), where the key groups sessions from the same day and may not be null, then append entries with Logger.log(logSession, Level.INFO, text) or the level specific helpers such as Logger.e. Six levels are available: DEBUG, VERBOSE, INFO, APPLICATION, WARNING and ERROR. ### What happens if the nRF Logger app is not installed on the device? The README states that if the nRF Logger application is not installed on the device those methods do nothing. Since version 2.0 you can instead extend the LocalLogContentProvider class and register it in the AndroidManifest.xml file to keep logs locally, though that provider supports only one application and no session marks or descriptions. ### Are there any known caveats in the nRF Logger API Timber integration? Yes. The log-timber library uses the androidx.annotation nullability annotations rather than the org.jetbrains.annotations ones Timber uses, Timber's levels do not map cleanly to nRF Logger's, APPLICATION level cannot be logged through the Timber API, verbose and debug priorities are upgraded and downgraded respectively, and tags are prefixed before the message unless you call tree.setLoggingTagsEnabled(false). ## Sources - [Issues](https://github.com/nordicsemi/nRF-Logger-API/issues) - [License: BSD-3-Clause](https://github.com/nordicsemi/nRF-Logger-API/blob/main/LICENSE) - [nordicsemi/nRF-Logger-API on GitHub](https://github.com/nordicsemi/nRF-Logger-API) - [README](https://github.com/nordicsemi/nRF-Logger-API/blob/main/README.md) - [Releases](https://github.com/nordicsemi/nRF-Logger-API/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nordicsemi-nrf-logger-api