Stable semconv final (?) polishing, JavaDoc updates, minor changes

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

@@ -10,6 +10,7 @@
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.http.internal.HttpAttributes;
 import io.opentelemetry.instrumentation.api.instrumenter.net.internal.InternalNetClientAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.network.internal.InternalNetworkAttributesExtractor;
@@ -23,19 +24,19 @@
 
 /**
  * Extractor of <a
- * href="https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#http-client">HTTP
- * client attributes</a>. Instrumentation of HTTP client frameworks should extend this class,
- * defining {@link REQUEST} and {@link RESPONSE} with the actual request / response types of the
- * instrumented library. If an attribute is not available in this library, it is appropriate to
- * return {@code null} from the protected attribute methods, but implement as many as possible for
- * best compliance with the OpenTelemetry specification.
+ * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#http-client">HTTP
+ * client attributes</a>.
  */
 public final class HttpClientAttributesExtractor<REQUEST, RESPONSE>
     extends HttpCommonAttributesExtractor<
         REQUEST, RESPONSE, HttpClientAttributesGetter<REQUEST, RESPONSE>>
     implements SpanKeyProvider {
 
-  /** Creates the HTTP client attributes extractor with default configuration. */
+  /**
+   * Creates the HTTP client attributes extractor with default configuration.
+   *
+   * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor)
+   */
   public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
       HttpClientAttributesGetter<REQUEST, RESPONSE> httpAttributesGetter) {
     return builder(httpAttributesGetter).build();

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

@@ -10,6 +10,7 @@
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.net.internal.InternalNetClientAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.network.internal.AddressAndPortExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.network.internal.InternalNetworkAttributesExtractor;
@@ -54,12 +55,11 @@ public final class HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE> {
 
   /**
    * Configures the HTTP request headers that will be captured as span attributes as described in <a
-   * href="https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes">HTTP
+   * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#http-client">HTTP
    * semantic conventions</a>.
    *
-   * <p>The HTTP request header values will be captured under the {@code http.request.header.<name>}
-   * attribute key. The {@code <name>} part in the attribute key is the normalized header name:
-   * lowercase, with dashes replaced by underscores.
+   * <p>The HTTP request header values will be captured under the {@code http.request.header.<key>}
+   * attribute key. The {@code <key>} part in the attribute key is the lowercase header name.
    *
    * @param requestHeaders A list of HTTP header names.
    */
@@ -73,12 +73,12 @@ public HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE> setCapturedReques
   /**
    * Configures the HTTP response headers that will be captured as span attributes as described in
    * <a
-   * href="https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes">HTTP
+   * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#common-attributes">HTTP
    * semantic conventions</a>.
    *
    * <p>The HTTP response header values will be captured under the {@code
-   * http.response.header.<name>} attribute key. The {@code <name>} part in the attribute key is the
-   * normalized header name: lowercase, with dashes replaced by underscores.
+   * http.response.header.<key>} attribute key. The {@code <key>} part in the attribute key is the
+   * lowercase header name.
    *
    * @param responseHeaders A list of HTTP header names.
    */
@@ -122,6 +122,8 @@ HttpClientAttributesExtractorBuilder<REQUEST, RESPONSE> setResendCountIncremente
   /**
    * Returns a new {@link HttpClientAttributesExtractor} with the settings of this {@link
    * HttpClientAttributesExtractorBuilder}.
+   *
+   * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor)
    */
   public AttributesExtractor<REQUEST, RESPONSE> build() {
     return new HttpClientAttributesExtractor<>(this);

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

@@ -15,6 +15,7 @@
 import io.opentelemetry.api.metrics.Meter;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.ContextKey;
+import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.OperationListener;
 import io.opentelemetry.instrumentation.api.instrumenter.OperationMetrics;
 import io.opentelemetry.instrumentation.api.internal.SemconvStability;
@@ -24,7 +25,7 @@
 
 /**
  * {@link OperationListener} which keeps track of <a
- * href="https://github.com/open-telemetry/semantic-conventions/blob/main/specification/metrics/semantic_conventions/http-metrics.md#http-client">HTTP
+ * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-metrics.md#http-client">HTTP
  * client metrics</a>.
  */
 public final class HttpClientMetrics implements OperationListener {
@@ -38,9 +39,10 @@ public final class HttpClientMetrics implements OperationListener {
   private static final Logger logger = Logger.getLogger(HttpClientMetrics.class.getName());
 
   /**
-   * Returns a {@link OperationMetrics} which can be used to enable recording of {@link
-   * HttpClientMetrics} on an {@link
-   * io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder}.
+   * Returns an {@link OperationMetrics} instance which can be used to enable recording of {@link
+   * HttpClientMetrics}.
+   *
+   * @see InstrumenterBuilder#addOperationMetrics(OperationMetrics)
    */
   public static OperationMetrics get() {
     return HttpClientMetrics::new;

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

@@ -28,7 +28,7 @@
 
 /**
  * Extractor of <a
- * href="https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes">HTTP
+ * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#common-attributes">HTTP
  * attributes</a> that are common to client and server instrumentations.
  */
 abstract class HttpCommonAttributesExtractor<

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

@@ -7,6 +7,7 @@
 
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.api.internal.HttpConstants;
 import java.util.List;
 import javax.annotation.Nullable;
 
@@ -61,13 +62,13 @@ public interface HttpCommonAttributesGetter<REQUEST, RESPONSE> {
    * received.
    *
    * <p>If this method is not implemented, or if it returns {@code null}, the exception class name
-   * (if any was caught) or the value {@code _OTHER} will be used as error type.
+   * (if any was caught) or the value {@value HttpConstants#_OTHER} will be used as error type.
    *
    * <p>The cardinality of the error type should be low. The instrumentations implementing this
    * method are recommended to document the custom values they support.
    *
-   * <p>Examples: {@code Bad Request}, {@code java.net.UnknownHostException}, {@code request
-   * cancelled}, {@code _OTHER}.
+   * <p>Examples: {@code timeout}, {@code java.net.UnknownHostException}, {@code
+   * server_certificate_invalid}, {@code 500}, {@code _OTHER}.
    */
   @Nullable
   default String getErrorType(

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

@@ -151,7 +151,7 @@ static void applyServerActiveRequestsAdvice(LongUpDownCounterBuilder builder) {
                 SemanticAttributes.HTTP_SCHEME,
                 SemanticAttributes.NET_HOST_NAME,
                 SemanticAttributes.NET_HOST_PORT,
-                // https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-metrics.md#metric-httpserveractive_requests
+                // https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-metrics.md#metric-httpserveractive_requests
                 SemanticAttributes.HTTP_REQUEST_METHOD,
                 SemanticAttributes.URL_SCHEME));
   }

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

@@ -10,6 +10,7 @@
 import io.opentelemetry.api.common.AttributesBuilder;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.net.internal.InternalNetServerAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.network.internal.InternalClientAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.network.internal.InternalNetworkAttributesExtractor;
@@ -23,19 +24,19 @@
 
 /**
  * Extractor of <a
- * href="https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#http-server">HTTP
- * server attributes</a>. Instrumentation of HTTP server frameworks should extend this class,
- * defining {@link REQUEST} and {@link RESPONSE} with the actual request / response types of the
- * instrumented library. If an attribute is not available in this library, it is appropriate to
- * return {@code null} from the protected attribute methods, but implement as many as possible for
- * best compliance with the OpenTelemetry specification.
+ * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#http-server">HTTP
+ * server attributes</a>.
  */
 public final class HttpServerAttributesExtractor<REQUEST, RESPONSE>
     extends HttpCommonAttributesExtractor<
         REQUEST, RESPONSE, HttpServerAttributesGetter<REQUEST, RESPONSE>>
     implements SpanKeyProvider {
 
-  /** Creates the HTTP server attributes extractor with default configuration. */
+  /**
+   * Creates the HTTP server attributes extractor with default configuration.
+   *
+   * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor)
+   */
   public static <REQUEST, RESPONSE> AttributesExtractor<REQUEST, RESPONSE> create(
       HttpServerAttributesGetter<REQUEST, RESPONSE> httpAttributesGetter) {
     return builder(httpAttributesGetter).build();

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

@@ -10,6 +10,7 @@
 import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.AttributesExtractor;
+import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.net.internal.InternalNetServerAttributesExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.network.internal.AddressAndPortExtractor;
 import io.opentelemetry.instrumentation.api.instrumenter.network.internal.ClientAddressAndPortExtractor;
@@ -58,13 +59,13 @@ public final class HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE> {
   }
 
   /**
-   * Configures the HTTP request headers that will be captured as span attributes as described in <a
-   * href="https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes">HTTP
+   * Configures the HTTP response headers that will be captured as span attributes as described in
+   * <a
+   * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#http-server-semantic-conventions">HTTP
    * semantic conventions</a>.
    *
-   * <p>The HTTP request header values will be captured under the {@code http.request.header.<name>}
-   * attribute key. The {@code <name>} part in the attribute key is the normalized header name:
-   * lowercase, with dashes replaced by underscores.
+   * <p>The HTTP request header values will be captured under the {@code http.request.header.<key>}
+   * attribute key. The {@code <key>} part in the attribute key is the lowercase header name.
    *
    * @param requestHeaders A list of HTTP header names.
    */
@@ -78,12 +79,12 @@ public HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE> setCapturedReques
   /**
    * Configures the HTTP response headers that will be captured as span attributes as described in
    * <a
-   * href="https://github.com/open-telemetry/semantic-conventions/blob/main/docs/http/http-spans.md#common-attributes">HTTP
+   * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#common-attributes">HTTP
    * semantic conventions</a>.
    *
    * <p>The HTTP response header values will be captured under the {@code
-   * http.response.header.<name>} attribute key. The {@code <name>} part in the attribute key is the
-   * normalized header name: lowercase, with dashes replaced by underscores.
+   * http.response.header.<key>} attribute key. The {@code <key>} part in the attribute key is the
+   * lowercase header name.
    *
    * @param responseHeaders A list of HTTP header names.
    */
@@ -127,6 +128,8 @@ HttpServerAttributesExtractorBuilder<REQUEST, RESPONSE> setHttpRouteGetter(
   /**
    * Returns a new {@link HttpServerAttributesExtractor} with the settings of this {@link
    * HttpServerAttributesExtractorBuilder}.
+   *
+   * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor)
    */
   public AttributesExtractor<REQUEST, RESPONSE> build() {
     return new HttpServerAttributesExtractor<>(this);

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

@@ -47,8 +47,8 @@ public interface HttpServerAttributesGetter<REQUEST, RESPONSE>
   String getUrlQuery(REQUEST request);
 
   /**
-   * Returns the matched route (path template in the format used by the respective server
-   * framework).
+   * Returns the matched route, that is, the path template in the format used by the respective
+   * server framework.
    *
    * <p>Examples: {@code /users/:userID?}, {@code {controller}/{action}/{id?}}
    */

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

@@ -15,6 +15,7 @@
 import io.opentelemetry.api.metrics.Meter;
 import io.opentelemetry.context.Context;
 import io.opentelemetry.context.ContextKey;
+import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.OperationListener;
 import io.opentelemetry.instrumentation.api.instrumenter.OperationMetrics;
 import io.opentelemetry.instrumentation.api.internal.SemconvStability;
@@ -24,7 +25,7 @@
 
 /**
  * {@link OperationListener} which keeps track of <a
- * href="https://github.com/open-telemetry/semantic-conventions/blob/main/specification/metrics/semantic_conventions/http-metrics.md#http-server">HTTP
+ * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-metrics.md#http-server">HTTP
  * server metrics</a>.
  */
 public final class HttpServerMetrics implements OperationListener {
@@ -38,9 +39,10 @@ public final class HttpServerMetrics implements OperationListener {
   private static final Logger logger = Logger.getLogger(HttpServerMetrics.class.getName());
 
   /**
-   * Returns a {@link OperationMetrics} which can be used to enable recording of {@link
-   * HttpServerMetrics} on an {@link
-   * io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder}.
+   * Returns an {@link OperationMetrics} instance which can be used to enable recording of {@link
+   * HttpServerMetrics}.
+   *
+   * @see InstrumenterBuilder#addOperationMetrics(OperationMetrics)
    */
   public static OperationMetrics get() {
     return HttpServerMetrics::new;

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

@@ -9,9 +9,9 @@
 import io.opentelemetry.context.Context;
 import io.opentelemetry.instrumentation.api.instrumenter.ContextCustomizer;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
 import io.opentelemetry.instrumentation.api.instrumenter.LocalRootSpan;
 import io.opentelemetry.instrumentation.api.internal.HttpRouteState;
-import io.opentelemetry.semconv.SemanticAttributes;
 import javax.annotation.Nullable;
 
 /**
@@ -28,6 +28,8 @@ public final class HttpServerRoute {
   /**
    * Returns a {@link ContextCustomizer} that initializes an {@link HttpServerRoute} in the {@link
    * Context} returned from {@link Instrumenter#start(Context, Object)}.
+   *
+   * @see InstrumenterBuilder#addContextCustomizer(ContextCustomizer)
    */
   public static <REQUEST> ContextCustomizer<REQUEST> create(
       HttpServerAttributesGetter<REQUEST, ?> getter) {
@@ -53,10 +55,6 @@ private HttpServerRoute() {}
    * if and only if the last {@link HttpServerRouteSource} to update the route using this method has
    * strictly lower priority than the provided {@link HttpServerRouteSource}, and the passed value
    * is non-null.
-   *
-   * <p>If there is a server span in the context, and the context has NOT been customized with a
-   * {@link HttpServerRoute}, then this method will update the route using the provided value if it
-   * is non-null.
    */
   public static void update(
       Context context, HttpServerRouteSource source, @Nullable String httpRoute) {
@@ -72,10 +70,6 @@ public static void update(
    * route using this method has strictly lower priority than the provided {@link
    * HttpServerRouteSource}, and the value returned from the {@link HttpServerRouteGetter} is
    * non-null.
-   *
-   * <p>If there is a server span in the context, and the context has NOT been customized with a
-   * {@link HttpServerRoute}, then this method will update the route using the provided {@link
-   * HttpServerRouteGetter} if the value returned from it is non-null.
    */
   public static <T> void update(
       Context context,
@@ -94,10 +88,6 @@ public static <T> void update(
    * route using this method has strictly lower priority than the provided {@link
    * HttpServerRouteSource}, and the value returned from the {@link HttpServerRouteBiGetter} is
    * non-null.
-   *
-   * <p>If there is a server span in the context, and the context has NOT been customized with a
-   * {@code ServerSpanName}, then this method will update the route using the provided {@link
-   * HttpServerRouteBiGetter} if the value returned from it is non-null.
    */
   public static <T, U> void update(
       Context context,
@@ -113,12 +103,6 @@ public static <T, U> void update(
     }
     HttpRouteState httpRouteState = HttpRouteState.fromContextOrNull(context);
     if (httpRouteState == null) {
-      // TODO: remove this branch?
-      String httpRoute = httpRouteGetter.get(context, arg1, arg2);
-      if (httpRoute != null && !httpRoute.isEmpty()) {
-        // update just the attribute - without http.method we can't compute a proper span name here
-        serverSpan.setAttribute(SemanticAttributes.HTTP_ROUTE, httpRoute);
-      }
       return;
     }
     // special case for servlet filters, even when we have a route from previous filter see whether