Attaching OpenTelemetry Java Agent to a Maven Microservice

Observability is critical in modern microservices architecture. It enables you to monitor, debug, and optimize distributed systems. OpenTelemetry (OTel) is a powerful observability framework that supports tracing, metrics, and logs in a vendor-neutral way.

In this blog post, we’ll walk through how to attach the OpenTelemetry Java Agent to a Maven-based microservice, enabling automatic instrumentation with minimal effort.

---

Prerequisites

Before we dive in, ensure you have the following set up:

• Java 8 or later (Java 17 and java 21 recommended)

• Maven 3.6+

• A working microservice project (Spring Boot, Jakarta EE, or similar)

• Access to an OpenTelemetry-compatible backend like Jaeger, Zipkin, or an observability platform (e.g., Grafana Tempo, Lightstep)

---

What is the OpenTelemetry Java Agent?

The OpenTelemetry Java Agent is a JAR file that you can attach to any Java application. It automatically instruments your application without requiring any code changes. It supports popular frameworks like:

• Spring Boot

• gRPC

• JDBC

• HTTP clients (RestTemplate, OkHttp, Apache HTTP Client, etc.)

• Servlet containers (Tomcat, Jetty)

---

Step-by-Step: Attach the OTel Agent to a Maven Microservice

1. Download the OpenTelemetry Java Agent

Go to the OpenTelemetry Java Instrumentation Releases page and download the latest opentelemetry-javaagent.jar.

You can also use curl:

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

Place this file in the root directory of your microservice or a common location.

---

2. Update Maven pom.xml (Optional)

You don't need to change your pom.xml to use the agent, but if you want to send custom spans or metrics, add the OpenTelemetry SDK dependencies:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-bom</artifactId>
      <version>1.35.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-api</artifactId>
  </dependency>
  <dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-sdk</artifactId>
  </dependency>
</dependencies>

Skip this step if you only need automatic instrumentation.

---

3. Configure the OpenTelemetry Agent

To enable observability, you'll configure the OpenTelemetry Java agent and run your microservice with it attached. The agent picks up system properties or environment variables to determine where to send telemetry like traces, metrics, and logs.

Note - You can send telemetry from the OpenTelemetry agent to any OTLP-compatible backend. First, ensure your observability backend is up and running, then configure the agent with the appropriate endpoint URL and port to forward the telemetry data.

Run the Microservice with the Agent

You attach the agent via the -javaagent option when starting your microservice.

If you’re using the Spring Boot Maven plugin:

java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.service.name=my-microservice \
     -Dotel.exporter.otlp.traces.endpoint=http://traces-backend:4317 \
     -Dotel.exporter.otlp.metrics.endpoint=http://metrics-backend:4317 \
     -Dotel.exporter.otlp.logs.endpoint=http://logs-backend:4317 \
     -Dotel.metrics.exporter=otlp \
     -Dotel.logs.exporter=otlp \
     -Dotel.instrumentation.log-injection.enabled=true \
     -jar target/my-microservice.jar

Or if using mvn spring-boot:run:

MAVEN_OPTS="\
-javaagent:./opentelemetry-javaagent.jar \
-Dotel.service.name=my-microservice \
-Dotel.exporter.otlp.traces.endpoint=http://traces-backend:4317 \
-Dotel.exporter.otlp.metrics.endpoint=http://metrics-backend:4317 \
-Dotel.exporter.otlp.logs.endpoint=http://logs-backend:4317 \
-Dotel.metrics.exporter=otlp \
-Dotel.logs.exporter=otlp \
-Dotel.instrumentation.log-injection.enabled=true" \
mvn spring-boot:run

You can also pass OTEL_EXPORTER_OTLP_ENDPOINT and other settings as environment variables.

---

Verification

Once your service starts, check your observability backend (e.g., Jaeger, Tempo, or your OpenTelemetry Collector). You should see:

• Traces for incoming HTTP requests

• Spans representing downstream calls (e.g., DB, external services)

• Service metadata like service name, environment, etc.

---

Advanced Configurations (Optional)

• Disable instrumentation for certain libraries:

    -Dotel.instrumentation.spring-web.enabled=false
  

• Add custom context propagation or headers:

    -Dotel.propagators=b3
  

• Enable metrics export (if Collector supports it):

    -Dotel.metrics.exporter=otlp
  

• Remote config via environment variables:

    export OTEL_TRACES_SAMPLER=always_on
  

---

Docker Support

If your microservice is containerized, you can mount the agent JAR and pass the Java options in your Dockerfile or entrypoint.

COPY opentelemetry-javaagent.jar /otel/opentelemetry-javaagent.jar
ENV JAVA_TOOL_OPTIONS "-javaagent:/otel/opentelemetry-javaagent.jar"

Example with Spring Boot

For a Spring Boot app named orderservice, start it with:

java -javaagent:./opentelemetry-javaagent.jar \
     -Dotel.service.name=orderservice \
     -Dotel.exporter.otlp.endpoint=http://localhost:4317 \
     -jar target/orderservice-0.0.1-SNAPSHOT.jar

When you set:

 -Dotel.exporter.otlp.endpoint=http://localhost:4317

You're telling the OpenTelemetry agent to send all telemetry signals (traces, metrics, and logs) to that single OTLP endpoint — unless you override them individually.

Override Per Signal (as we did previously at top of this blog)

If you want to split telemetry signals to different backends, you’d need to use:

-Dotel.exporter.otlp.traces.endpoint=http://traces-backend:4317
-Dotel.exporter.otlp.metrics.endpoint=http://metrics-backend:4317
-Dotel.exporter.otlp.logs.endpoint=http://logs-backend:4317

Or the environment variable equivalents:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://traces-backend:4317
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics-backend:4317
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs-backend:4317

And just like that, you're automatically capturing traces for:

• REST controllers

• JDBC queries

• Redis or Kafka integrations (if supported)

---

Conclusion

Attaching the OpenTelemetry Java Agent is one of the fastest and easiest ways to get observability into your Java applications. Whether you're running Spring Boot microservices, Jakarta EE apps, or vanilla Java services — the agent gives you deep visibility with zero code changes.

Next steps:

• Visualize traces and metrics in Grafana or Jaeger

• Add custom spans for business logic

• Use OpenTelemetry Collector for exporting to multiple backends

---

Useful Links

• OpenTelemetry Java Agent GitHub

• OpenTelemetry Collector

• Grafana Tempo

• Jaeger

• OpenTelemetry Java Docs