AWS Open Distro for OpenTelemetry

Tracing with the AWS Distro for OpenTelemetry Java Auto-Instrumentation and X-Ray

Tracing with the AWS Distro for OpenTelemetry Java Auto-Instrumentation and X-Ray


The AWS Distro for OpenTelemetry (ADOT) Java Auto-Instrumentation Agent can be attached to any Java 8+ application to gather telemetry data from a diverse set of libraries and frameworks. The agent will automatically transform code at startup to collect tracing data. It is preconfigured for compatibility with X-Ray and AWS services but can also be used with any other tracing backend. Out of the box, it propagates traces using all of W3C Trace Context, B3, and X-Amzn-Trace-Id.


Java 8 (or later) is required to run an application using OpenTelemetry.

Note: You’ll also need to have the ADOT Collector running to export traces to X-Ray.


Download the latest version.

If you'd prefer to pin to a specific version, check out our releases.

Running an Application with Auto-Instrumentation

To run your app with the agent, specify the -javaagent flag when starting up your application, pointing to the downloaded agent Java Archive (JAR) artifact. In addition, while not required by the agent itself, almost all tracing systems require a service name and service namespace defined to identify your application, which you can specify with the OTEL_RESOURCE_ATTRIBUTES environment variable and / service.namespace attribute keys.,service.namespace=MyTeam java -javaagent:path/to/aws-opentelemetry-agent.jar -jar myapp.jar

Note: Like normal system properties, the -javaagent flag must come before -jar or your main class name.

The above command will start up your app with the agent activated, and instrumentation is then activated automatically. For many cases, this is all you need to use tracing.

Configuring Auto-Instrumentation

By default OpenTelemetry Java agent uses the OTLP exporter and is configured to send data to a OpenTelemetry collector at http://localhost:4317.

The agent can be configured using standard OpenTelemetry options for configuration. For example, to set the random sampling rate for creating traces, you can set the environment variables OTEL_TRACES_SAMPLER=parentbased_traceidratio and OTEL_TRACES_SAMPLER_ARG=0.3 to configure a sampling rate of 30%.

Using X-Ray Remote Sampling

The ADOT Java Auto-Instrumentation Agent can be configured to use X-Ray remote sampling by setting the environment variable OTEL_TRACES_SAMPLER=xray. You will also need to configure the OpenTelemetry collector to allow the application to fetch sampling configuration. By default the sampler sends requests to http://localhost:2000. By setting OTEL_TRACES_SAMPLER_ARG environment variable you can change the endpoint the sampler talks with when getting sampling configuration from AWS X-Ray Console. For example setting OTEL_TRACES_SAMPLER_ARG=endpoint=http://localhost:4000 would configure the sampler to communicate with http://localhost:4000.

Running the agent in Docker

If your application is packaged in Docker, the easiest way to run with the agent is to use the JAVA_TOOL_OPTIONS environment variable, which automatically sets flags for Java. Adding this snippet to your Dockerfile will typically be enough to enable tracing, although if you already set JAVA_TOOL_OPTIONS, don't forget to make sure to add to your existing setting rather than replacing it.

ADD /opt/aws-opentelemetry-agent.jar
ENV JAVA_TOOL_OPTIONS=-javaagent:/opt/aws-opentelemetry-agent.jar

Using Manual Instrumentation

While the Java agent provides automatic instrumentation for popular frameworks, you might find the need to perform instrumentation in your application, for example, to provide custom data or to instrument code within the application itself.

To perform manual instrumentation alongside the agent, you only need to use the opentelemetry-api aritfact. The version of this artifact can not be newer than the version of the agent. Notably, you do not need the opentelemetry-sdk artifact, any usage of it will be disabled by the agent.

For Gradle:
1dependencies {
2 implementation("io.opentelemetry:opentelemetry-api:1.6.0")
For Maven:
2 <dependency>
3 <groupId>io.opentelemetry</groupId>
4 <artifactId>opentelemetry-api</artifactId>
5 <version>1.6.0</version>
6 </dependency>

See the document on manual instrumentation for more detail on using the OpenTelemetry API.

Sample Application

Visit the Sample Spring App using OpenTelemetry Java Auto-Instrumentation.