How open-telemetry/opentelemetry-java-instrumentation works
OpenTelemetry Java Instrumentation captures traces and other telemetry from Java applications, primarily through a JVM agent that instruments supported libraries without application code changes. The main flow is application execution → agent-provided library instrumentation → common instrumentation APIs → configured exporters and a collector. The repository also provides standalone library instrumentation and APIs for manual spans. The README documents these capabilities, but most agent, exporter, and extension implementation paths are not present in the supplied tree; links to those subsystems are therefore limited to documented relationships.
Main entry points: DefineClassHandler.java Java agent · Instrumenter.java Span instrumenter · InstrumentedEmbeddingService.java OpenAI embeddings · instrumentation Automatic integrations
Components 16
Agent runtime
- Java agent
javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/DefineClassHandler.java - Agent configuration
sdk-autoconfigure-support/src/main/java/io/opentelemetry/instrumentation/sampler/internal/RuleBasedRoutingSamplerDeprecationCustomizerProvider.java - Agent extensions
Library instrumentation
- Automatic integrations
instrumentation - Netty HTTP tracing
instrumentation/netty/netty-3.8/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/netty/v3_8/ChannelPipelineUtil.java - OpenAI embeddings
instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java - Vert.x SQL tracing
instrumentation/vertx/vertx-sql-client/vertx-sql-client-5.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/vertx/sqlclient/v5_0/VertxSqlClientQueryState.java - Standalone libraries
instrumentation
Instrumentation APIs
- Span instrumenter
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java - Virtual fields
instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/util/VirtualField.java - Manual annotations
instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/WithSpan.java - gRPC context bridge
instrumentation/grpc-1.6/library/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/internal/ContextStorageBridge.java
Telemetry delivery
- Configured exporters
- OpenTelemetry collector
- Telemetry data
Other components
- Java application
Connections 16
- Java application → Java agent: runs with
- Java agent → Automatic integrations: instruments libraries
- Java application → Standalone libraries: uses directly
- Java application → Manual annotations: adds spans
- OpenAI embeddings → Span instrumenter: starts and ends spans
instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java - Netty HTTP tracing → Automatic integrations: registers tracing handlers
instrumentation/netty/netty-3.8/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/netty/v3_8/ChannelPipelineUtil.java - Vert.x SQL tracing → Span instrumenter: ends query span
instrumentation/vertx/vertx-sql-client/vertx-sql-client-5.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/vertx/sqlclient/v5_0/VertxSqlClientQueryState.java - gRPC context bridge → Span instrumenter: bridges context
- Agent configuration → Java agent: configures behavior
- Java agent → Configured exporters: sends telemetry
- Configured exporters → OpenTelemetry collector: exports by OTLP
- Java agent → Telemetry data: captures signals
- Agent extensions → Java agent: adds capabilities
- Span instrumenter → Telemetry data: produces spans
- OpenAI embeddings → Span instrumenter: uses API
instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java - Virtual fields → Span instrumenter: supports context storage