DOCSEARCHbyAlgolia
Submit Docs

nRF Logger API

repository·main·Indexed 19 days ago

https://github.com/nordicsemi/nrf-logger-api

A library for Android applications to create custom log entries viewable within the nRF Logger application, providing a debugging alternative to LogCat. It supports session management via the Logger class, integration with Timber through the log-timber dependency, and local log persistence using LocalLogContentProvider for devices without the nRF Logger app installed.

Tokens
1.2K
Snippets
5
Records
6
Agent score
18%

What's inside nrf-logger-api

  1. Migrate to ILogSession for version 2.0+

    main
    In version 2.0, the library introduced the ILogSession interface. Both LogSession and LocalLogSession implement this interface. To ensure compatibility with both standard and local logging, you should change the type of your session variable to ILogSession.

  2. Obtain the latest nRF Logger Library via Maven Central

    main

    To ensure you are using the most up-to-date version of the nRF Logger library, do not use the JAR files included directly in this repository. Instead, configure your build tool (Maven or Gradle) to fetch the library from Maven Central.

    <!-- Example Maven dependency configuration -->
<dependency>
    <groupId>com.nordicsemi.android</groupId>
    <artifactId>nrf-logger-api</artifactId>
    <version>2.5.0</version>
</dependency>

  3. Install the nRF Logger Library

    main

    Add the nRF Logger dependency to your build.gradle file.

    For AndroidX projects: Use the standard library:

    implementation 'no.nordicsemi.android:log:2.5.0'

    For non-AndroidX projects: Use version 2.2.0.

    ProGuard configuration: If you use ProGuard, the following rule is automatically added, but ensure it is present to prevent obfuscation of the logger classes:

  4. Integrate with Timber

    main

    For easy integration with Timber, use the log-timber dependency. After importing, you must plant the nRFLoggerTree.

    Dependency:

    implementation 'no.nordicsemi.android:log-timber:2.5.0'

    Important Integration Notes:

    • Annotations: log-timber uses androidx.annotation (@NonNull/@Nullable) instead of org.jetbrains.annotations.
    • Log Level Mismatch: Timber's log levels are incompatible with nRF Logger. Specifically, the APPLICATION level is missing in Timber.
    • Priority Mapping:
      • Log.VERBOSE is upgraded to VERBOSE level.
      • Log.DEBUG is downgraded to DEBUG level.
    • Tagging: By default, tags are prepended to messages as [TAG] message. To disable this, use tree.setLoggingTagsEnabled(false) (available since version 2.5).

  5. Use LocalLogContentProvider to keep logs without nRF Logger app

    main

    The LocalLogContentProvider allows you to persist logs even if the nRF Logger application is not installed on the device. This uses a local database limited to a single application.

    Limitations:

    • Does not support multiple applications.
    • Does not support marking sessions with flags/stars or adding descriptions.

    Setup:

    1. Extend the LocalLogContentProvider class in your project.
    2. Register your implementation in AndroidManifest.xml:
    <provider
    android:name="com.example.log.provider.MyLogContentProvider"
    android:authorities="com.example.log"
    android:exported="true" />

    Note on Permissions: If you need to log from threads owned by other applications (e.g., Bluetooth scanner callbacks), you must set android:exported="true" so the external application has permission to add log events.

  6. Create and manage log sessions

    main

    Use the Logger class to manage log sessions. If the nRF Logger application is not installed on the device, these methods will do nothing.

    Creating a session:

    • Basic session: Logger.newSession(context, key, name)
    • Session with profile: Logger.newSession(context, "Profile Name", key, name). This creates a folder in nRF Logger by concatenating the profile name with the application name.

    Parameters:

    • key: A non-null string used to group log sessions from the same day together.
    • name: The title shown in the UI. If null, "No name" is displayed.

    Session Metadata:

    • Add a description: Logger.setSessionDescription(logSession, "This is a comment")
    • Mark a session: Logger.setSessionMark(logSession, Logger.MARK_FLAG_RED)
    // Create a session
logSession = Logger.newSession(context, key, name);

// Add entries
Logger.log(logSession, Level.INFO, text);
Logger.e(logSession, R.string.error, someArg);

// Add metadata
Logger.setSessionDescription(logSession, "This is a comment");
Logger.setSessionMark(logSession, Logger.MARK_FLAG_RED);