Java OpenTelemetry troubleshooting

Work through the Java-specific issues below first, then the general checks at the end.

The agent is not attaching

If startup logs show nothing from OpenTelemetry and no service appears in Osuite, the agent likely never loaded.

Flag order. -javaagent must appear before -jar (and before the main class). java -javaagent:./opentelemetry-javaagent.jar -jar app.jar is correct; placing it after -jar is not.
Path. The path after -javaagent: must point at the actual jar. A relative path is resolved against the working directory, not the jar’s location. In containers, prefer an absolute path such as /app/opentelemetry-javaagent.jar.
JAVA_TOOL_OPTIONS. When you attach the agent through JAVA_TOOL_OPTIONS, the JVM prints Picked up JAVA_TOOL_OPTIONS: ... on startup. If that line is missing, the variable is not reaching the process.
JDK version. The agent requires Java 8 or newer.
Enable agent debug logging to see what the agent is doing:

export OTEL_JAVAAGENT_DEBUG=true

Duplicate or missing spans

Duplicate spans almost always mean two instrumentation layers are active at once — for example, the Java agent and the Spring Boot starter, or the agent and the Quarkus extension. Use exactly one. Remove the starter dependency or drop the -javaagent flag.
Missing spans for a specific library may mean that library is not auto-instrumented. Add custom spans around that code.
No traces at all, but the agent attached, usually points at the exporter — see Exporter connectivity below. Confirm OTEL_TRACES_EXPORTER has not been set to none.

Conflicting APM agents

The OpenTelemetry Java agent instruments bytecode. So do the New Relic, Datadog, AppDynamics, and Dynatrace agents. Running the OpenTelemetry agent alongside another bytecode APM agent can lead to double instrumentation, broken context propagation, or startup failures.

Run only one bytecode agent per JVM. Remove the other vendor’s -javaagent flag before adding OpenTelemetry.
If you must migrate gradually, do it one service at a time rather than stacking agents.

GraalVM native image

The Java agent works by transforming bytecode at class load, which does not happen in a GraalVM native image. opentelemetry-javaagent.jar cannot be used with native images.

For a native Spring Boot application, use the Spring Boot starter (Option B).
For Quarkus, use the quarkus-opentelemetry extension, which registers the required native metadata at build time.

Exporter connectivity

If the agent attaches but no data reaches Osuite, the exporter cannot deliver. Enable OTEL_JAVAAGENT_DEBUG=true and look for Failed to export messages, then check:

Endpoint scheme. OTEL_EXPORTER_OTLP_ENDPOINT must be a full URL with a scheme: https://ingest.<region>.osuite.io:443. A bare host and port is rejected by the exporter.
Protocol. These docs use OTEL_EXPORTER_OTLP_PROTOCOL=grpc against port 443. If your setup expects HTTP, set OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf instead — the exporter then appends the signal path (/v1/traces, /v1/logs, /v1/metrics) automatically. Do not mix a gRPC endpoint with the HTTP protocol.
Token header. OTEL_EXPORTER_OTLP_HEADERS must read exactly x-osuite-ingest-token=<your-ingest-token>. A wrong header name or a rotated token is rejected at ingest.
TLS and network. Confirm the host has outbound access to the endpoint on port 443 and that TLS is not intercepted by a proxy that breaks the connection.

General checks

No data in Osuite after a few minutes? Work through these checks.

Endpoint — confirm the exporter targets exactly ingest.<region>.osuite.io:443 for your region, over TLS.
Token — confirm the ingest header carries a valid <your-ingest-token> and has not been rotated.
Pipeline — confirm the signal you expect (traces, logs, or metrics) is wired into an active pipeline with the otlp/osuite exporter attached.
Export errors — check the application or Collector logs for OTLP export failures (auth, DNS, TLS, connection refused).
Network — confirm the host has outbound access to the ingest endpoint on port 443.
Timing — allow up to a minute for the first data to appear before assuming a failure.

Still stuck? Ask the Investigation Agent or contact support.