feat: Add OpenTelemetry tracing support

Adds OpenTelemetry integration for distributed tracing:

- Client: OpenTelemetryClientTransport decorator wrapping all client operations
  with span creation and context propagation via ClientTransportWrapper SPI
- Server: OpenTelemetryRequestHandlerDecorator CDI decorator for request handlers
- Common: A2AObservabilityNames for standard observability attributes
- Integration tests with comprehensive coverage for client and server tracing
- Updated HelloWorld examples with OTEL configuration and documentation

Fixes a2aproject#388

Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>

Author: ehsavoie

.gitignore

@@ -7,6 +7,9 @@ release.properties
 .flattened-pom.xml
 *.args
 
+#Claude
+CLAUDE.md
+
 # Eclipse
 .project
 .classpath
@@ -21,6 +24,7 @@ bin/
 
 # NetBeans
 nb-configuration.xml
+nbactions.xml
 
 # Visual Studio Code
 .vscode
@@ -54,3 +58,4 @@ nbactions.xml
 .serena/
 .bob/
 claudedocs
+.bob/

boms/extras/pom.xml

@@ -39,6 +39,26 @@
                 <artifactId>a2a-java-sdk-http-client-vertx</artifactId>
                 <version>${project.version}</version>
             </dependency>
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>a2a-java-sdk-opentelemetry-common</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>a2a-java-sdk-opentelemetry-client</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>a2a-java-sdk-opentelemetry-client-propagation</artifactId>
+                <version>${project.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>${project.groupId}</groupId>
+                <artifactId>a2a-java-sdk-opentelemetry-server</artifactId>
+                <version>${project.version}</version>
+            </dependency>
             <dependency>
                 <groupId>${project.groupId}</groupId>
                 <artifactId>a2a-java-extras-task-store-database-jpa</artifactId>

boms/extras/src/it/extras-usage-test/pom.xml

@@ -48,6 +48,22 @@
             <groupId>io.github.a2asdk</groupId>
             <artifactId>a2a-java-sdk-http-client-vertx</artifactId>
         </dependency>
+        <dependency>
+            <groupId>io.github.a2asdk</groupId>
+            <artifactId>a2a-java-sdk-opentelemetry-common</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.github.a2asdk</groupId>
+            <artifactId>a2a-java-sdk-opentelemetry-client</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.github.a2asdk</groupId>
+            <artifactId>a2a-java-sdk-opentelemetry-client-propagation</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.github.a2asdk</groupId>
+            <artifactId>a2a-java-sdk-opentelemetry-server</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.github.a2asdk</groupId>
             <artifactId>a2a-java-extras-task-store-database-jpa</artifactId>

boms/extras/src/it/extras-usage-test/src/main/java/io/a2a/test/ExtrasBomVerifier.java

@@ -17,7 +17,8 @@ public class ExtrasBomVerifier extends DynamicBomVerifier {
         "tck/",        // TCK test suite
         "tests/",      // Integration tests
         "extras/queue-manager-replicated/tests-multi-instance/",   // Test harness applications
-        "extras/queue-manager-replicated/tests-single-instance/"   // Test harness applications
+        "extras/queue-manager-replicated/tests-single-instance/",   // Test harness applications
+        "extras/opentelemetry/integration-tests/"   // Test harness applications
         // Note: extras/ production modules are NOT in this list - we want to verify those classes load
     );
 

client/base/src/main/java/io/a2a/client/ClientBuilder.java

@@ -6,21 +6,27 @@
 import java.util.List;
 import java.util.Map;
 import java.util.ServiceLoader;
+import java.util.ServiceLoader.Provider;
 import java.util.function.BiConsumer;
 import java.util.function.Consumer;
+import java.util.stream.Collectors;
 
 import io.a2a.client.config.ClientConfig;
 import io.a2a.client.transport.spi.ClientTransport;
 import io.a2a.client.transport.spi.ClientTransportConfig;
 import io.a2a.client.transport.spi.ClientTransportConfigBuilder;
 import io.a2a.client.transport.spi.ClientTransportProvider;
+import io.a2a.client.transport.spi.ClientTransportWrapper;
 import io.a2a.spec.A2AClientException;
 import io.a2a.spec.AgentCard;
 import io.a2a.spec.AgentInterface;
 import io.a2a.spec.TransportProtocol;
 import org.jspecify.annotations.NonNull;
 import org.jspecify.annotations.Nullable;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
 /**
  * Builder for creating instances of {@link Client} to communicate with A2A agents.
  * <p>
@@ -96,6 +102,7 @@ public class ClientBuilder {
 
     private static final Map<String, ClientTransportProvider<? extends ClientTransport, ? extends ClientTransportConfig<?>>> transportProviderRegistry = new HashMap<>();
     private static final Map<Class<? extends ClientTransport>, String> transportProtocolMapping = new HashMap<>();
+    private static final Logger LOGGER = LoggerFactory.getLogger(ClientBuilder.class);
 
     static {
         ServiceLoader<ClientTransportProvider> loader = ServiceLoader.load(ClientTransportProvider.class);
@@ -318,7 +325,7 @@ private ClientTransport buildClientTransport() throws A2AClientException {
             throw new A2AClientException("Missing required TransportConfig for " + agentInterface.protocolBinding());
         }
 
-        return clientTransportProvider.create(clientTransportConfig, agentCard, agentInterface);
+        return wrap(clientTransportProvider.create(clientTransportConfig, agentCard, agentInterface), clientTransportConfig);
     }
 
     private Map<String, String> getServerPreferredTransports() throws A2AClientException {
@@ -373,10 +380,55 @@ private AgentInterface findBestClientTransport() throws A2AClientException {
         if (transportProtocol == null || transportUrl == null) {
             throw new A2AClientException("No compatible transport found");
         }
-        if (! transportProviderRegistry.containsKey(transportProtocol)) {
+        if (!transportProviderRegistry.containsKey(transportProtocol)) {
             throw new A2AClientException("No client available for " + transportProtocol);
         }
 
         return new AgentInterface(transportProtocol, transportUrl);
     }
+
+    /**
+     * Wraps the transport with all available transport wrappers discovered via ServiceLoader.
+     * Wrappers are applied in reverse priority order (lowest priority first) to build a stack
+     * where the highest priority wrapper is the outermost layer.
+     *
+     * @param transport the base transport to wrap
+     * @param clientTransportConfig the transport configuration
+     * @return the wrapped transport (or original if no wrappers are available/applicable)
+     */
+    private ClientTransport wrap(ClientTransport transport, ClientTransportConfig<? extends ClientTransport> clientTransportConfig) {
+        ServiceLoader<ClientTransportWrapper> wrapperLoader = ServiceLoader.load(ClientTransportWrapper.class);
+
+        // Collect all wrappers, sort by priority, then reverse for stack application
+        List<ClientTransportWrapper> wrappers = wrapperLoader.stream().map(Provider::get)
+                .sorted()
+                .collect(Collectors.toList());
+
+        if (wrappers.isEmpty()) {
+            LOGGER.debug("No client transport wrappers found via ServiceLoader");
+            return transport;
+        } 
+        LOGGER.debug(wrappers.size() + " client transport wrappers found via ServiceLoader");
+
+        // Reverse to apply lowest priority first (building stack with highest priority outermost)
+        java.util.Collections.reverse(wrappers);
+
+        // Apply wrappers to build stack
+        ClientTransport wrapped = transport;
+        for (ClientTransportWrapper wrapper : wrappers) {
+            try {
+                ClientTransport newWrapped = wrapper.wrap(wrapped, clientTransportConfig);
+                if (newWrapped != wrapped) {
+                    LOGGER.debug("Applied transport wrapper: {} (priority: {})",
+                            wrapper.getClass().getName(), wrapper.priority());
+                }
+                wrapped = newWrapped;
+            } catch (Exception e) {
+                LOGGER.warn("Failed to apply transport wrapper {}: {}",
+                        wrapper.getClass().getName(), e.getMessage(), e);
+            }
+        }
+
+        return wrapped;
+    }
 }

client/transport/rest/src/main/java/io/a2a/client/transport/rest/RestTransportConfig.java

@@ -48,7 +48,7 @@
  * @see A2AHttpClient
  * @see io.a2a.client.http.JdkA2AHttpClient
  */
-public class RestTransportConfig extends ClientTransportConfig<RestTransport>  {
+public class RestTransportConfig extends ClientTransportConfig<RestTransport> {
 
     private final @Nullable A2AHttpClient httpClient;
 

client/transport/spi/src/main/java/io/a2a/client/transport/spi/ClientTransportConfig.java

@@ -1,9 +1,13 @@
 package io.a2a.client.transport.spi;
 
 import java.util.ArrayList;
+
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 import io.a2a.client.transport.spi.interceptors.ClientCallInterceptor;
+import java.util.Collections;
 
 /**
  * Base configuration class for A2A client transport protocols.
@@ -34,7 +38,8 @@
  */
 public abstract class ClientTransportConfig<T extends ClientTransport> {
 
-    protected List<ClientCallInterceptor> interceptors = new ArrayList<>();
+    protected List<ClientCallInterceptor> interceptors = Collections.emptyList();
+    protected Map<String, ? extends Object> parameters = Collections.emptyMap();
 
     /**
      * Set the list of request/response interceptors.
@@ -63,4 +68,28 @@ public void setInterceptors(List<ClientCallInterceptor> interceptors) {
     public List<ClientCallInterceptor> getInterceptors() {
         return java.util.Collections.unmodifiableList(interceptors);
     }
+
+    /**
+     * Set the Map of config parameters.
+     * The provided map is copied to prevent external modifications from affecting
+     * this configuration.
+     *
+     * @param parameters the map of parameters to use (will be copied)
+     */
+    public void setParameters(Map<String, ? extends Object > parameters) {
+        this.parameters = new HashMap<>(parameters);
+    }
+
+
+    /**
+     * Get the list of configured parameters.
+     * <p>
+     * Returns an unmodifiable view of the parameters map. Attempting to modify
+     * the returned map will throw {@link UnsupportedOperationException}.
+     *
+     * @return an unmodifiable map of configured parameters (never null, but may be empty)
+     */
+    public Map<String, ? extends Object > getParameters() {
+        return java.util.Collections.unmodifiableMap(parameters);
+    }
 }

client/transport/spi/src/main/java/io/a2a/client/transport/spi/ClientTransportWrapper.java

@@ -0,0 +1,81 @@
+package io.a2a.client.transport.spi;
+
+/**
+ * Service provider interface for wrapping client transports with additional functionality.
+ * Implementations can add cross-cutting concerns like tracing, metrics, logging, etc.
+ *
+ * <p>Wrappers are discovered via Java's ServiceLoader mechanism. To register a wrapper,
+ * create a file {@code META-INF/services/io.a2a.client.transport.spi.ClientTransportWrapper}
+ * containing the fully qualified class name of your implementation.
+ *
+ * <p>Wrappers are sorted by priority in descending order (highest priority first).
+ * This interface implements {@link Comparable} to enable natural sorting.
+ *
+ * <p>Example implementation:
+ * <pre>{@code
+ * public class TracingWrapper implements ClientTransportWrapper {
+ *     @Override
+ *     public ClientTransport wrap(ClientTransport transport, ClientTransportConfig<?> config) {
+ *         if (config.getParameters().containsKey("tracer")) {
+ *             return new TracingTransport(transport, (Tracer) config.getParameters().get("tracer"));
+ *         }
+ *         return transport;
+ *     }
+ *
+ *     @Override
+ *     public int priority() {
+ *         return 100; // Higher priority = wraps earlier (outermost)
+ *     }
+ * }
+ * }</pre>
+ */
+public interface ClientTransportWrapper extends Comparable<ClientTransportWrapper> {
+
+    /**
+     * Wraps the given transport with additional functionality.
+     *
+     * <p>Implementations should check the configuration to determine if they should
+     * actually wrap the transport. If the wrapper is not applicable (e.g., required
+     * configuration is missing), return the original transport unchanged.
+     *
+     * @param transport the transport to wrap
+     * @param config the transport configuration, may contain wrapper-specific parameters
+     * @return the wrapped transport, or the original if wrapping is not applicable
+     */
+    ClientTransport wrap(ClientTransport transport, ClientTransportConfig<?> config);
+
+    /**
+     * Returns the priority of this wrapper. Higher priority wrappers are applied first
+     * (wrap the transport earlier, resulting in being the outermost wrapper).
+     *
+     * <p>Default priority is 0. Suggested ranges:
+     * <ul>
+     *   <li>1000+ : Critical infrastructure (security, authentication)
+     *   <li>500-999: Observability (tracing, metrics, logging)
+     *   <li>100-499: Enhancement (caching, retry logic)
+     *   <li>0-99: Optional features
+     * </ul>
+     *
+     * @return the priority value, higher values = higher priority
+     */
+    default int priority() {
+        return 0;
+    }
+
+    /**
+     * Compares this wrapper with another based on priority.
+     * Returns a negative integer, zero, or a positive integer as this wrapper
+     * has higher priority than, equal to, or lower priority than the specified wrapper.
+     *
+     * <p>Note: This comparison is reversed (higher priority comes first) to enable
+     * natural sorting in descending priority order.
+     *
+     * @param other the wrapper to compare to
+     * @return negative if this has higher priority, positive if lower, zero if equal
+     */
+    @Override
+    default int compareTo(ClientTransportWrapper other) {
+        // Reverse comparison: higher priority should come first
+        return Integer.compare(other.priority(), this.priority());
+    }
+}