Automatic instrumentation

The agent has an opt-in functionality that automatically generates telemetry on your behalf. This allows you to get telemetry data for supported targets without having to write manual instrumentation.

Install the automatic instrumentations you'd like 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 agent initialization without having to write extra code.

You can use instrumentations from OpenTelemetry Android with the Elastic agent. Learn how to do so here.

Some automatic instrumentations perform "byte code instrumentation" (also called byte code weaving), where your application's code (including code from the libraries it uses) is modified at compile-time. This automates code changes that you would otherwise need to make manually.

Byte code instrumentation is a common technique which may already be used in your project for use cases such as code optimization through R8. While useful, code 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, similar to what isMinifyEnabled does with R8 functionalities.

For some large projects (including dependencies), 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 do so:

// 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 disable byte code instrumentation.

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.

Component type: extended

If there's an instrumentation that you can't find in supported instrumentations, you can instead search for it in the OpenTelemetry Android available instrumentations and use it with the Elastic agent via its OTel instrumentation adapter by following the steps below.

The OTel Android instrumentation adapter is a Gradle plugin, which you can find here. To add it to your project, include it in your app's plugins block—the same block where the agent's plugin should also be added, as shown below:

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

1. You can find the latest version here.

OTel Android instrumentations are designed to work independently of the OTel Android agent. This is why they can be used not only with the Elastic agent but also with any other agent based on OpenTelemetry Java.

With that in mind, after including the adapter in your project, you can install any OTel Android instrumentation by following its installation instructions from its README file, just as you would if you were using the OTel Android agent.

For example, let's install the HttpURLConnection instrumentation, which automatically instruments HTTP requests made with HttpURLConnection.

• First, ensure that the adapter is added to your project.
• Next, refer to the HttpURLConnection instrumentation README for instructions on how to include it in your project.
• Finally, follow those instructions, which usually involve adding one or more Gradle dependencies. Once those dependencies are in place, the adapter will take care of the rest.

Based on the above, 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. More info here.
2. You can find the latest versions in the official instructions for this instrumentation here.

And that's it! Now the Elastic agent will use the HttpURLConnection instrumentation to automatically instrument those kinds of HTTP requests on your behalf.