You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 9a77290
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/content/dev/extra/opentelemetry.md
+14-6Lines changed: 14 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,12 @@
1
1
---
2
2
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.
4
4
layout: page
5
5
---
6
6
7
7
# OpenTelemetry
8
8
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/).
10
10
11
11
## Features
12
12
@@ -28,7 +28,7 @@ Adds distributed tracing, metrics, and context propagation to A2A servers and cl
28
28
29
29
The `OpenTelemetryRequestHandlerDecorator` wraps the default request handler to create spans for every A2A protocol method, with automatic error tracking.
30
30
31
-
### 1. Add Dependency
31
+
### Add Dependency
32
32
33
33
```xml
34
34
<dependency>
@@ -90,12 +90,20 @@ For other runtimes, consult your MicroProfile Context Propagation implementation
90
90
91
91
### Span Attributes
92
92
93
-
The following attributes are automatically added to spans:
93
+
The following attributes are automatically added to spans (defined in `A2AObservabilityNames`):
Copy file name to clipboardExpand all lines: docs/content/dev/server.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -223,6 +223,10 @@ public class CloseStreamsHook implements TaskStreamLifecycleHook {
223
223
224
224
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.
225
225
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
+
226
230
## Backward Compatibility with v0.3
227
231
228
232
See [Backward Compatibility](compatibility) for multi-version modules, version routing, and v0.3 client support.
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 tracingand context propagation.
4
4
5
5
## Features
6
6
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
10
10
-**Error Tracking**: Automatic error status and error type attributes on failures
11
11
12
12
## Modules
13
13
14
14
### `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.
16
16
17
17
### `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.
19
19
20
20
### `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.
22
22
23
23
### `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`).
25
25
26
26
### `opentelemetry-integration-tests`
27
-
Integration tests for OpenTelemetry functionality.
27
+
Quarkus-based integration tests for OpenTelemetry functionality.
28
28
29
-
## Usage
29
+
## Server Usage
30
30
31
-
### Basic Setup
32
-
33
-
Add the OpenTelemetry server module to your dependencies:
31
+
### Add Dependency
34
32
35
33
```xml
36
34
<dependency>
@@ -40,120 +38,131 @@ Add the OpenTelemetry server module to your dependencies:
40
38
</dependency>
41
39
```
42
40
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
+
```
44
54
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.
46
56
47
-
#### How It Works
57
+
###Span Attributes
48
58
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`):
50
60
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`) |
|`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) |
54
74
55
-
#### Configuration
75
+
###Streaming Methods
56
76
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.
58
78
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.
66
80
67
-
**Other Runtimes:**
68
-
Consult your MicroProfile Context Propagation implementation documentation for configuration options.
81
+
## Client Usage
69
82
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)
71
84
72
-
#### Example
85
+
Add the client tracing module:
73
86
74
-
```java
75
-
@ApplicationScoped
76
-
publicclassMyAgentimplementsAgent {
77
-
78
-
@Inject
79
-
@Internal
80
-
Executor executor; // Automatically uses ManagedExecutor with context propagation
-`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.
117
129
118
130
## Architecture
119
131
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
123
133
124
134
```
125
135
Client Request
126
136
↓
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
**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.
186
180
187
181
### Performance Impact
188
182
189
183
**Symptom**: Increased latency with OpenTelemetry enabled.
190
184
191
-
**Solution**:
185
+
**Solution**:
192
186
- Disable request/response extraction in production
193
187
- Configure sampling rate to reduce trace volume
194
188
- Ensure your OpenTelemetry collector is properly sized
@@ -203,13 +197,12 @@ Initializing OpenTelemetry-aware ManagedExecutor for async operations
0 commit comments