Auto-Instrumentation for Traces and Metrics with the Java agent

Introduction

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.

Requirements

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.

Installation

Download the latest version.

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

The ADOT Java Agent is also published in the following maven coordinates:

Copy
1dependencies {
2    implementation("software.amazon.opentelemetry:aws-opentelemetry-agent:1.32.5")
3}

Copy
1<dependencies>
2  <dependency>
3      <groupId>software.amazon.opentelemetry</groupId>
4      <artifactId>aws-opentelemetry-agent</artifactId>
5      <version>1.32.5</version>
6  </dependency>
7</dependencies>

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.name / service.namespace attribute keys.

Copy
OTEL_RESOURCE_ATTRIBUTES=service.name=MyApp,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 for both metrics and traces.

The agent can be configured using standard OpenTelemetry options for configuration using either environment variables or system properties. 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%.

Another useful configuration that can be used during development is to log traces and metrics. This can be achieved by setting OTEL_TRACES_EXPORTER=logging and OTEL_METRICS_EXPORTER=logging.

Using CloudWatch Application Signals

You can use CloudWatch Application Signals to automatically instrument your applications on AWS using ADOT Java auto-instrumentation so that you can monitor current application health and track long-term application performance against your business objectives. Application Signals provides you with a unified, application-centric view of your applications, services, and dependencies, and helps you monitor and triage application health.

Get started with CloudWatch Application Signals

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.

Copy
ADD https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar /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:

Copy
1dependencies {
2    implementation("io.opentelemetry:opentelemetry-api:1.32.0")
3}

For Maven:

Copy
1<dependencies>
2  <dependency>
3    <groupId>io.opentelemetry</groupId>
4    <artifactId>opentelemetry-api</artifactId>
5    <version>1.32.0</version>
6  </dependency>
7</dependencies>

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

Sample Applications

• Visit the Sample Spring App using OpenTelemetry Java Auto-Instrumentation.
• SparkJava Sample Application Using Traces and Metrics.