Skip to content

Commit 9a77290

Browse files
authored
fix(opentelemetry): correct inaccurate docs, Javadoc, and dead config (#1019)
- README: fix wrong property names, attribute names, remove misplaced AsyncManagedExecutorProducer section, add client usage and streaming limitation docs - Javadoc: fix references to non-existent OpenTelemetryClientTransportFactory - beans.xml: remove reference to non-existent InstrumentedRequestHandler - Docs site: remove false "metrics" claim, expand span attributes table, add cross-references from server/client guides Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>
1 parent 420c1ce commit 9a77290

8 files changed

Lines changed: 179 additions & 248 deletions

File tree

‎docs/content/dev/client.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -185,6 +185,10 @@ Client client = Client
185185
.build();
186186
```
187187

188+
## Observability (Optional)
189+
190+
Add distributed tracing and W3C Trace Context propagation to client calls with the [OpenTelemetry extras modules](extra/opentelemetry#client).
191+
188192
## Communicating with v0.3 Agents
189193

190194
See [Backward Compatibility](compatibility#client-communicating-with-v03-agents) for using `Client_v0_3` with older protocol agents.

‎docs/content/dev/extra/opentelemetry.md‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
22
title: OpenTelemetry
3-
description: OpenTelemetry observability integration for the A2A Java SDK with distributed tracing, context propagation, and metrics for servers and clients.
3+
description: OpenTelemetry observability integration for the A2A Java SDK with distributed tracing and context propagation for servers and clients.
44
layout: page
55
---
66

77
# OpenTelemetry
88

9-
Adds distributed tracing, metrics, and context propagation to A2A servers and clients using [OpenTelemetry](https://opentelemetry.io/).
9+
Adds distributed tracing and context propagation to A2A servers and clients using [OpenTelemetry](https://opentelemetry.io/).
1010

1111
## Features
1212

@@ -28,7 +28,7 @@ Adds distributed tracing, metrics, and context propagation to A2A servers and cl
2828

2929
The `OpenTelemetryRequestHandlerDecorator` wraps the default request handler to create spans for every A2A protocol method, with automatic error tracking.
3030

31-
### 1. Add Dependency
31+
### Add Dependency
3232

3333
```xml
3434
<dependency>
@@ -90,12 +90,20 @@ For other runtimes, consult your MicroProfile Context Propagation implementation
9090

9191
### Span Attributes
9292

93-
The following attributes are automatically added to spans:
93+
The following attributes are automatically added to spans (defined in `A2AObservabilityNames`):
9494

9595
| Attribute | Description |
9696
|-----------|-------------|
97-
| `gen_ai.agent.a2a.request` | Request parameters (if extraction enabled) |
98-
| `gen_ai.agent.a2a.response` | Response data (if extraction enabled) |
97+
| `gen_ai.agent.a2a.operation.name` | The A2A method name (e.g., `message/send`, `tasks/get`) |
98+
| `gen_ai.agent.a2a.task_id` | Task identifier (when available) |
99+
| `gen_ai.agent.a2a.context_id` | Context/conversation identifier (when available) |
100+
| `gen_ai.agent.a2a.message_id` | Message identifier (when available) |
101+
| `gen_ai.agent.a2a.role` | Message role (when available) |
102+
| `gen_ai.agent.a2a.extensions` | Comma-separated extension names (when present) |
103+
| `gen_ai.agent.a2a.parts.number` | Number of message parts |
104+
| `gen_ai.agent.a2a.config_id` | Push notification config identifier (when available) |
105+
| `gen_ai.agent.a2a.request` | Full request parameters (only if extraction enabled) |
106+
| `gen_ai.agent.a2a.response` | Full response data (only if extraction enabled) |
99107
| `error.type` | Error message (on failures) |
100108

101109
### Request/Response Extraction

‎docs/content/dev/server.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,6 +223,10 @@ public class CloseStreamsHook implements TaskStreamLifecycleHook {
223223

224224
See the [`examples/stream-lifecycle`](https://github.com/a2aproject/a2a-java/tree/main/examples/stream-lifecycle) directory for a complete working example with server, client, and integration tests for all three transports.
225225

226+
## Observability (Optional)
227+
228+
Add distributed tracing to your server with the [OpenTelemetry extras module](extra/opentelemetry). It decorates the request handler to create spans for every A2A protocol method, with automatic error tracking and optional request/response extraction.
229+
226230
## Backward Compatibility with v0.3
227231

228232
See [Backward Compatibility](compatibility) for multi-version modules, version routing, and v0.3 client support.

‎extras/opentelemetry/README.md‎

Lines changed: 96 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,34 @@
11
# OpenTelemetry Integration for A2A
22

3-
This module provides OpenTelemetry observability integration for A2A servers, including distributed tracing, metrics, and context propagation across asynchronous boundaries.
3+
This module provides OpenTelemetry observability integration for A2A servers and clients, including distributed tracing and context propagation.
44

55
## Features
66

7-
- **Distributed Tracing**: Automatic span creation for all A2A protocol methods
8-
- **Context Propagation**: OpenTelemetry trace context propagation across async operations
9-
- **Request/Response Logging**: Optional extraction of request and response data into spans
7+
- **Distributed Tracing**: Automatic span creation for all A2A protocol methods (both client and server)
8+
- **Context Propagation**: W3C Trace Context injection into outbound client requests
9+
- **Request/Response Logging**: Optional extraction of request and response data into span attributes
1010
- **Error Tracking**: Automatic error status and error type attributes on failures
1111

1212
## Modules
1313

1414
### `opentelemetry-common`
15-
Common utilities and constants shared across OpenTelemetry modules.
15+
Constants and span attribute names shared across client and server modules. See `A2AObservabilityNames` for the full list of attribute keys.
1616

1717
### `opentelemetry-client`
18-
OpenTelemetry integration for A2A clients.
18+
Client-side distributed tracing. Wraps `ClientTransport` to create spans for every A2A operation. Discovered automatically via `ServiceLoader` when a `Tracer` is present in the transport configuration parameters.
1919

2020
### `opentelemetry-client-propagation`
21-
Context propagation support for A2A clients.
21+
Injects W3C Trace Context headers into outbound client requests using `OpenTelemetry.getPropagators().getTextMapPropagator()`. Discovered automatically via `ServiceLoader` when an `OpenTelemetry` instance is present in the transport configuration parameters.
2222

2323
### `opentelemetry-server`
24-
OpenTelemetry integration for A2A servers, including the context-aware executor.
24+
CDI decorator (`OpenTelemetryRequestHandlerDecorator`) that wraps `RequestHandler` to create server-side spans. Automatically activated when the module JAR is on the classpath (via the bundled `beans.xml`).
2525

2626
### `opentelemetry-integration-tests`
27-
Integration tests for OpenTelemetry functionality.
27+
Quarkus-based integration tests for OpenTelemetry functionality.
2828

29-
## Usage
29+
## Server Usage
3030

31-
### Basic Setup
32-
33-
Add the OpenTelemetry server module to your dependencies:
31+
### Add Dependency
3432

3533
```xml
3634
<dependency>
@@ -40,120 +38,131 @@ Add the OpenTelemetry server module to your dependencies:
4038
</dependency>
4139
```
4240

43-
### Context-Aware Async Executor
41+
The `OpenTelemetryRequestHandlerDecorator` is registered automatically via the `beans.xml` bundled in the module JAR. No additional configuration is required.
42+
43+
> **Note**: The decorator relies on the runtime (e.g., Quarkus OpenTelemetry extension) to extract trace context from incoming HTTP requests. It does not perform context extraction itself — it creates a new span within the already-established trace context.
44+
45+
### Request/Response Extraction
46+
47+
Optionally include full request/response data as span attributes. These are controlled by **JVM system properties** (not application config), read via `Boolean.getBoolean()`:
48+
49+
```bash
50+
# Pass as JVM system properties (-D flags)
51+
-Dorg.a2aproject.sdk.server.extract.request=true
52+
-Dorg.a2aproject.sdk.server.extract.response=true
53+
```
4454

45-
The `AsyncManagedExecutorProducer` provides a `ManagedExecutor` that automatically propagates OpenTelemetry trace context across asynchronous boundaries. This ensures that spans created in async tasks are properly linked to their parent spans.
55+
> **Warning**: Extracting request/response data may expose sensitive information in traces. Use with caution in production environments.
4656
47-
#### How It Works
57+
### Span Attributes
4858

49-
When the OpenTelemetry server module is included, the `AsyncManagedExecutorProducer` automatically replaces the default `AsyncExecutorProducer` using CDI alternatives:
59+
The following attributes are automatically added to spans (defined in `A2AObservabilityNames`):
5060

51-
- **Priority 20**: Takes precedence over the default executor producer (priority 10)
52-
- **Automatic Activation**: No configuration needed - just include the module
53-
- **Context Propagation**: Uses MicroProfile Context Propagation to maintain trace context
61+
| Attribute | Description |
62+
|-----------|-------------|
63+
| `gen_ai.agent.a2a.operation.name` | The A2A method name (e.g., `message/send`, `tasks/get`) |
64+
| `gen_ai.agent.a2a.task_id` | Task identifier (when available) |
65+
| `gen_ai.agent.a2a.context_id` | Context/conversation identifier (when available) |
66+
| `gen_ai.agent.a2a.message_id` | Message identifier (when available) |
67+
| `gen_ai.agent.a2a.role` | Message role (when available) |
68+
| `gen_ai.agent.a2a.extensions` | Comma-separated extension names (when present) |
69+
| `gen_ai.agent.a2a.parts.number` | Number of message parts |
70+
| `gen_ai.agent.a2a.config_id` | Push notification config identifier (when available) |
71+
| `gen_ai.agent.a2a.request` | Full request parameters (only if extraction enabled) |
72+
| `gen_ai.agent.a2a.response` | Full response data (only if extraction enabled) |
73+
| `error.type` | Error message (on failures) |
5474

55-
#### Configuration
75+
### Streaming Methods
5676

57-
The `ManagedExecutor` is container-managed and configured through your runtime environment:
77+
For streaming methods (`onMessageSendStream`, `onSubscribeToTask`), the server-side span covers only the creation of the `Flow.Publisher`, not the actual streaming of events. The span is started and ended synchronously before events are emitted, and the response attribute is set to `"Stream publisher created"`. This means the span duration does not reflect the actual duration of the streaming operation.
5878

59-
**Quarkus:**
60-
```properties
61-
# Configure the managed executor pool
62-
quarkus.thread-pool.core-threads=10
63-
quarkus.thread-pool.max-threads=50
64-
quarkus.thread-pool.queue-size=100
65-
```
79+
On the client side, streaming is handled differently: the `OpenTelemetryClientTransport` creates child spans linked to the parent for each streaming event and error callback, providing per-event tracing.
6680

67-
**Other Runtimes:**
68-
Consult your MicroProfile Context Propagation implementation documentation for configuration options.
81+
## Client Usage
6982

70-
> **Note**: Unlike the default `AsyncExecutorProducer`, the `AsyncManagedExecutorProducer` does not use the `a2a.executor.*` configuration properties. Pool sizing is controlled by the container's ManagedExecutor configuration.
83+
### Instrumentation (Tracing Spans)
7184

72-
#### Example
85+
Add the client tracing module:
7386

74-
```java
75-
@ApplicationScoped
76-
public class MyAgent implements Agent {
77-
78-
@Inject
79-
@Internal
80-
Executor executor; // Automatically uses ManagedExecutor with context propagation
81-
82-
@Override
83-
public void execute(RequestContext context, AgentEmitter emitter) {
84-
// Current span context is automatically propagated
85-
executor.execute(() -> {
86-
// This code runs in a different thread but maintains the trace context
87-
Span currentSpan = Span.current();
88-
currentSpan.addEvent("Processing in async task");
89-
90-
// Do async work...
91-
});
92-
}
93-
}
87+
```xml
88+
<dependency>
89+
<groupId>org.a2aproject.sdk</groupId>
90+
<artifactId>a2a-extras-opentelemetry-client</artifactId>
91+
<version>${a2a.version}</version>
92+
</dependency>
9493
```
9594

96-
### Request/Response Extraction
95+
Enable tracing by adding a `Tracer` instance to the transport configuration parameters:
9796

98-
Enable request and response data extraction in spans:
97+
```java
98+
import static org.a2aproject.sdk.extras.opentelemetry.client.OpenTelemetryClientTransportWrapper.OTEL_TRACER_KEY;
99+
100+
config.setParameters(Map.of(
101+
OTEL_TRACER_KEY, openTelemetry.getTracer("my-service")
102+
));
103+
```
99104

100-
```properties
101-
# Extract request parameters into span attributes
102-
a2a.opentelemetry.extract-request=true
105+
### Context Propagation (W3C Trace Headers)
103106

104-
# Extract response data into span attributes
105-
a2a.opentelemetry.extract-response=true
107+
Add the propagation module:
108+
109+
```xml
110+
<dependency>
111+
<groupId>org.a2aproject.sdk</groupId>
112+
<artifactId>a2a-extras-opentelemetry-client-propagation</artifactId>
113+
<version>${a2a.version}</version>
114+
</dependency>
106115
```
107116

108-
> **Warning**: Extracting request/response data may expose sensitive information in traces. Use with caution in production environments.
117+
Enable propagation by adding an `OpenTelemetry` instance to the transport configuration parameters:
109118

110-
### Span Attributes
119+
```java
120+
import static org.a2aproject.sdk.extras.opentelemetry.client.propagation.OpenTelemetryClientPropagatorTransportWrapper.OTEL_OPEN_TELEMETRY_KEY;
111121

112-
The following attributes are automatically added to spans:
122+
config.setParameters(Map.of(
123+
OTEL_TRACER_KEY, openTelemetry.getTracer("my-service"),
124+
OTEL_OPEN_TELEMETRY_KEY, openTelemetry
125+
));
126+
```
113127

114-
- `genai.request`: Request parameters (if extraction enabled)
115-
- `genai.response`: Response data (if extraction enabled)
116-
- `error.type`: Error message (on failures)
128+
Both wrappers are discovered automatically via `ServiceLoader` and activate only when their respective keys are present in the configuration parameters. The client wrapper (priority 600) runs after the propagation wrapper (priority 500), so trace context headers are injected before the tracing span is created.
117129

118130
## Architecture
119131

120-
### Request Handler Decoration
121-
122-
The `OpenTelemetryRequestHandlerDecorator` wraps the default request handler and creates spans for each A2A protocol method:
132+
### Server Request Handler Decoration
123133

124134
```
125135
Client Request
126136
↓
127-
OpenTelemetryRequestHandlerDecorator
128-
↓ (creates span)
137+
Runtime (e.g., Quarkus OTel) extracts trace context from HTTP headers
138+
↓
139+
OpenTelemetryRequestHandlerDecorator creates span within trace context
140+
↓
129141
Default RequestHandler
130142
↓
131-
Agent Execution (with context propagation)
143+
Agent Execution
132144
↓
133145
Response
134146
```
135147

136-
### Context Propagation Flow
148+
### Client Transport Wrapping
137149

138150
```
139-
HTTP Request (with trace headers)
151+
Application calls ClientTransport method
140152
↓
141-
OpenTelemetry extracts context
153+
OpenTelemetryClientPropagatorTransport injects W3C trace context headers (priority 500)
142154
↓
143-
Span created for A2A method
155+
OpenTelemetryClientTransport creates tracing span (priority 600)
144156
↓
145-
ManagedExecutor propagates context
157+
Underlying transport (JSON-RPC, gRPC, REST)
146158
↓
147-
Async agent execution (maintains trace context)
148-
↓
149-
Response (with trace headers)
159+
Response
150160
```
151161

152162
## Testing
153163

154-
The module includes comprehensive unit tests:
164+
The module includes:
155165

156-
- `AsyncManagedExecutorProducerTest`: Tests for the context-aware executor producer
157166
- `OpenTelemetryRequestHandlerDecoratorTest`: Tests for span creation and error handling
158167

159168
Run tests:
@@ -167,28 +176,13 @@ mvn test -pl extras/opentelemetry/server
167176

168177
**Symptom**: Spans in async tasks are not linked to parent spans.
169178

170-
**Solution**: Ensure the OpenTelemetry server module is included and the `ManagedExecutor` is being injected correctly. Check logs for:
171-
```
172-
Initializing OpenTelemetry-aware ManagedExecutor for async operations
173-
```
174-
175-
### ManagedExecutor Not Available
176-
177-
**Symptom**: `IllegalStateException: ManagedExecutor not injected - ensure MicroProfile Context Propagation is available`
178-
179-
**Solution**: Ensure your runtime provides MicroProfile Context Propagation support. For Quarkus, add:
180-
```xml
181-
<dependency>
182-
<groupId>io.quarkus</groupId>
183-
<artifactId>quarkus-smallrye-context-propagation</artifactId>
184-
</dependency>
185-
```
179+
**Solution**: Ensure your runtime provides trace context propagation for async boundaries. For Quarkus, this is handled automatically by MicroProfile Context Propagation. The context-aware `ManagedExecutor` that propagates trace context across async boundaries is provided by the reference server module (`reference/common`), not this OpenTelemetry module.
186180

187181
### Performance Impact
188182

189183
**Symptom**: Increased latency with OpenTelemetry enabled.
190184

191-
**Solution**:
185+
**Solution**:
192186
- Disable request/response extraction in production
193187
- Configure sampling rate to reduce trace volume
194188
- Ensure your OpenTelemetry collector is properly sized
@@ -203,13 +197,12 @@ Initializing OpenTelemetry-aware ManagedExecutor for async operations
203197

204198
## Dependencies
205199

206-
- MicroProfile Telemetry 2.0.1+
207-
- MicroProfile Context Propagation 1.3+
208200
- OpenTelemetry API
209-
- A2A Server Common
201+
- A2A Server Common (for server module)
202+
- A2A Client Transport SPI (for client modules)
210203

211204
## See Also
212205

213206
- [OpenTelemetry Documentation](https://opentelemetry.io/docs/)
214207
- [MicroProfile Telemetry Specification](https://github.com/eclipse/microprofile-telemetry)
215-
- [MicroProfile Context Propagation](https://github.com/eclipse/microprofile-context-propagation)
208+
- [Helloworld Example with OpenTelemetry](../../examples/helloworld/)

0 commit comments

Comments
 (0)