Tracing Android Applications
Send traces to Datadog from your Android applications with Datadog’s dd-sdk-android-trace client-side tracing library and leverage the following features:
- Create custom spans for operations in your application.
- Add
context and extra custom attributes to each span sent. - Optimized network usage with automatic bulk posts.
Note: Datadog charges for
ingested and indexed spans sent from your Android applications, but does not charge for the underlying devices. Read more in the
APM billing documentation.
Setup
- Add the Gradle dependency by declaring the library as a dependency in your
build.gradle file:
dependencies {
implementation "com.datadoghq:dd-sdk-android-trace:x.x.x"
}
Initialize Datadog SDK with your application context, tracking consent, and the Datadog client token. For security reasons, you must use a client token: you cannot use Datadog API keys to configure Datadog SDK 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()
val configuration = Configuration.Builder(
clientToken = <CLIENT_TOKEN>,
env = <ENV_NAME>,
variant = <APP_VARIANT_NAME>
).build()
Datadog.initialize(this, configuration, trackingConsent)
}
}
public class SampleApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
Configuration configuration =
new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
.build();
Datadog.initialize(this, configuration, trackingConsent);
}
}
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val configuration = Configuration.Builder(
clientToken = <CLIENT_TOKEN>,
env = <ENV_NAME>,
variant = <APP_VARIANT_NAME>
)
.useSite(DatadogSite.EU1)
.build()
Datadog.initialize(this, configuration, trackingConsent)
}
}
public class SampleApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
Configuration configuration =
new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
.useSite(DatadogSite.EU1)
.build();
Datadog.initialize(this, configuration, trackingConsent);
}
}
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val configuration = Configuration.Builder(
clientToken = <CLIENT_TOKEN>,
env = <ENV_NAME>,
variant = <APP_VARIANT_NAME>
)
.useSite(DatadogSite.US3)
.build()
Datadog.initialize(this, configuration, trackingConsent)
}
}
public class SampleApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
Configuration configuration =
new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
.useSite(DatadogSite.US3)
.build();
Datadog.initialize(this, configuration, trackingConsent);
}
}
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val configuration = Configuration.Builder(
clientToken = <CLIENT_TOKEN>,
env = <ENV_NAME>,
variant = <APP_VARIANT_NAME>
)
.useSite(DatadogSite.US5)
.build()
Datadog.initialize(this, configuration, trackingConsent)
}
}
public class SampleApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
Configuration configuration =
new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
.useSite(DatadogSite.US5)
.build();
Datadog.initialize(this, configuration, trackingConsent);
}
}
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val configuration = Configuration.Builder(
clientToken = <CLIENT_TOKEN>,
env = <ENV_NAME>,
variant = <APP_VARIANT_NAME>
)
.useSite(DatadogSite.US1_FED)
.build()
Datadog.initialize(this, configuration, trackingConsent)
}
}
public class SampleApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
Configuration configuration =
new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
.useSite(DatadogSite.US1_FED)
.build();
Datadog.initialize(this, configuration, trackingConsent);
}
}
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val configuration = Configuration.Builder(
clientToken = <CLIENT_TOKEN>,
env = <ENV_NAME>,
variant = <APP_VARIANT_NAME>
)
.useSite(DatadogSite.AP1)
.build()
Datadog.initialize(this, configuration, trackingConsent)
}
}
public class SampleApplication extends Application {
@Override
public void onCreate() {
super.onCreate();
Configuration configuration =
new Configuration.Builder(<CLIENT_TOKEN>, <ENV_NAME>, <APP_VARIANT_NAME>)
.useSite(DatadogSite.AP1)
.build();
Datadog.initialize(this, 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)
Configure and enable Trace feature:
val traceConfig = TraceConfiguration.Builder().build()
Trace.enable(traceConfig)
TraceConfiguration traceConfig = TraceConfiguration.Builder().build();
Trace.enable(traceConfig);
Configure and register the Android Tracer. You only need to do it once, usually in your application’s onCreate() method:
val tracer = AndroidTracer.Builder().build()
GlobalTracer.registerIfAbsent(tracer)
AndroidTracer tracer = new AndroidTracer.Builder().build();
GlobalTracer.registerIfAbsent(tracer);
- (Optional) - Set the partial flush threshold. You can optimize the workload of the SDK if you create a lot of spans in your application, or on the contrary very few of them. The library waits until the number of finished spans gets above the threshold to write them on disk. A value of
1 writes each span as soon as its finished.
val tracer = AndroidTracer.Builder()
.setPartialFlushThreshold(10)
.build()
AndroidTracer tracer = new AndroidTracer.Builder()
.setPartialFlushThreshold(10)
.build();
- Start a custom span using the following method:
val tracer = GlobalTracer.get()
val span = tracer.buildSpan("<SPAN_NAME>").start()
// Do something ...
// ...
// Then when the span should be closed
span.finish()
GlobalTracer tracer = GlobalTracer.get();
Span span = tracer.buildSpan("<SPAN_NAME>").start();
// Do something ...
// ...
// Then when the span should be closed
span.finish();
- To use scopes in synchronous calls:
val span = tracer.buildSpan("<SPAN_NAME1>").start()
try {
val scope = tracer.activateSpan(span)
scope.use {
// Do something ...
// ...
// Start a new Scope
val childSpan = tracer.buildSpan("<SPAN_NAME2>").start()
try {
tracer.activateSpan(childSpan).use {
// Do something ...
}
} catch(e: Error) {
childSpan.error(e)
} finally {
childSpan.finish()
}
}
} catch(e: Throwable) {
AndroidTracer.logThrowable(span, e)
} finally {
span.finish()
}
Span = tracer.buildSpan("<SPAN_NAME1>").start();
try {
Scope scope = tracer.activateSpan(span);
try {
// Do something ...
// ...
// Start a new Scope
Span childSpan = tracer.buildSpan("<SPAN_NAME2>").start();
try {
Scope innerScope = tracer.activateSpan(childSpan);
try {
// Do something ...
} finally {
innerScope.close();
}
} catch(Throwable e) {
AndroidTracer.logThrowable(childSpan, e);
} finally {
childSpan.finish();
}
}
finally {
scope.close();
}
} catch(Error e) {
AndroidTracer.logThrowable(span, e);
} finally {
span.finish();
}
To use scopes in asynchronous calls:
val span = tracer.buildSpan("<SPAN_NAME1>").start()
try{
val scope = tracer.activateSpan(span)
scope.use {
// Do something ...
doAsyncWork {
// Step 2: reactivate the Span in the worker thread
val scopeContinuation = tracer.scopeManager().activate(span)
scopeContinuation.use {
// Do something ...
}
}
}
} catch(e: Throwable) {
AndroidTracer.logThrowable(span, e)
} finally {
span.finish()
}
Span span = tracer.buildSpan("<SPAN_NAME1>").start();
try {
Scope scope = tracer.activateSpan(span);
try {
// Do something ...
new Thread(() -> {
// Step 2: reactivate the Span in the worker thread
Scope scopeContinuation = tracer.scopeManager().activate(span);
try {
// Do something
} finally {
scope.close();
}
}).start();
} finally {
scope.close();
}
} catch (Throwable e){
AndroidTracer.logThrowable(span, e);
} finally {
span.finish();
}
(Optional) To manually distribute traces between your environments, for example frontend to backend:
a. Inject tracer context in the client request.
val tracer = GlobalTracer.get()
val span = tracer.buildSpan("<SPAN_NAME>").start()
val tracedRequestBuilder = Request.Builder()
tracer.inject(span.context(), Format.Builtin.TEXT_MAP_INJECT,
TextMapInject { key, value ->
tracedRequestBuilder.addHeader(key, value)
}
)
val request = tracedRequestBuilder.build()
// Dispatch the request and finish the span after.
Tracer tracer = GlobalTracer.get();
Span span = tracer.buildSpan("<SPAN_NAME>").start();
Request.Builder tracedRequestBuilder = new Request.Builder();
tracer.inject(
span.context(),
Format.Builtin.TEXT_MAP_INJECT,
new TextMapInject() {
@Override
public void put(String key, String value) {
tracedRequestBuilder.addHeader(key, value);
}
});
Request request = tracedRequestBuilder.build();
// Dispatch the request and finish the span after
b. Extract the client tracer context from headers in server code.
val tracer = GlobalTracer.get()
val extractedContext = tracer.extract(
Format.Builtin.TEXT_MAP_EXTRACT,
TextMapExtract {
request.headers().toMultimap()
.map { it.key to it.value.joinToString(";") }
.toMap()
.entrySet()
.iterator()
}
)
val serverSpan = tracer.buildSpan("<SERVER_SPAN_NAME>").asChildOf(extractedContext).start()
Tracer tracer = GlobalTracer.get();
SpanContext extractedContext = tracer.extract(
Format.Builtin.TEXT_MAP_EXTRACT,
new TextMapExtract() {
@Override
public Iterator<Map.Entry<String, String>> iterator() {
return request.headers().toMultimap()
.entrySet()
.stream()
.collect(
Collectors.toMap(
Map.Entry::getKey,
entry -> String.join(";", entry.getValue())
)
)
.entrySet()
.iterator();
}
});
Span serverSpan = tracer.buildSpan("<SERVER_SPAN_NAME>").asChildOf(extractedContext).start();
Note: For code bases using the OkHttp client, Datadog provides the implementation below.
- (Optional) To provide additional tags alongside your span:
span.setTag("http.url", url)
- (Optional) To mark a span as having an error, log it using OpenTracing tags:
span.log(mapOf(Fields.ERROR_OBJECT to throwable))
span.log(mapOf(Fields.MESSAGE to errorMessage))
You can also use one of the following helper method in AndroidTracer:
AndroidTracer.logThrowable(span, throwable)
AndroidTracer.logErrorMessage(span, message)
- If you need to modify some attributes in your Span events before batching you can do so by providing an implementation of
SpanEventMapper when enabling Trace feature:
val traceConfig = TraceConfiguration.Builder()
// ...
.setEventMapper(spanEventMapper)
.build()
TraceConfiguration config = new TraceConfiguration.Builder()
// ...
.setEventMapper(spanEventMapper)
.build();
Kotlin Extensions
Running a lambda within a Span
To monitor the performance of a given lambda, you can use the withinSpan() method. By default, a scope will be created for the span, but you can disable this behavior by setting the activate parameter to false.
withinSpan("<SPAN_NAME>", parentSpan, activate) {
// Your code here
}
Span extension methods
You can mark a span as having an error using one of the following error() methods.
val span = tracer.buildSpan("<SPAN_NAME>").start()
try {
// …
} catch (e: IOException) {
span.setError(e)
}
span.finish()
val span = tracer.buildSpan("<SPAN_NAME>").start()
if (invalidState) {
span.setError("Something unexpected happened")
}
span.finish()
Tracing SQLite transaction
If you are using SQLiteDatabase to persist data locally, you can trace the database transaction using the following method:
sqliteDatabase.transactionTraced("<SPAN_NAME>", isExclusive) { database ->
// Your queries here
database.insert("<TABLE_NAME>", null, contentValues)
// Decorate the Span
setTag("<TAG_KEY>", "<TAG_VALUE>")
}
It behaves like the SQLiteDatabase.transaction method provided in the core-ktx AndroidX package and only requires a span operation name.
Integrations
In addition to manual tracing, the Datadog SDK provides the following integrations.
OkHttp
If you want to trace your OkHttp requests, you can add the provided Interceptor (which can be found in the dd-sdk-android-okhttp library) as follows:
Add the Gradle dependency to the dd-sdk-android-okhttp library in the module-level build.gradle file:
dependencies {
implementation "com.datadoghq:dd-sdk-android-okhttp:x.x.x"
}
Add DatadogInterceptor to your OkHttpClient:
val okHttpClient = OkHttpClient.Builder()
.addInterceptor(
DatadogInterceptor(listOf("example.com", "example.eu"), traceSampler = RateBasedSampler(20f))
)
.build()
OkHttpClient okHttpClient = new OkHttpClient.Builder()
.addInterceptor(
new DatadogInterceptor(Arrays.asList("example.com", "example.eu"), RateBasedSampler(20f))
)
.build();
This creates a span around each request processed by the OkHttpClient (matching the provided hosts), with all the relevant information automatically filled (URL, method, status code, error), and propagates the tracing information to your backend to get a unified trace within Datadog.
Network traces are sampled with an adjustable sampling rate. A sampling of 20% is applied by default.
The interceptor tracks requests at the application level. You can also add a TracingInterceptor at the network level to get more details, for example when following redirections.
val tracedHosts = listOf("example.com", "example.eu")
val okHttpClient = OkHttpClient.Builder()
.addInterceptor(DatadogInterceptor(tracedHosts, traceSampler = RateBasedSampler(20f)))
.addNetworkInterceptor(TracingInterceptor(tracedHosts, traceSampler = RateBasedSampler(20f)))
.build()
final List<String> tracedHosts = Arrays.asList("example.com", "example.eu");
final OkHttpClient okHttpClient = new OkHttpClient.Builder()
.addInterceptor(new DatadogInterceptor(tracedHosts, RateBasedSampler(20f)))
.addNetworkInterceptor(new TracingInterceptor(tracedHosts, RateBasedSampler(20f)))
.build();
In this case trace sampling decision made by the upstream interceptor for a particular request will be respected by the downstream interceptor.
Because the way the OkHttp Request is executed (using a Thread pool), the request span won’t be automatically linked with the span that triggered the request. You can manually provide a parent span in the OkHttp Request.Builder as follows by using Request.Builder.parentSpan extension method:
val request = Request.Builder()
.url(requestUrl)
.parentSpan(parentSpan)
.build()
Request.Builder requestBuilder = new Request.Builder()
.url(requestUrl)
Request request = OkHttpRequestExtKt
.parentSpan(requestBuilder, parentSpan)
.build();
Note:
- If you use multiple Interceptors, this one must be called first.
- If you define custom tracing header types in the Datadog configuration and are using a tracer registered with
GlobalTracer, make sure the same tracing header types are set for the tracer in use.
RxJava
To provide a continuous trace inside a RxJava stream you need to follow the steps below:
- Add the OpenTracing for RxJava dependency into your project and follow the Readme file
for instructions. For example for a continuous trace you just have to add:
TracingRxJava3Utils.enableTracing(GlobalTracer.get())
- Then in your project open a scope when the Observable is subscribed and close it when it completes. Any span
created inside the stream operators will be displayed inside this scope (parent Span):
var spanScope: Scope? = null
Single.fromSupplier { }
.subscribeOn(Schedulers.io())
.map {
val span = GlobalTracer.get().buildSpan("<YOUR_OP_NAME>").start()
// ...
span.finish()
}
.doOnSubscribe {
val span = GlobalTracer.get()
.buildSpan("<YOUR_OP_NAME>")
.start()
spanScope = GlobalTracer.get().scopeManager().activate(span)
}
.doFinally {
GlobalTracer.get().scopeManager().activeSpan()?.let {
it.finish()
}
spanScope?.close()
}
ThreadLocal<Scope> scopeStorage = new ThreadLocal<>();
...
Single.fromSupplier({})
.subscribeOn(Schedulers.io())
.map(data -> {
final Span span = GlobalTracer.get().buildSpan("<YOUR_OP_NAME>").start();
// ...
span.finish();
// ...
})
.doOnSubscribe(disposable -> {
final Span span = GlobalTracer.get().buildSpan("<YOUR_OP_NAME>").start();
Scope spanScope = GlobalTracer.get().scopeManager().activate(span);
scopeStorage.set(spanScope);
})
.doFinally(() -> {
final Span activeSpan = GlobalTracer.get().scopeManager().activeSpan();
if (activeSpan != null) {
activeSpan.finish();
}
Scope spanScope = scopeStorage.get();
if (spanScope != null) {
spanScope.close();
scopeStorage.remove();
}
})
};
RxJava + Retrofit
For a continuous trace inside a RxJava stream that uses Retrofit for the network requests:
- Configure the Datadog Interceptor
- Use the Retrofit RxJava adapters to use synchronous Observables for the network requests:
Retrofit.Builder()
.baseUrl("<YOUR_URL>")
.addCallAdapterFactory(RxJava3CallAdapterFactory.createSynchronous())
.client(okHttpClient)
.build()
new Retrofit.Builder()
.baseUrl("<YOUR_URL>")
.addCallAdapterFactory(RxJava3CallAdapterFactory.createSynchronous())
.client(okHttpClient)
.build();
- Open a scope around your Rx stream as follows:
var spanScope: Scope? = null
remoteDataSource.getData(query)
.subscribeOn(Schedulers.io())
.map { // ... }
.doOnSuccess {
localDataSource.persistData(it)
}
.doOnSubscribe {
val span = GlobalTracer.get().buildSpan("<YOUR_OP_NAME>").start()
spanScope = GlobalTracer.get().scopeManager().activate(span)
}
.doFinally {
GlobalTracer.get().scopeManager().activeSpan()?.let {
it.finish()
}
spanScope?.close()
}
ThreadLocal<Scope> scopeStorage = new ThreadLocal<>();
...
remoteDataSource.getData(query)
.subscribeOn(Schedulers.io())
.map(data -> { // ... })
.doOnSuccess(data -> {
localDataSource.persistData(data);
})
.doOnSubscribe(disposable -> {
final Span span = GlobalTracer.get().buildSpan("<YOUR_OP_NAME>").start();
Scope spanScope = GlobalTracer.get().scopeManager().activate(span);
scopeStorage.set(spanScope);
})
.doFinally(() -> {
final Span activeSpan = GlobalTracer.get().scopeManager().activeSpan();
if (activeSpan != null) {
activeSpan.finish();
}
Scope spanScope = scopeStorage.get();
if (spanScope != null) {
spanScope.close();
scopeStorage.remove();
}
});
Batch collection
All the spans 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.
Initialization
The following methods in AndroidTracer.Builder can be used when initializing the Tracer:
| Method | Description |
|---|
setService(<SERVICE_NAME>) | Set the value for the service. |
setPartialFlushThreshold(<INT>) | When this threshold is reached (you have a specific <INT> amount of spans closed waiting), the flush mechanism is triggered and all pending closed spans are processed and sent to intake. |
addTag(<KEY>, <VALUE>) | Set a <KEY>:<VALUE> pair of tags to be added to spans created by the Tracer. |
setBundleWithRumEnabled(true) | Set to true to enable spans to be enriched with the current RUM View information. This enables you to see all of the spans produced during a specific View lifespan in the RUM Explorer. |
setSampleRate(<FLOAT>) | Set a value 0-100 to define the percentage of Traces to collect. |
setTracingHeaderTypes(Set<TracingHeaderType>) | Sets the tracing header styles that may be injected by the Tracer. |
Further Reading
Additional helpful documentation, links, and articles:
