Automatic instrumentation

Stack Serverless Observability EDOT Android

The SDK 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 the agent the same way you would without using automatic instrumentation.

Automatic instrumentations will get installed during the SDK 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, the agent 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, the EDOT agent installs this extra plugin on your behalf, so there's no need for you to do so manually.