Android Log Collection

Send logs to Datadog from your Android applications with Datadog’s dd-sdk-android client-side logging library and leverage the following features:

• Log to Datadog in JSON format natively.
• Add context and extra custom attributes to each log sent.
• Forward Java/Kotlin caught exceptions.
• Record real client IP addresses and User-Agents.
• Optimized network usage with automatic bulk posts.

Setup

1. Add the Gradle dependency by declaring the library as a dependency in the module-level build.gradle file:

   dependencies {
       implementation "com.datadoghq:dd-sdk-android:x.x.x"
   }
   

2. Initialize the library with your application context, tracking consent, and the Datadog client token and Application ID generated when you create a new RUM application in the Datadog UI (see Getting Started with Android RUM Collection for more information). For security reasons, you must use a client token: you cannot use Datadog API keys to configure the dd-sdk-android library as they would be exposed client-side in the Android application APK byte code. For more information about setting up a client token, see the client token documentation. The APP_VARIANT_NAME specifies the variant of the application that generates data.

    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            val configuration = Configuration.Builder(
                logsEnabled = true,
                tracesEnabled = true,
                crashReportsEnabled = true,
                rumEnabled = true
            ).build()
            val credentials = Credentials(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>, <APPLICATION_ID>)
            Datadog.initialize(this, credentials, configuration, trackingConsent)
        }
    }

    public class SampleApplication extends Application {
        @Override
        public void onCreate() {
            super.onCreate();
            Configuration configuration =
                    new Configuration.Builder(true, true, true, true)
                            .build();
            Credentials credentials = new Credentials( < CLIENT_TOKEN >, <ENV_NAME >, <APP_VARIANT_NAME >, <
            APPLICATION_ID >);
            Datadog.initialize(this, credentials, configuration, trackingConsent);
        }
    }

    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            val configuration = Configuration.Builder(
                    logsEnabled = true,
                    tracesEnabled = true,
                    crashReportsEnabled = true,
                    rumEnabled = true
                )
                .useSite(DatadogSite.EU1)
                .build()
            val credentials = Credentials(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>, <APPLICATION_ID>)
            Datadog.initialize(this, credentials, configuration, trackingConsent)
        }
    }

    public class SampleApplication extends Application {
        @Override
        public void onCreate() {
            super.onCreate();
            Configuration configuration =
                    new Configuration.Builder(true, true, true, true)
                            .useSite(DatadogSite.EU1)
                            .build();
            Credentials credentials = new Credentials( < CLIENT_TOKEN >, <ENV_NAME >, <APP_VARIANT_NAME >, <
            APPLICATION_ID >);
            Datadog.initialize(this, credentials, configuration, trackingConsent);
        }
    }

    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            val configuration = Configuration.Builder(
                    logsEnabled = true,
                    tracesEnabled = true,
                    crashReportsEnabled = true,
                    rumEnabled = true
                )
                .useSite(DatadogSite.US3)
                .build()
            val credentials = Credentials(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>, <APPLICATION_ID>)
            Datadog.initialize(this, credentials, configuration, trackingConsent)
        }
    }

    public class SampleApplication extends Application {
        @Override
        public void onCreate() {
            super.onCreate();
            Configuration configuration =
                    new Configuration.Builder(true, true, true, true)
                            .useSite(DatadogSite.US3)
                            .build();
            Credentials credentials = new Credentials( < CLIENT_TOKEN >, <ENV_NAME >, <APP_VARIANT_NAME >, <
            APPLICATION_ID >);
            Datadog.initialize(this, credentials, configuration, trackingConsent);
        }
    }

    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            val configuration = Configuration.Builder(
                    logsEnabled = true,
                    tracesEnabled = true,
                    crashReportsEnabled = true,
                    rumEnabled = true
                )
                .useSite(DatadogSite.US5)
                .build()
            val credentials = Credentials(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>, <APPLICATION_ID>)
            Datadog.initialize(this, credentials, configuration, trackingConsent)
        }
    }

    public class SampleApplication extends Application {
        @Override
        public void onCreate() {
            super.onCreate();
            Configuration configuration =
                    new Configuration.Builder(true, true, true, true)
                            .useSite(DatadogSite.US5)
                            .build();
            Credentials credentials = new Credentials( < CLIENT_TOKEN >, <ENV_NAME >, <APP_VARIANT_NAME >, <
            APPLICATION_ID >);
            Datadog.initialize(this, credentials, configuration, trackingConsent);
        }
    }

    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            val configuration = Configuration.Builder(
                    logsEnabled = true,
                    tracesEnabled = true,
                    crashReportsEnabled = true,
                    rumEnabled = true
                )
                .useSite(DatadogSite.US1_FED)
                .build()
            val credentials = Credentials(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>, <APPLICATION_ID>)
            Datadog.initialize(this, credentials, configuration, trackingConsent)
        }
    }

    public class SampleApplication extends Application {
        @Override
        public void onCreate() {
            super.onCreate();
            Configuration configuration =
                    new Configuration.Builder(true, true, true, true)
                            .useSite(DatadogSite.US1_FED)
                            .build();
            Credentials credentials = new Credentials( < CLIENT_TOKEN >, <ENV_NAME >, <APP_VARIANT_NAME >, <
            APPLICATION_ID >);
            Datadog.initialize(this, credentials, configuration, trackingConsent);
        }
    }

To be compliant with the GDPR regulation, the SDK requires the tracking consent value at initialization. The tracking consent can be one of the following values:

• TrackingConsent.PENDING: The SDK starts collecting and batching the data but does not send it to the data collection endpoint. The SDK waits for the new tracking consent value to decide what to do with the batched data.
• TrackingConsent.GRANTED: The SDK starts collecting the data and sends it to the data collection endpoint.
• TrackingConsent.NOT_GRANTED: The SDK does not collect any data. You will not be able to manually send any logs, traces, or RUM events.

To update the tracking consent after the SDK is initialized, call: Datadog.setTrackingConsent(<NEW CONSENT>). The SDK changes its behavior according to the new consent. For example, if the current tracking consent is TrackingConsent.PENDING and you update it to:

• TrackingConsent.GRANTED: The SDK sends all current batched data and future data directly to the data collection endpoint.
• TrackingConsent.NOT_GRANTED: The SDK wipes all batched data and does not collect any future data.

Note: In the credentials required for initialization, your application variant name is also required, and should use your BuildConfig.FLAVOR value (or an empty string if you don’t have variants). This is important because it enables the right ProGuard mapping.txt file to be automatically uploaded at build time to be able to view de-obfuscated RUM error stack traces. For more information see the guide to uploading Android source mapping files.

Use the utility method isInitialized to check if the SDK is properly initialized:

 if (Datadog.isInitialized()) {
     // your code here
 }

When writing your application, you can enable development logs by calling the setVerbosity method. All internal messages in the library with a priority equal to or higher than the provided level are then logged to Android’s Logcat:

Datadog.setVerbosity(Log.INFO)

3. Configure the Android Logger:

         val logger = Logger.Builder()
            .setNetworkInfoEnabled(true)
            .setLogcatLogsEnabled(true)
            .setDatadogLogsEnabled(true)
            .setBundleWithTraceEnabled(true)
            .setLoggerName("<LOGGER_NAME>")
            .build()
   

          final Logger logger = new Logger.Builder()
            .setNetworkInfoEnabled(true)
            .setLogcatLogsEnabled(true)
            .setDatadogLogsEnabled(true)
            .setBundleWithTraceEnabled(true)
            .setLoggerName("<LOGGER_NAME>")
            .build();
   

4. Send a custom log entry directly to Datadog with one of the following functions:

   logger.d("A debug message.")
   logger.i("Some relevant information ?")
   logger.w("An important warning…")
   logger.e("An error was met!")
   logger.wtf("What a Terrible Failure!")
   

5. Exceptions caught can be sent with a message:

        try { 
            doSomething() 
        } catch (e: IOException) {
            logger.e("Error while doing something", e) 
        }
   

        try {
            doSomething();
        } catch (IOException e) {
            logger.e("Error while doing something", e);
        }
   

   Note: All logging methods can have a throwable attached to them.

6. (Optional) - Provide a map alongside your log message to add attributes to the emitted log. Each entry of the map is added as an attribute.

        logger.i("onPageStarted", attributes = mapOf("http.url" to url))
   

        Map<String, Object> attributes = new HashMap<>();
        attributes.put("http.url", url);
        logger.i("onPageStarted", null, attributes);
   

7. If you need to modify some attributes in your Log events before batching you can do so by providing an implementation of EventMapper<LogEvent> when initializing the SDK:

        val config = Configuration.Builder(logsEnabled = true, ...)
                    // ...
                    .setLogEventMapper(logEventMapper)
                    .build()
   

        Configuration config = new Configuration.Builder(true, true, true, true)
                    // ...
                    .setLogEventMapper(logEventMapper)
                    .build();
   

   Note: If you return null or a different instance from the EventMapper<LogEvent> implementation the event will be dropped.

Advanced logging

Library initialization

The following methods in Configuration.Builder can be used when creating the Datadog Configuration to initialize the library:

Logger initialization

The following methods in Logger.Builder can be used when initializing the logger to send logs to Datadog:

Global configuration

Find below functions to add/remove tags and attributes to all logs sent by a given logger.

Global tags

Add tags

Use the addTag("<TAG_KEY>", "<TAG_VALUE>") function to add tags to all logs sent by a specific logger:

// This adds a tag "build_type:debug" or "build_type:release" accordingly
logger.addTag("build_type", BuildConfig.BUILD_TYPE)

// This adds a tag "device:android"
logger.addTag("device", "android")

Note: <TAG_VALUE> must be a String.

Remove tags

Use the removeTagsWithKey("<TAG_KEY>") function to remove tags from all logs sent by a specific logger:

// This removes any tag starting with "build_type"
logger.removeTagsWithKey("build_type")

Learn more about Datadog tags.

Global attributes

Add attributes

By default, the following attributes are added to all logs sent by a logger:

• http.useragent and its extracted device and OS properties
• network.client.ip and its extracted geographical properties (country, city)

Use the addAttribute("<ATTRIBUTE_KEY>", "<ATTRIBUTE_VALUE>") function to add a custom attribute to all logs sent by a specific logger:

// This adds an attribute "version_code" with an integer value
logger.addAttribute("version_code", BuildConfig.VERSION_CODE)

// This adds an attribute "version_name" with a String value
logger.addAttribute("version_name", BuildConfig.VERSION_NAME)

Note: <ATTRIBUTE_VALUE> can be any primitive, String, or Date.

Remove attributes

Use the removeAttribute("<ATTRIBUTE_KEY>", "<ATTRIBUTE_VALUE>") function to remove a custom attribute from all logs sent by a specific logger:

// This removes the attribute "version_code" from all further log send.
logger.removeAttribute("version_code")

// This removes the attribute "version_name" from all further log send.
logger.removeAttribute("version_name")

Batch collection

All the logs are first stored on the local device in batches. Each batch follows the intake specification. They are sent as soon as network is available, and the battery is high enough to ensure the Datadog SDK does not impact the end user’s experience. If the network is not available while your application is in the foreground, or if an upload of data fails, the batch is kept until it can be sent successfully.

This means that even if users open your application while being offline, no data will be lost.

The data on disk will automatically be discarded if it gets too old to ensure the SDK doesn’t use too much disk space.

Note: Before data is uploaded to Datadog, it is stored in cleartext in your application’s cache directory. This cache folder is protected by Android’s Application Sandbox, meaning that on most devices this data can’t be read by other applications. However, if the mobile device is rooted, or someone tempers with the Linux kernel, the stored data might become readable.

Extensions

Timber

If your existing codebase is using Timber, you can forward all those logs to Datadog automatically by using the dedicated library.

Further Reading

Additional helpful documentation, links, and articles:

dd-sdk-android Source codeGITHUB Learn how to explore your logsDOCUMENTATION