Java OpenTelemetry instrumentation

Osuite collects Java telemetry over OpenTelemetry. There are two supported paths, and most services should start with the first:

The OpenTelemetry Java agent (opentelemetry-javaagent.jar) — the primary path. A single -javaagent flag instruments your application at startup with no code changes and no rebuild. It covers the widest set of frameworks, HTTP clients, database drivers, and messaging libraries.
The OpenTelemetry Spring Boot starter — a build dependency for Spring Boot services that prefer to ship instrumentation inside the application artifact instead of attaching an agent. It is also the path to use when the Java agent cannot run, such as GraalVM native images.

This page covers the Java agent. For framework-specific setup, see the Spring Boot and Quarkus guides.

Fastest path. Run this in your AI IDE and the Instrumentation Agent wires this service up for you.

/osuite-instrument java

Detects your build tool and framework, adds the agent or starter, and wires the exporter to Osuite.

Prefer to do it by hand? Follow the manual steps below — they are the complete path.

Prerequisites

A running Java application (JDK 8 or newer).
Your Osuite ingest endpoint and token. The endpoint is ingest.<region>.osuite.io:443 for your region; the token is your <your-ingest-token>.
Outbound network access from the application host to the ingest endpoint on port 443.

Set up the Java agent

The agent reads its configuration from environment variables. Three are required in every deployment:

OTEL_EXPORTER_OTLP_ENDPOINT — where telemetry is sent.
OTEL_EXPORTER_OTLP_HEADERS — carries your ingest token.
OTEL_SERVICE_NAME — identifies the service (service.name).
OTEL_RESOURCE_ATTRIBUTES — identifies its environment (service.environment).

Pick your deployment target. Every tab is a complete, self-contained path.

Download the agent, set the environment, and attach it with -javaagent:

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

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.osuite.io:443"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your-ingest-token>"
export OTEL_SERVICE_NAME="my-service"
export OTEL_RESOURCE_ATTRIBUTES="service.environment=production"

java -javaagent:./opentelemetry-javaagent.jar -jar app.jar

The -javaagent flag must come before -jar.

Add the agent to the image and attach it in the entrypoint. Keep the token out of the image — pass it at runtime:

FROM eclipse-temurin:21-jre

WORKDIR /app
COPY target/app.jar app.jar
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar opentelemetry-javaagent.jar

ENV OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.osuite.io:443" \
    OTEL_EXPORTER_OTLP_PROTOCOL="grpc" \
    OTEL_SERVICE_NAME="my-service" \
    OTEL_RESOURCE_ATTRIBUTES="service.environment=production"

ENTRYPOINT ["java", "-javaagent:/app/opentelemetry-javaagent.jar", "-jar", "app.jar"]

Provide the token when you run the container:

docker run \
  -e OTEL_EXPORTER_OTLP_HEADERS="x-osuite-ingest-token=<your-ingest-token>" \
  my-service:latest

Build the image with the agent as shown in the Docker tab. Store the token in a Secret so it never lands in the manifest:

kubectl create secret generic osuite-ingest \
  --from-literal=otlp-headers="x-osuite-ingest-token=<your-ingest-token>"

Attach the agent with JAVA_TOOL_OPTIONS and set the exporter environment on the container:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-service
  template:
    metadata:
      labels:
        app: my-service
    spec:
      containers:
        - name: my-service
          image: my-service:latest
          env:
            - name: JAVA_TOOL_OPTIONS
              value: "-javaagent:/app/opentelemetry-javaagent.jar"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "https://ingest.<region>.osuite.io:443"
            - name: OTEL_EXPORTER_OTLP_PROTOCOL
              value: "grpc"
            - name: OTEL_SERVICE_NAME
              value: "my-service"
            - name: OTEL_RESOURCE_ATTRIBUTES
              value: "service.environment=production"
            - name: OTEL_EXPORTER_OTLP_HEADERS
              valueFrom:
                secretKeyRef:
                  name: osuite-ingest
                  key: otlp-headers

JAVA_TOOL_OPTIONS attaches the agent without changing the container’s command.

Framework guides

The agent works with any JVM framework out of the box. These guides cover framework-specific configuration and the alternative starter and extension paths:

Spring Boot — the Java agent and the opentelemetry-spring-boot-starter.
Quarkus — the native quarkus-opentelemetry extension.

To add your own spans on top of the automatic instrumentation, see Custom instrumentation.

Verify in Osuite

What you should see

Start the application and send it some traffic. The service appears in APM within a minute, emitting request-rate, error-rate, and latency metrics, and its requests show up as traces in the trace explorer.

Troubleshooting

If no data arrives, work through the Java-specific checks in Java troubleshooting.