# open-telemetry/opentelemetry-java-instrumentation architecture

> Architecture diagram of the GitHub repository open-telemetry/opentelemetry-java-instrumentation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open-telemetry/opentelemetry-java-instrumentation
- Repository: https://github.com/open-telemetry/opentelemetry-java-instrumentation

## Overview

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: [`javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/DefineClassHandler.java`](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/DefineClassHandler.java) (Java agent), [`instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java`](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java) (Span instrumenter), [`instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java`](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java) (OpenAI embeddings), [`instrumentation`](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation) (Automatic integrations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Agent runtime"]
  node_agent["Java agent"]
  node_config["Agent configuration"]
  node_extension["Agent extensions"]
end

subgraph group_instrumentation["Library instrumentation"]
  node_library_auto["Automatic integrations"]
  node_netty["Netty HTTP tracing"]
  node_openai["OpenAI embeddings"]
  node_vertx["Vert.x SQL tracing"]
  node_standalone["Standalone libraries"]
end

subgraph group_api["Instrumentation APIs"]
  node_instrumenter["Span instrumenter<br/>[Instrumenter.java]"]
  node_virtual_field["Virtual fields<br/>[VirtualField.java]"]
  node_annotations["Manual annotations<br/>[WithSpan.java]"]
  node_grpc_context["gRPC context bridge"]
end

subgraph group_delivery["Telemetry delivery"]
  node_exporters["Configured exporters"]
  node_collector["OpenTelemetry collector"]
  node_telemetry["Telemetry data"]
end

node_application(("Java application"))

node_application -->|"runs with"| node_agent
node_agent -->|"instruments libraries"| node_library_auto
node_application -->|"uses directly"| node_standalone
node_application -->|"adds spans"| node_annotations
node_openai -->|"starts and ends spans"| node_instrumenter
node_netty -->|"registers tracing handlers"| node_library_auto
node_vertx -->|"ends query span"| node_instrumenter
node_grpc_context -.->|"bridges context"| node_instrumenter
node_config -->|"configures behavior"| node_agent
node_agent -->|"sends telemetry"| node_exporters
node_exporters -->|"exports by OTLP"| node_collector
node_agent -->|"captures signals"| node_telemetry
node_extension -->|"adds capabilities"| node_agent
node_instrumenter -.->|"produces spans"| node_telemetry
node_openai -->|"uses API"| node_instrumenter
node_virtual_field -.->|"supports context storage"| node_instrumenter

click node_agent "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/DefineClassHandler.java"
click node_config "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/sdk-autoconfigure-support/src/main/java/io/opentelemetry/instrumentation/sampler/internal/RuleBasedRoutingSamplerDeprecationCustomizerProvider.java"
click node_library_auto "https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation"
click node_netty "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/netty/netty-3.8/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/netty/v3_8/ChannelPipelineUtil.java"
click node_openai "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java"
click node_vertx "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/vertx/vertx-sql-client/vertx-sql-client-5.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/vertx/sqlclient/v5_0/VertxSqlClientQueryState.java"
click node_standalone "https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation"
click node_instrumenter "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java"
click node_virtual_field "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/util/VirtualField.java"
click node_annotations "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/WithSpan.java"
click node_grpc_context "https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/grpc-1.6/library/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/internal/ContextStorageBridge.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_config,node_extension toneBlue
class node_library_auto,node_netty,node_openai,node_vertx,node_standalone toneAmber
class node_instrumenter,node_virtual_field,node_annotations,node_grpc_context toneMint
class node_exporters,node_collector,node_telemetry toneRose
class node_application toneIndigo
```

## Components

### Agent runtime

- [Java agent](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/DefineClassHandler.java): `javaagent-tooling/src/main/java/io/opentelemetry/javaagent/tooling/DefineClassHandler.java`
- [Agent configuration](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/sdk-autoconfigure-support/src/main/java/io/opentelemetry/instrumentation/sampler/internal/RuleBasedRoutingSamplerDeprecationCustomizerProvider.java): `sdk-autoconfigure-support/src/main/java/io/opentelemetry/instrumentation/sampler/internal/RuleBasedRoutingSamplerDeprecationCustomizerProvider.java`
- **Agent extensions**

### Library instrumentation

- [Automatic integrations](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation): `instrumentation`
- [Netty HTTP tracing](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/netty/netty-3.8/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/netty/v3_8/ChannelPipelineUtil.java): `instrumentation/netty/netty-3.8/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/netty/v3_8/ChannelPipelineUtil.java`
- [OpenAI embeddings](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java): `instrumentation/openai/openai-java-1.1/library/src/main/java/io/opentelemetry/instrumentation/openai/v1_1/InstrumentedEmbeddingService.java`
- [Vert.x SQL tracing](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/vertx/vertx-sql-client/vertx-sql-client-5.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/vertx/sqlclient/v5_0/VertxSqlClientQueryState.java): `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](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation): `instrumentation`

### Instrumentation APIs

- [Span instrumenter](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java): `instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/Instrumenter.java`
- [Virtual fields](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/util/VirtualField.java): `instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/util/VirtualField.java`
- [Manual annotations](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/WithSpan.java): `instrumentation-annotations/src/main/java/io/opentelemetry/instrumentation/annotations/WithSpan.java`
- [gRPC context bridge](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/instrumentation/grpc-1.6/library/src/main/java/io/opentelemetry/instrumentation/grpc/v1_6/internal/ContextStorageBridge.java): `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

- 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 (evidence: `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 (evidence: `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 (evidence: `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 (evidence: `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
