Skip to main content

OpenTelemetry for Java

Instrumenting a Java application with OpenTelemetry gives you rich, framework-aware distributed tracing — spans for every HTTP request, database call, message queue operation, and supported library call. All of it ships to CodeXray over OTLP, without modifying your application code.

Automatic instrumentation — no code changes

OpenTelemetry provides a Java agent (opentelemetry-javaagent.jar) that auto-detects popular frameworks (Spring, Jetty, Tomcat, JDBC, Kafka, Redis, gRPC, and dozens more) and instruments them at class-load time. Attach it via -javaagent and traces start flowing — no annotations, no custom code.

Before You Begin​

You'll need:

  • A running Java application (Java 8+) — any framework, any packaging
  • The URL of your CodeXray collector (e.g., https://your-codexray.example.com)
  • A project API key from the CodeXray UI (Project Settings → API Keys)

Step 1 — Download the OpenTelemetry Java Agent​

wget https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

The agent is a single JAR. No installation into your codebase required.

Step 2 — Configure via Environment Variables​

OpenTelemetry is configured entirely through environment variables. The essentials:

export OTEL_SERVICE_NAME="your-service-name"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-codexray.example.com"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-project-api-key"
export OTEL_METRICS_EXPORTER="none"     # traces only for now
VariablePurpose
OTEL_SERVICE_NAMEThe name that appears in CodeXray's Applications list
OTEL_EXPORTER_OTLP_ENDPOINTYour CodeXray collector URL (no trailing slash)
OTEL_EXPORTER_OTLP_PROTOCOLhttp/protobuf (recommended) or grpc
OTEL_EXPORTER_OTLP_HEADERSAuthentication — your project API key as x-api-key
OTEL_RESOURCE_ATTRIBUTESOptional — add environment, version, etc.

Step 3 — Run Your Application with the Agent​

Attach the agent with the -javaagent flag:

java -javaagent:./opentelemetry-javaagent.jar -jar your-application.jar

Spring Boot example​

java -javaagent:./opentelemetry-javaagent.jar \
  -jar build/libs/demo-0.0.1-SNAPSHOT.jar

The agent auto-instruments Spring MVC, Spring WebFlux, Spring Data JPA, RestTemplate, WebClient, and most of the Spring ecosystem. Traces appear in CodeXray within a minute.

Running in a container​

Bake the agent into your Docker image:

FROM eclipse-temurin:17-jre
COPY opentelemetry-javaagent.jar /otel/
COPY target/*.jar /app/app.jar
ENTRYPOINT ["java", "-javaagent:/otel/opentelemetry-javaagent.jar", "-jar", "/app/app.jar"]

Then set the OTel environment variables on the container at runtime — Kubernetes deployments typically set them on the Pod template.

Additional Resource Attributes​

Add environment, version, and any other metadata you want attached to every span:

export OTEL_RESOURCE_ATTRIBUTES="deployment.environment=production,service.version=1.4.2,service.namespace=checkout"

These become searchable in the CodeXray Traces tab and on the service detail page.

What Gets Instrumented​

The Java agent auto-instruments:

  • Web frameworks — Spring MVC / WebFlux, Servlet API, Jetty, Tomcat, Undertow, Netty, Vert.x
  • HTTP clients — Apache HttpClient, OkHttp, RestTemplate, WebClient, java.net.HttpURLConnection
  • Databases (JDBC) — PostgreSQL, MySQL, Oracle, MSSQL, MariaDB, H2
  • NoSQL — MongoDB, Cassandra, Elasticsearch, Redis (Jedis, Lettuce, Redisson)
  • Messaging — Kafka, RabbitMQ, JMS, AWS SQS
  • RPC — gRPC
  • Serverless — AWS Lambda

See the full list of supported libraries in the OpenTelemetry Java documentation.

Verifying It's Working​

  1. Start your application with the agent attached
  2. Generate some traffic (a request, a cron run, etc.)
  3. In CodeXray, open Applications → find your service (by the OTEL_SERVICE_NAME you set) → Traces tab
  4. Traces should appear within a minute or two

If nothing shows up, check your application's stdout — the OTel agent logs any connectivity or configuration issues explicitly on startup.

Quiet mode in production

The Java agent logs its startup discovery at INFO by default. For quieter production logs, add -Dotel.javaagent.logging=simple or tune the log level via OTEL_LOG_LEVEL=warn.

Next Steps​