Automatic instrumentation for Android with EDOT SDK

Serverless Observability Stack EDOT Android

EDOT Android can automatically generate telemetry on your behalf. This allows you to get telemetry data for supported targets without having to write manual instrumentation.

All automatic instrumentations are opt-in. Therefore, you have to install the ones you want to use. Specific targets are supported for automatic instrumentation, each with its own Gradle plugin for installation.

To install a supported automatic instrumentation, follow these steps:

1. Choose a supported instrumentation.
2. Add its Gradle plugin to your project in the same location where the agent is added.
3. Initialize EDOT Android the same way you would without using automatic instrumentation.

Automatic instrumentations will get installed during EDOT Android's initialization.

Some automatic instrumentations perform bytecode instrumentation, also known as bytecode weaving, where your application's code, including code from the libraries it uses, is modified at compile-time. This is similar to what isMinifyEnabled does with R8 functionalities, automating code changes that you would otherwise need to make manually.

Bytecode instrumentation is a common technique which may already be used in your project for use cases such as code optimization through R8. While useful, bytecode instrumentation can make compilation take longer to complete. Because of this, EDOT Android provides a way to exclude specific build types in your app from byte code changes.

For large projects, you can avoid the added compilation time caused by the compilation behavior by excluding build types that don't need the functionality.

Use the following configuration to exclude build types:

// Your app's build.gradle.kts file
plugins {
    // ...
    id("co.elastic.otel.android.agent")
}

// ...

elasticAgent {
    bytecodeInstrumentation.disableForBuildTypes.set(listOf("debug"))
}
		

1. By default, the disableForBuildTypes list is empty. Add any build type names for which you want to turn off byte code instrumentation.

The following automatic instrumentations are supported.

Creates spans for outgoing HTTP requests that are made using the OkHttp library. This also includes tools that rely on OkHttp to work, such as Retrofit.

plugins {
    id("co.elastic.otel.android.instrumentation.okhttp") version "[latest_version]"
}
		

1. You can find the latest version here.

You can use any instrumentation from the OpenTelemetry Android available instrumentations through the OTel instrumentation adapter gradle plugin. The adapter is an extended component.

Add the OTel Android instrumentation adapter by including it in your app's plugins block. This is the same block where the agent's plugin should also be added.

plugins {
    id("co.elastic.otel.android.instrumentation.oteladapter") version "[latest_version]"
}
		

1. To find the latest version, refer to the plugin portal.

After including the adapter in your project, choose an instrumentation from this list and follow the installation instructions from its README file.

For example, consider the HttpURLConnection instrumentation, which automatically instruments HTTP requests made with HttpURLConnection.

To have it fully installed, your app's build.gradle.kts file should look like this:

plugins {
    // ...
    id("co.elastic.otel.android.instrumentation.oteladapter")
}

// ...

dependencies {
    // ...
    implementation("io.opentelemetry.android.instrumentation:httpurlconnection-library:AUTO_HTTP_URL_INSTRUMENTATION_VERSION")
    byteBuddy("io.opentelemetry.android.instrumentation:httpurlconnection-agent:AUTO_HTTP_URL_INSTRUMENTATION_VERSION")
}
		

1. Make sure the adapter is added.
2. You can find the dependencies needed in the instrumentation's README file. The same will be the case for any other instrumentation.
3. The instrumentations that require a byteBuddy dependency, do bytecode weaving, as explained in compilation behavior. An extra plugin named net.bytebuddy.byte-buddy-gradle-plugin is required to make this work, as shown here. However, EDOT Android installs this extra plugin on your behalf, so there's no need for you to do so manually.

As explained in compilation behavior, the instrumentations that perform bytecode weaving might increase the compilation times. Because of this, EDOT Android provides a configuration param that allows to select specific build types for which the bytecode instrumentation will be turned off. This configuration only works for EDOT Android's supported instrumentations, so it won't have any effect on instrumentations added through the OTel Android instrumentations adapter.

To select the build variant to run the bytecode instrumentation for an OTel Android instrumentation, you must add its byteBuddy dependency using the variant-specific byteBuddy name, such as releaseByteBuddy or debugByteBuddy, depending on which variant you'd like to enable the bytecode instrumentation for.

Following the previous example, if you want to install the HttpURLConnection instrumentation only for your app's release build type, you can change the way we add its byteBuddy dependency as shown here:

dependencies {
    // ...
    releaseByteBuddy("io.opentelemetry.android.instrumentation:httpurlconnection-agent:AUTO_HTTP_URL_INSTRUMENTATION_VERSION")
}
		

1. Will only install the instrumentation for the release build type of the app, avoiding to increase the compilation time for other types, such as debug, for example.