OpenTelemetry for Java and Spring Boot

The OpenTelemetry Java agent is a jar you attach at startup. It instruments Spring, servlet containers, JDBC, Kafka and the HTTP clients in the JVM, and exports traces, logs and metrics to Maple without a code change.

GET /api/orders/{id} 6 spans · 86ms
DurationStatus
/api/orders/{id}shop-api
86.0msOk
SELECT shop.orders
11.0msOk
SELECT shop.order_items
9.0msOk
orders publish
6.0msOk
orders processbilling-worker
38.0msOk
INSERT billing.invoices
14.0msOk

Example: a Spring Boot request and the Kafka consumer it feeds

Quick start

Set up Java

1

Download the agent

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

Start the JVM with the agent attached

bash
# The key goes in the environment, not on the command line, where ps would show it
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_INGEST_KEY"

java \
  -javaagent:opentelemetry-javaagent.jar \
  -Dotel.service.name=my-java-app \
  -Dotel.exporter.otlp.endpoint=https://ingest.maple.dev \
  -Dotel.exporter.otlp.protocol=http/protobuf \
  -Dotel.resource.attributes="deployment.environment.name=production" \
  -jar app.jar
3

Or set it from the environment in a container

bash
export JAVA_TOOL_OPTIONS="-javaagent:/opt/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="my-java-app"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.maple.dev"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer YOUR_INGEST_KEY"

This is the short path. The full Java guide covers the rest.

Organization in the EU region? Send to https://ingest.eu.maple.dev instead of https://ingest.maple.dev. An ingest key only works in its own region.

What you get

What the Java agent sends to Maple

Spring MVC and WebFlux requests

Each request is one root server span named after its method and route, such as GET /api/orders.

JDBC, R2DBC and Hibernate

Query spans carry the statement and the database system. The database shows as a node on the service map.

Kafka and JMS

The agent traces message producers and consumers alongside your HTTP and database spans.

Outgoing HTTP and gRPC

Client spans propagate traceparent. An instrumented callee joins the same trace and draws an edge on the service map.

Logback, Log4j2 and JUL

Log records are exported with the active trace and span id, so each line links to the request that wrote it.

JVM metrics

The agent reports memory, garbage collection and thread counts, exported every 60 seconds.

What is different on the JVM

The agent does the wiring

Agent 2.x exports traces, logs and metrics over OTLP by default. There is no SDK code to write, and opentelemetry-api is the only dependency custom spans need.

GraalVM native images

A native image cannot load a Java agent. Use the OpenTelemetry Spring Boot starter there; it reads the same otel.* properties.

Base URL, no port

The agent appends /v1/traces itself. Never add :4317 or :4318. If nothing arrives, look for the agent's line in the startup log; without it, the -javaagent flag never reached the JVM.

Integrations

Other integrations

See your first trace today.

Add the SDK, point your OTLP exporter at Maple, and traces arrive.

maple.dev: observability on OpenTelemetry