Network Performance Monitoring is now generally available! Network Monitoring is now available!

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.

Note: The dd-sdk-android library supports all Android versions from API level 21 (Lollipop).

Setup

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

    repositories {
        maven { url "https://dl.bintray.com/datadog/datadog-maven" }
    }
    
    dependencies {
        implementation "com.datadoghq:dd-sdk-android:x.x.x"
    }
  2. Initialize the library with your application context and your Datadog client token. 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:

    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            Datadog.initialize(this, BuildConfig.DD_CLIENT_TOKEN)
        }
    }
    class SampleApplication : Application() {
        override fun onCreate() {
            super.onCreate()
            Datadog.initialize(this, BuildConfig.DD_CLIENT_TOKEN, Datadog.DATADOG_EU)
        }
    }
  3. Configure the Android Logger:

    val logger = Logger.Builder()
        .setNetworkInfoEnabled(true)
        .setServiceName("<SERVICE_NAME>")
        .setLogcatLogsEnabled(true)
        .setDatadogLogsEnabled(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!")

    Exceptions caught can be sent with a message:

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

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

  5. (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", url))

    In java you would have:

    Logger.d(
            "onPageStarted",
            null,
            new HashMap<String, Object>() {{
                put("http.url", url);
            }}
    );

Advanced logging

Initialization

The following parameters can be used when initializing the logger to send logs to Datadog:

MethodDescription
setNetworkInfoEnabled(true)Add network.client.connectivity attribute to all log. The data logged by default is connectivity (Wifi, 3G, 4G…) and carrier_name (AT&T - US). Carrier_name is only available for Android API level 28 and above.
setServiceName(<SERVICE_NAME>)Set <SERVICE_NAME> as value for the service standard attribute attached to all logs sent to Datadog.
setLogcatLogsEnabled(true)Set to true to use Logcat as logger.
setDatadogLogsEnabled(true)Set to true to send logs to Datadog.
setLoggerName(<LOGGER_NAME>)Set <LOGGER_NAME> as the value for the logger.name attribute attached to all logs sent to Datadog.
setVerbosity(Log.INFO)Set the verbosity of the logger. All internal messages in the library with a priority equal or higher than the provided level will be logged to Android’s Logcat.
build()Build a new logger instance with all options set.

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")

Further Reading

Additional helpful documentation, links, and articles: