Add experimental http client url.template attribute (#13581)

laurit · web-flow · commit 7d1aeb4156ee · 2025-03-27T13:30:36.000+02:00
diff --git a/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpClientInstrumenterBuilder.java b/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpClientInstrumenterBuilder.java
@@ -10,6 +10,7 @@
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.context.propagation.TextMapSetter;
 import io.opentelemetry.instrumentation.api.incubator.config.internal.CommonConfig;
+import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpClientExperimentalAttributesGetter;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpClientExperimentalMetrics;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpClientPeerServiceAttributesExtractor;
 import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpExperimentalAttributesExtractor;
@@ -218,6 +219,13 @@ public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setBuilderCustomi
   }
 
   public Instrumenter<REQUEST, RESPONSE> build() {
+    if (emitExperimentalHttpClientTelemetry
+        && attributesGetter instanceof HttpClientExperimentalAttributesGetter) {
+      HttpClientExperimentalAttributesGetter<REQUEST, RESPONSE> experimentalAttributesGetter =
+          (HttpClientExperimentalAttributesGetter<REQUEST, RESPONSE>) attributesGetter;
+      Experimental.setUrlTemplateExtractor(
+          httpSpanNameExtractorBuilder, experimentalAttributesGetter::getUrlTemplate);
+    }
     SpanNameExtractor<? super REQUEST> spanNameExtractor =
         spanNameExtractorTransformer.apply(httpSpanNameExtractorBuilder.build());
 
diff --git a/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/http/HttpClientExperimentalAttributesGetter.java b/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/http/HttpClientExperimentalAttributesGetter.java
@@ -0,0 +1,22 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.incubator.semconv.http;
+
+import io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesGetter;
+import javax.annotation.Nullable;
+
+/** An interface for getting experimental HTTP client attributes. */
+public interface HttpClientExperimentalAttributesGetter<REQUEST, RESPONSE>
+    extends HttpClientAttributesGetter<REQUEST, RESPONSE> {
+
+  /**
+   * Returns the template used by the http client framework to build the request URL.
+   *
+   * <p>Examples: {@code /users/:userID?}, {@code {controller}/{action}/{id?}}
+   */
+  @Nullable
+  String getUrlTemplate(REQUEST request);
+}
diff --git a/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/http/HttpExperimentalAttributesExtractor.java b/instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/http/HttpExperimentalAttributesExtractor.java
@@ -26,6 +26,9 @@ public final class HttpExperimentalAttributesExtractor<REQUEST, RESPONSE>
   static final AttributeKey<Long> HTTP_RESPONSE_BODY_SIZE =
       AttributeKey.longKey("http.response.body.size");
 
+  // copied from UrlIncubatingAttributes
+  private static final AttributeKey<String> URL_TEMPLATE = AttributeKey.stringKey("url.template");
+
   public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
       HttpClientAttributesGetter<REQUEST, RESPONSE> getter) {
     return new HttpExperimentalAttributesExtractor<>(getter);
@@ -61,6 +64,12 @@ public void onEnd(
       Long responseBodySize = responseBodySize(request, response);
       internalSet(attributes, HTTP_RESPONSE_BODY_SIZE, responseBodySize);
     }
+
+    if (getter instanceof HttpClientExperimentalAttributesGetter) {
+      HttpClientExperimentalAttributesGetter<REQUEST, RESPONSE> experimentalGetter =
+          (HttpClientExperimentalAttributesGetter<REQUEST, RESPONSE>) getter;
+      internalSet(attributes, URL_TEMPLATE, experimentalGetter.getUrlTemplate(request));
+    }
   }
 
   @Nullable
diff --git a/instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/http/HttpExperimentalAttributesExtractorTest.java b/instrumentation-api-incubator/src/test/java/io/opentelemetry/instrumentation/api/incubator/semconv/http/HttpExperimentalAttributesExtractorTest.java
@@ -7,17 +7,20 @@
 
 import static io.opentelemetry.sdk.testing.assertj.OpenTelemetryAssertions.assertThat;
 import static java.util.Collections.singletonList;
-import static org.assertj.core.api.Assertions.entry;
 import static org.mockito.Mockito.when;
 
+import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.common.Attributes;
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
-import io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesGetter;
 import io.opentelemetry.instrumentation.api.semconv.http.HttpCommonAttributesGetter;
 import io.opentelemetry.instrumentation.api.semconv.http.HttpServerAttributesGetter;
 import io.opentelemetry.semconv.incubating.HttpIncubatingAttributes;
+import io.opentelemetry.semconv.incubating.UrlIncubatingAttributes;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
 import org.mockito.Mock;
@@ -26,22 +29,30 @@
 @ExtendWith(MockitoExtension.class)
 class HttpExperimentalAttributesExtractorTest {
 
-  @Mock HttpClientAttributesGetter<String, String> clientGetter;
+  @Mock HttpClientExperimentalAttributesGetter<String, String> clientGetter;
   @Mock HttpServerAttributesGetter<String, String> serverGetter;
 
   @Test
   void shouldExtractRequestAndResponseSizes_client() {
-    runTest(clientGetter, HttpExperimentalAttributesExtractor.create(clientGetter));
+    when(clientGetter.getUrlTemplate("request")).thenReturn("template");
+    runTest(
+        clientGetter,
+        HttpExperimentalAttributesExtractor.create(clientGetter),
+        Collections.singletonMap(UrlIncubatingAttributes.URL_TEMPLATE, "template"));
   }
 
   @Test
   void shouldExtractRequestAndResponseSizes_server() {
-    runTest(serverGetter, HttpExperimentalAttributesExtractor.create(serverGetter));
+    runTest(
+        serverGetter,
+        HttpExperimentalAttributesExtractor.create(serverGetter),
+        Collections.emptyMap());
   }
 
   void runTest(
       HttpCommonAttributesGetter<String, String> getter,
-      AttributesExtractor<String, String> extractor) {
+      AttributesExtractor<String, String> extractor,
+      Map<AttributeKey<?>, ?> expected) {
 
     when(getter.getHttpRequestHeader("request", "content-length")).thenReturn(singletonList("123"));
     when(getter.getHttpResponseHeader("request", "response", "content-length"))
@@ -52,9 +63,9 @@ void runTest(
     assertThat(attributes.build()).isEmpty();
 
     extractor.onEnd(attributes, Context.root(), "request", "response", null);
-    assertThat(attributes.build())
-        .containsOnly(
-            entry(HttpIncubatingAttributes.HTTP_REQUEST_BODY_SIZE, 123L),
-            entry(HttpIncubatingAttributes.HTTP_RESPONSE_BODY_SIZE, 42L));
+    Map<AttributeKey<?>, Object> expectedAttributes = new HashMap<>(expected);
+    expectedAttributes.put(HttpIncubatingAttributes.HTTP_REQUEST_BODY_SIZE, 123L);
+    expectedAttributes.put(HttpIncubatingAttributes.HTTP_RESPONSE_BODY_SIZE, 42L);
+    assertThat(attributes.build().asMap()).containsExactlyInAnyOrderEntriesOf(expectedAttributes);
   }
 }
diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/Experimental.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/internal/Experimental.java
@@ -6,7 +6,9 @@
 package io.opentelemetry.instrumentation.api.internal;
 
 import io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesExtractorBuilder;
+import io.opentelemetry.instrumentation.api.semconv.http.HttpSpanNameExtractorBuilder;
 import java.util.function.BiConsumer;
+import java.util.function.Function;
 import javax.annotation.Nullable;
 
 /**
@@ -19,6 +21,10 @@ public final class Experimental {
   private static volatile BiConsumer<HttpClientAttributesExtractorBuilder<?, ?>, Boolean>
       redactHttpClientQueryParameters;
 
+  @Nullable
+  private static volatile BiConsumer<HttpSpanNameExtractorBuilder<?>, Function<?, String>>
+      urlTemplateExtractorSetter;
+
   private Experimental() {}
 
   public static void setRedactQueryParameters(
@@ -33,4 +39,19 @@ public static void internalSetRedactHttpClientQueryParameters(
           redactHttpClientQueryParameters) {
     Experimental.redactHttpClientQueryParameters = redactHttpClientQueryParameters;
   }
+
+  public static <REQUEST> void setUrlTemplateExtractor(
+      HttpSpanNameExtractorBuilder<REQUEST> builder,
+      Function<REQUEST, String> urlTemplateExtractor) {
+    if (urlTemplateExtractorSetter != null) {
+      urlTemplateExtractorSetter.accept(builder, urlTemplateExtractor);
+    }
+  }
+
+  @SuppressWarnings({"rawtypes", "unchecked"})
+  public static <REQUEST> void internalSetUrlTemplateExtractor(
+      BiConsumer<HttpSpanNameExtractorBuilder<REQUEST>, Function<REQUEST, String>>
+          urlTemplateExtractorSetter) {
+    Experimental.urlTemplateExtractorSetter = (BiConsumer) urlTemplateExtractorSetter;
+  }
 }
diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/semconv/http/HttpSpanNameExtractor.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/semconv/http/HttpSpanNameExtractor.java
@@ -9,6 +9,7 @@
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
 import java.util.Set;
+import java.util.function.Function;
 
 /**
  * Extractor of the <a
@@ -61,19 +62,28 @@ static final class Client<REQUEST> implements SpanNameExtractor<REQUEST> {
 
     private final HttpClientAttributesGetter<REQUEST, ?> getter;
     private final Set<String> knownMethods;
+    private final Function<REQUEST, String> urlTemplateExtractor;
 
-    Client(HttpClientAttributesGetter<REQUEST, ?> getter, Set<String> knownMethods) {
+    Client(
+        HttpClientAttributesGetter<REQUEST, ?> getter,
+        Set<String> knownMethods,
+        Function<REQUEST, String> urlTemplateExtractor) {
       this.getter = getter;
       this.knownMethods = knownMethods;
+      this.urlTemplateExtractor = urlTemplateExtractor;
     }
 
     @Override
     public String extract(REQUEST request) {
       String method = getter.getHttpRequestMethod(request);
-      if (method == null || !knownMethods.contains(method)) {
+      if (method == null) {
         return "HTTP";
       }
-      return method;
+      if (!knownMethods.contains(method)) {
+        method = "HTTP";
+      }
+      String template = urlTemplateExtractor.apply(request);
+      return template == null ? method : method + " " + template;
     }
   }
 
@@ -90,13 +100,13 @@ static final class Server<REQUEST> implements SpanNameExtractor<REQUEST> {
     @Override
     public String extract(REQUEST request) {
       String method = getter.getHttpRequestMethod(request);
-      String route = getter.getHttpRoute(request);
       if (method == null) {
         return "HTTP";
       }
       if (!knownMethods.contains(method)) {
         method = "HTTP";
       }
+      String route = getter.getHttpRoute(request);
       return route == null ? method : method + " " + route;
     }
   }
diff --git a/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/semconv/http/HttpSpanNameExtractorBuilder.java b/instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/semconv/http/HttpSpanNameExtractorBuilder.java
@@ -11,10 +11,12 @@
 import io.opentelemetry.api.OpenTelemetry;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
+import io.opentelemetry.instrumentation.api.internal.Experimental;
 import io.opentelemetry.instrumentation.api.internal.HttpConstants;
 import java.util.Collection;
 import java.util.HashSet;
 import java.util.Set;
+import java.util.function.Function;
 import javax.annotation.Nullable;
 
 /**
@@ -27,6 +29,12 @@ public final class HttpSpanNameExtractorBuilder<REQUEST> {
   @Nullable final HttpClientAttributesGetter<REQUEST, ?> clientGetter;
   @Nullable final HttpServerAttributesGetter<REQUEST, ?> serverGetter;
   Set<String> knownMethods = HttpConstants.KNOWN_METHODS;
+  Function<REQUEST, String> urlTemplateExtractor = unused -> null;
+
+  static {
+    Experimental.internalSetUrlTemplateExtractor(
+        (builder, urlTemplateExtractor) -> builder.urlTemplateExtractor = urlTemplateExtractor);
+  }
 
   public HttpSpanNameExtractorBuilder(
       @Nullable HttpClientAttributesGetter<REQUEST, ?> clientGetter,
@@ -87,7 +95,7 @@ public HttpSpanNameExtractorBuilder<REQUEST> setKnownMethods(Set<String> knownMe
   public SpanNameExtractor<REQUEST> build() {
     Set<String> knownMethods = new HashSet<>(this.knownMethods);
     return clientGetter != null
-        ? new HttpSpanNameExtractor.Client<>(clientGetter, knownMethods)
+        ? new HttpSpanNameExtractor.Client<>(clientGetter, knownMethods, urlTemplateExtractor)
         : new HttpSpanNameExtractor.Server<>(requireNonNull(serverGetter), knownMethods);
   }
 }
diff --git a/instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/semconv/http/HttpSpanNameExtractorTest.java b/instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/semconv/http/HttpSpanNameExtractorTest.java
@@ -9,6 +9,8 @@
 import static org.mockito.ArgumentMatchers.anyMap;
 import static org.mockito.Mockito.when;
 
+import io.opentelemetry.instrumentation.api.incubator.semconv.http.HttpClientExperimentalAttributesGetter;
+import io.opentelemetry.instrumentation.api.internal.Experimental;
 import java.util.Collections;
 import java.util.Map;
 import org.junit.jupiter.api.Test;
@@ -22,7 +24,9 @@
 @MockitoSettings(strictness = Strictness.LENIENT)
 class HttpSpanNameExtractorTest {
 
-  @Mock private HttpClientAttributesGetter<Map<String, String>, Map<String, String>> clientGetter;
+  @Mock
+  private HttpClientExperimentalAttributesGetter<Map<String, String>, Map<String, String>>
+      clientGetter;
 
   @Mock private HttpServerAttributesGetter<Map<String, String>, Map<String, String>> serverGetter;
 
@@ -41,6 +45,16 @@ void method() {
         .isEqualTo("GET");
   }
 
+  @Test
+  void methodAndTemplate() {
+    when(clientGetter.getUrlTemplate(anyMap())).thenReturn("/cats/{id}");
+    when(clientGetter.getHttpRequestMethod(anyMap())).thenReturn("GET");
+    HttpSpanNameExtractorBuilder<Map<String, String>> builder =
+        HttpSpanNameExtractor.builder(clientGetter);
+    Experimental.setUrlTemplateExtractor(builder, clientGetter::getUrlTemplate);
+    assertThat(builder.build().extract(Collections.emptyMap())).isEqualTo("GET /cats/{id}");
+  }
+
   @Test
   void nothing() {
     assertThat(HttpSpanNameExtractor.create(clientGetter).extract(Collections.emptyMap()))
