[DRAFT] Common http telemetry builder interface

docs/apidiffs/current_vs_latest/opentelemetry-instrumentation-api.txt

@@ -1,2 +1,23 @@
 Comparing source compatibility of opentelemetry-instrumentation-api-2.11.0-SNAPSHOT.jar against opentelemetry-instrumentation-api-2.10.0.jar
-No changes.
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	GENERIC TEMPLATES: +++ REQUEST:java.lang.Object, +++ RESPONSE:java.lang.Object
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder<REQUEST,RESPONSE> addAttributesExtractor(io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor<REQUEST,RESPONSE>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.Object build()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder<REQUEST,RESPONSE> setCapturedRequestHeaders(java.util.List<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder<REQUEST,RESPONSE> setCapturedResponseHeaders(java.util.List<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder<REQUEST,RESPONSE> setKnownMethods(java.util.Set<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder<REQUEST,RESPONSE> setSpanNameExtractor(java.util.function.Function<io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor<REQUEST>,io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor<REQUEST>>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder<REQUEST,RESPONSE> setStatusExtractor(java.util.function.Function<io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor<REQUEST,RESPONSE>,io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor<REQUEST,RESPONSE>>)
++++  NEW INTERFACE: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerTelemetryBuilder  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	GENERIC TEMPLATES: +++ REQUEST:java.lang.Object, +++ RESPONSE:java.lang.Object
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerTelemetryBuilder<REQUEST,RESPONSE> addAttributesExtractor(io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor<REQUEST,RESPONSE>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) java.lang.Object build()
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerTelemetryBuilder<REQUEST,RESPONSE> setCapturedRequestHeaders(java.util.List<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerTelemetryBuilder<REQUEST,RESPONSE> setCapturedResponseHeaders(java.util.List<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerTelemetryBuilder<REQUEST,RESPONSE> setKnownMethods(java.util.Set<java.lang.String>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerTelemetryBuilder<REQUEST,RESPONSE> setSpanNameExtractor(java.util.function.Function<io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor<REQUEST>,io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor<REQUEST>>)
+	+++  NEW METHOD: PUBLIC(+) ABSTRACT(+) io.opentelemetry.instrumentation.api.semconv.http.HttpServerTelemetryBuilder<REQUEST,RESPONSE> setStatusExtractor(java.util.function.Function<io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor<REQUEST,RESPONSE>,io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor<REQUEST,RESPONSE>>)

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpClientInstrumenterBuilder.java

@@ -50,17 +50,15 @@ public final class DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> {
 
   private final List<AttributesExtractor<? super REQUEST, ? super RESPONSE>> additionalExtractors =
       new ArrayList<>();
-  private Function<
-          SpanStatusExtractor<? super REQUEST, ? super RESPONSE>,
-          ? extends SpanStatusExtractor<? super REQUEST, ? super RESPONSE>>
+  private Function<SpanStatusExtractor<REQUEST, RESPONSE>, SpanStatusExtractor<REQUEST, RESPONSE>>
       statusExtractorTransformer = Function.identity();
   private final HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE>
       httpAttributesExtractorBuilder;
   private final HttpClientAttributesGetter<REQUEST, RESPONSE> attributesGetter;
   private final HttpSpanNameExtractorBuilder<REQUEST> httpSpanNameExtractorBuilder;
 
   @Nullable private final TextMapSetter<REQUEST> headerSetter;
-  private Function<SpanNameExtractor<? super REQUEST>, ? extends SpanNameExtractor<? super REQUEST>>
+  private Function<SpanNameExtractor<REQUEST>, ? extends SpanNameExtractor<REQUEST>>
       spanNameExtractorTransformer = Function.identity();
   private boolean emitExperimentalHttpClientMetrics = false;
   private Consumer<InstrumenterBuilder<REQUEST, RESPONSE>> builderCustomizer = b -> {};
@@ -103,17 +101,15 @@ public static <REQUEST, RESPONSE> DefaultHttpClientInstrumenterBuilder<REQUEST,
    * items. The {@link AttributesExtractor} will be executed after all default extractors.
    */
   @CanIgnoreReturnValue
-  public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> addAttributeExtractor(
+  public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> addAttributesExtractor(
       AttributesExtractor<? super REQUEST, ? super RESPONSE> attributesExtractor) {
     additionalExtractors.add(attributesExtractor);
     return this;
   }
 
   @CanIgnoreReturnValue
   public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setStatusExtractor(
-      Function<
-              SpanStatusExtractor<? super REQUEST, ? super RESPONSE>,
-              ? extends SpanStatusExtractor<? super REQUEST, ? super RESPONSE>>
+      Function<SpanStatusExtractor<REQUEST, RESPONSE>, SpanStatusExtractor<REQUEST, RESPONSE>>
           statusExtractor) {
     this.statusExtractorTransformer = statusExtractor;
     return this;
@@ -180,7 +176,7 @@ public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setKnownMethods(
   /** Sets custom {@link SpanNameExtractor} via transform function. */
   @CanIgnoreReturnValue
   public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setSpanNameExtractor(
-      Function<SpanNameExtractor<? super REQUEST>, ? extends SpanNameExtractor<? super REQUEST>>
+      Function<SpanNameExtractor<REQUEST>, SpanNameExtractor<REQUEST>>
           spanNameExtractorTransformer) {
     this.spanNameExtractorTransformer = spanNameExtractorTransformer;
     return this;
@@ -190,15 +186,15 @@ public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setSpanNameExtrac
   @CanIgnoreReturnValue
   public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setPeerServiceResolver(
       PeerServiceResolver peerServiceResolver) {
-    return addAttributeExtractor(
+    return addAttributesExtractor(
         HttpClientPeerServiceAttributesExtractor.create(attributesGetter, peerServiceResolver));
   }
 
   /** Sets the {@code peer.service} attribute for http client spans. */
   @CanIgnoreReturnValue
   public DefaultHttpClientInstrumenterBuilder<REQUEST, RESPONSE> setPeerService(
       String peerService) {
-    return addAttributeExtractor(AttributesExtractor.constant(PEER_SERVICE, peerService));
+    return addAttributesExtractor(AttributesExtractor.constant(PEER_SERVICE, peerService));
   }
 
   @CanIgnoreReturnValue

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/builder/internal/DefaultHttpServerInstrumenterBuilder.java

@@ -46,16 +46,14 @@ public final class DefaultHttpServerInstrumenterBuilder<REQUEST, RESPONSE> {
 
   private final List<AttributesExtractor<? super REQUEST, ? super RESPONSE>> additionalExtractors =
       new ArrayList<>();
-  private Function<
-          SpanStatusExtractor<? super REQUEST, ? super RESPONSE>,
-          ? extends SpanStatusExtractor<? super REQUEST, ? super RESPONSE>>
+  private Function<SpanStatusExtractor<REQUEST, RESPONSE>, SpanStatusExtractor<REQUEST, RESPONSE>>
       statusExtractorTransformer = Function.identity();
   private final HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE>
       httpAttributesExtractorBuilder;
   private final HttpSpanNameExtractorBuilder<REQUEST> httpSpanNameExtractorBuilder;
 
   @Nullable private final TextMapGetter<REQUEST> headerGetter;
-  private Function<SpanNameExtractor<? super REQUEST>, ? extends SpanNameExtractor<? super REQUEST>>
+  private Function<SpanNameExtractor<REQUEST>, SpanNameExtractor<REQUEST>>
       spanNameExtractorTransformer = Function.identity();
   private final HttpServerRouteBuilder<REQUEST> httpServerRouteBuilder;
   private final HttpServerAttributesGetter<REQUEST, RESPONSE> attributesGetter;
@@ -109,9 +107,7 @@ public DefaultHttpServerInstrumenterBuilder<REQUEST, RESPONSE> addAttributesExtr
 
   @CanIgnoreReturnValue
   public DefaultHttpServerInstrumenterBuilder<REQUEST, RESPONSE> setStatusExtractor(
-      Function<
-              SpanStatusExtractor<? super REQUEST, ? super RESPONSE>,
-              ? extends SpanStatusExtractor<? super REQUEST, ? super RESPONSE>>
+      Function<SpanStatusExtractor<REQUEST, RESPONSE>, SpanStatusExtractor<REQUEST, RESPONSE>>
           statusExtractor) {
     this.statusExtractorTransformer = statusExtractor;
     return this;
@@ -179,7 +175,7 @@ public DefaultHttpServerInstrumenterBuilder<REQUEST, RESPONSE> setKnownMethods(
   /** Sets custom {@link SpanNameExtractor} via transform function. */
   @CanIgnoreReturnValue
   public DefaultHttpServerInstrumenterBuilder<REQUEST, RESPONSE> setSpanNameExtractor(
-      Function<SpanNameExtractor<? super REQUEST>, ? extends SpanNameExtractor<? super REQUEST>>
+      Function<SpanNameExtractor<REQUEST>, SpanNameExtractor<REQUEST>>
           spanNameExtractorTransformer) {
     this.spanNameExtractorTransformer = spanNameExtractorTransformer;
     return this;

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/semconv/http/HttpClientTelemetryBuilder.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.semconv.http;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor;
+import java.util.List;
+import java.util.Set;
+import java.util.function.Function;
+
+public interface HttpClientTelemetryBuilder<REQUEST, RESPONSE> {
+
+  @CanIgnoreReturnValue
+  HttpClientTelemetryBuilder<REQUEST, RESPONSE> addAttributesExtractor(
+      AttributesExtractor<REQUEST, RESPONSE> attributesExtractor);
+
+  @CanIgnoreReturnValue
+  HttpClientTelemetryBuilder<REQUEST, RESPONSE> setCapturedRequestHeaders(
+      List<String> requestHeaders);
+
+  @CanIgnoreReturnValue
+  HttpClientTelemetryBuilder<REQUEST, RESPONSE> setCapturedResponseHeaders(
+      List<String> responseHeaders);
+
+  @CanIgnoreReturnValue
+  HttpClientTelemetryBuilder<REQUEST, RESPONSE> setKnownMethods(Set<String> knownMethods);
+
+  @CanIgnoreReturnValue
+  HttpClientTelemetryBuilder<REQUEST, RESPONSE> setSpanNameExtractor(
+      Function<SpanNameExtractor<REQUEST>, SpanNameExtractor<REQUEST>>
+          spanNameExtractorTransformer);
+
+  @CanIgnoreReturnValue
+  HttpClientTelemetryBuilder<REQUEST, RESPONSE> setStatusExtractor(
+      Function<SpanStatusExtractor<REQUEST, RESPONSE>, SpanStatusExtractor<REQUEST, RESPONSE>>
+          statusExtractorTransformer);
+
+  Object build();
+}

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/semconv/http/HttpServerTelemetryBuilder.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.semconv.http;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor;
+import java.util.List;
+import java.util.Set;
+import java.util.function.Function;
+
+public interface HttpServerTelemetryBuilder<REQUEST, RESPONSE> {
+
+  @CanIgnoreReturnValue
+  HttpServerTelemetryBuilder<REQUEST, RESPONSE> addAttributesExtractor(
+      AttributesExtractor<REQUEST, RESPONSE> attributesExtractor);
+
+  @CanIgnoreReturnValue
+  HttpServerTelemetryBuilder<REQUEST, RESPONSE> setCapturedRequestHeaders(
+      List<String> requestHeaders);
+
+  @CanIgnoreReturnValue
+  HttpServerTelemetryBuilder<REQUEST, RESPONSE> setCapturedResponseHeaders(
+      List<String> responseHeaders);
+
+  @CanIgnoreReturnValue
+  HttpServerTelemetryBuilder<REQUEST, RESPONSE> setKnownMethods(Set<String> knownMethods);
+
+  @CanIgnoreReturnValue
+  HttpServerTelemetryBuilder<REQUEST, RESPONSE> setSpanNameExtractor(
+      Function<SpanNameExtractor<REQUEST>, SpanNameExtractor<REQUEST>>
+          spanNameExtractorTransformer);
+
+  @CanIgnoreReturnValue
+  HttpServerTelemetryBuilder<REQUEST, RESPONSE> setStatusExtractor(
+      Function<SpanStatusExtractor<REQUEST, RESPONSE>, SpanStatusExtractor<REQUEST, RESPONSE>>
+          statusExtractorTransformer);
+
+  Object build();
+}

instrumentation/apache-httpclient/apache-httpclient-4.3/library/src/main/java/io/opentelemetry/instrumentation/apachehttpclient/v4_3/ApacheHttpClientTelemetryBuilder.java

@@ -7,17 +7,21 @@
 
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.api.OpenTelemetry;
+import io.opentelemetry.instrumentation.apachehttpclient.v4_3.internal.Experimental;
 import io.opentelemetry.instrumentation.api.incubator.builder.internal.DefaultHttpClientInstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor;
 import io.opentelemetry.instrumentation.api.semconv.http.HttpClientAttributesExtractorBuilder;
+import io.opentelemetry.instrumentation.api.semconv.http.HttpClientTelemetryBuilder;
 import java.util.List;
 import java.util.Set;
 import java.util.function.Function;
 import org.apache.http.HttpResponse;
 
 /** A builder for {@link ApacheHttpClientTelemetry}. */
-public final class ApacheHttpClientTelemetryBuilder {
+public final class ApacheHttpClientTelemetryBuilder
+    implements HttpClientTelemetryBuilder<ApacheHttpClientRequest, HttpResponse> {
 
   private static final String INSTRUMENTATION_NAME = "io.opentelemetry.apache-httpclient-4.3";
   private final DefaultHttpClientInstrumenterBuilder<ApacheHttpClientRequest, HttpResponse> builder;
@@ -33,12 +37,27 @@ public final class ApacheHttpClientTelemetryBuilder {
   /**
    * Adds an additional {@link AttributesExtractor} to invoke to set attributes to instrumented
    * items. The {@link AttributesExtractor} will be executed after all default extractors.
+   *
+   * @deprecated Use {@link #addAttributesExtractor(AttributesExtractor)} instead.
    */
+  @Deprecated
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder addAttributeExtractor(
       AttributesExtractor<? super ApacheHttpClientRequest, ? super HttpResponse>
           attributesExtractor) {
-    builder.addAttributeExtractor(attributesExtractor);
+    builder.addAttributesExtractor(attributesExtractor);
+    return this;
+  }
+
+  /**
+   * Adds an additional {@link AttributesExtractor} to invoke to set attributes to instrumented
+   * items. The {@link AttributesExtractor} will be executed after all default extractors.
+   */
+  @Override
+  @CanIgnoreReturnValue
+  public ApacheHttpClientTelemetryBuilder addAttributesExtractor(
+      AttributesExtractor<ApacheHttpClientRequest, HttpResponse> attributesExtractor) {
+    builder.addAttributesExtractor(attributesExtractor);
     return this;
   }
 
@@ -47,6 +66,7 @@ public ApacheHttpClientTelemetryBuilder addAttributeExtractor(
    *
    * @param requestHeaders A list of HTTP header names.
    */
+  @Override
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setCapturedRequestHeaders(List<String> requestHeaders) {
     builder.setCapturedRequestHeaders(requestHeaders);
@@ -58,6 +78,7 @@ public ApacheHttpClientTelemetryBuilder setCapturedRequestHeaders(List<String> r
    *
    * @param responseHeaders A list of HTTP header names.
    */
+  @Override
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setCapturedResponseHeaders(List<String> responseHeaders) {
     builder.setCapturedResponseHeaders(responseHeaders);
@@ -77,6 +98,7 @@ public ApacheHttpClientTelemetryBuilder setCapturedResponseHeaders(List<String>
    * @param knownMethods A set of recognized HTTP request methods.
    * @see HttpClientAttributesExtractorBuilder#setKnownMethods(Set)
    */
+  @Override
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setKnownMethods(Set<String> knownMethods) {
     builder.setKnownMethods(knownMethods);
@@ -88,7 +110,11 @@ public ApacheHttpClientTelemetryBuilder setKnownMethods(Set<String> knownMethods
    *
    * @param emitExperimentalHttpClientMetrics {@code true} if the experimental HTTP client metrics
    *     are to be emitted.
+   * @deprecated Use {@link
+   *     Experimental#setEmitExperimentalTelemetry(ApacheHttpClientTelemetryBuilder, boolean)}
+   *     instead.
    */
+  @Deprecated
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setEmitExperimentalHttpClientMetrics(
       boolean emitExperimentalHttpClientMetrics) {
@@ -97,20 +123,32 @@ public ApacheHttpClientTelemetryBuilder setEmitExperimentalHttpClientMetrics(
   }
 
   /** Sets custom {@link SpanNameExtractor} via transform function. */
+  @Override
   @CanIgnoreReturnValue
   public ApacheHttpClientTelemetryBuilder setSpanNameExtractor(
       Function<
-              SpanNameExtractor<? super ApacheHttpClientRequest>,
-              ? extends SpanNameExtractor<? super ApacheHttpClientRequest>>
+              SpanNameExtractor<ApacheHttpClientRequest>,
+              SpanNameExtractor<ApacheHttpClientRequest>>
           spanNameExtractorTransformer) {
     builder.setSpanNameExtractor(spanNameExtractorTransformer);
     return this;
   }
 
+  @Override
+  public ApacheHttpClientTelemetryBuilder setStatusExtractor(
+      Function<
+              SpanStatusExtractor<ApacheHttpClientRequest, HttpResponse>,
+              SpanStatusExtractor<ApacheHttpClientRequest, HttpResponse>>
+          statusExtractorTransformer) {
+    builder.setStatusExtractor(statusExtractorTransformer);
+    return this;
+  }
+
   /**
    * Returns a new {@link ApacheHttpClientTelemetry} configured with this {@link
    * ApacheHttpClientTelemetryBuilder}.
    */
+  @Override
   public ApacheHttpClientTelemetry build() {
     return new ApacheHttpClientTelemetry(builder.build(), openTelemetry.getPropagators());
   }