Java

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/docs/instrumentation-java"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/docs/pages/75a700f1-eba0-48a4-a586-40558934d77c/social-card.svg?v=3e7ae33eec8b" alt="Java" width="600" height="315"></a>

<!-- status: ga language: java -->

Java: zero-code instrumentation

The standard OpenTelemetry Java agent instruments common frameworks (servlets, Spring, JDBC, HTTP clients, Kafka) without a code change. Nothing Watchtower-specific is installed: the agent reads the standard OTEL_* variables.

  1. Create a project, then an ingestion key (wti_...) with the ingest:traces scope (add ingest:logs and ingest:metrics to send those too). The key is shown once.

  2. Point the agent at the gateway and pass the key in the x-watchtower-key header:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.example.com
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS=x-watchtower-key=wti_YOUR_KEY
export OTEL_SERVICE_NAME=my-service

  1. Download opentelemetry-javaagent.jar from the opentelemetry-java-instrumentation releases and start the service with it. The agent appends /v1/traces, /v1/logs and /v1/metrics to the endpoint.

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

In containers set JAVA_TOOL_OPTIONS=-javaagent:/opt/otel/opentelemetry-javaagent.jar instead of editing the command line.

  1. Send one request to the service, then open the project's onboarding screen: it turns green when the first span arrives. Open the trace in the trace explorer.

Database findings and queues

The Database tab lists N+1 queries (10 or more child DB spans with one normalised statement under one parent) and wait states (spans carrying db.wait_event or db.lock.wait_ms). The Queues tab marks dead letters (names matching *.dlq, *-dlq, *.dead, *-dead, or messaging.destination.dead_letter=true) and lists messaging.message.schema_id values seen.

Updated