From 33275b1522066a6a6add0872efce8b3459522001 Mon Sep 17 00:00:00 2001 From: Mateusz Rzeszutek Date: Tue, 7 Nov 2023 17:10:36 +0100 Subject: [PATCH] Stable semconv final (?) polishing, JavaDoc updates, minor changes (#9815) --- .../http/HttpClientAttributesExtractor.java | 15 +-- .../HttpClientAttributesExtractorBuilder.java | 16 +-- .../instrumenter/http/HttpClientMetrics.java | 10 +- .../http/HttpCommonAttributesExtractor.java | 2 +- .../http/HttpCommonAttributesGetter.java | 7 +- .../instrumenter/http/HttpMetricsAdvice.java | 2 +- .../http/HttpServerAttributesExtractor.java | 15 +-- .../HttpServerAttributesExtractorBuilder.java | 19 ++-- .../http/HttpServerAttributesGetter.java | 4 +- .../instrumenter/http/HttpServerMetrics.java | 10 +- .../instrumenter/http/HttpServerRoute.java | 22 +--- .../http/HttpServerRouteBuilder.java | 5 +- .../http/HttpServerRouteSource.java | 2 +- .../http/HttpSpanNameExtractor.java | 100 ++++++++++++------ .../http/HttpSpanNameExtractorBuilder.java | 22 +++- .../http/HttpSpanStatusExtractor.java | 18 ++-- .../api/instrumenter/http/package-info.java | 9 ++ .../network/ClientAttributesExtractor.java | 8 +- .../network/ClientAttributesGetter.java | 5 +- .../network/NetworkAttributesExtractor.java | 8 +- .../network/NetworkAttributesGetter.java | 39 +++---- .../network/ServerAttributesExtractor.java | 8 +- .../network/ServerAttributesGetter.java | 8 +- .../instrumenter/network/package-info.java | 9 ++ .../url/UrlAttributesExtractor.java | 8 +- .../api/instrumenter/url/package-info.java | 9 ++ 26 files changed, 235 insertions(+), 145 deletions(-) create mode 100644 instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/package-info.java create mode 100644 instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/package-info.java create mode 100644 instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/package-info.java diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractor.java index 396e26d341..863471c00d 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractor.java @@ -10,6 +10,7 @@ import static io.opentelemetry.instrumentation.api.internal.AttributesExtractorU 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 @@ import javax.annotation.Nullable; /** * Extractor of HTTP - * client attributes. 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. */ public final class HttpClientAttributesExtractor extends HttpCommonAttributesExtractor< REQUEST, RESPONSE, HttpClientAttributesGetter> 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 AttributesExtractor create( HttpClientAttributesGetter httpAttributesGetter) { return builder(httpAttributesGetter).build(); diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractorBuilder.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractorBuilder.java index dfb3f3f777..f0d886afe6 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractorBuilder.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientAttributesExtractorBuilder.java @@ -10,6 +10,7 @@ import static java.util.Collections.emptyList; 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 { /** * Configures the HTTP request headers that will be captured as span attributes as described in HTTP + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#http-client">HTTP * semantic conventions. * - *

The HTTP request header values will be captured under the {@code http.request.header.} - * attribute key. The {@code } part in the attribute key is the normalized header name: - * lowercase, with dashes replaced by underscores. + *

The HTTP request header values will be captured under the {@code http.request.header.} + * attribute key. The {@code } part in the attribute key is the lowercase header name. * * @param requestHeaders A list of HTTP header names. */ @@ -73,12 +73,12 @@ public final class HttpClientAttributesExtractorBuilder { /** * Configures the HTTP response headers that will be captured as span attributes as described in * HTTP + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#common-attributes">HTTP * semantic conventions. * *

The HTTP response header values will be captured under the {@code - * http.response.header.} attribute key. The {@code } part in the attribute key is the - * normalized header name: lowercase, with dashes replaced by underscores. + * http.response.header.} attribute key. The {@code } part in the attribute key is the + * lowercase header name. * * @param responseHeaders A list of HTTP header names. */ @@ -122,6 +122,8 @@ public final class HttpClientAttributesExtractorBuilder { /** * Returns a new {@link HttpClientAttributesExtractor} with the settings of this {@link * HttpClientAttributesExtractorBuilder}. + * + * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor) */ public AttributesExtractor build() { return new HttpClientAttributesExtractor<>(this); diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientMetrics.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientMetrics.java index 5e61b9046d..4173e27cd6 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientMetrics.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpClientMetrics.java @@ -15,6 +15,7 @@ import io.opentelemetry.api.metrics.DoubleHistogramBuilder; 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 @@ import javax.annotation.Nullable; /** * {@link OperationListener} which keeps track of HTTP + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-metrics.md#http-client">HTTP * client metrics. */ 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; diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesExtractor.java index bf52534da6..b6c56a98d6 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesExtractor.java @@ -28,7 +28,7 @@ import javax.annotation.Nullable; /** * Extractor of HTTP + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#common-attributes">HTTP * attributes that are common to client and server instrumentations. */ abstract class HttpCommonAttributesExtractor< diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesGetter.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesGetter.java index ebcb4a82a2..76ca717027 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesGetter.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpCommonAttributesGetter.java @@ -7,6 +7,7 @@ package io.opentelemetry.instrumentation.api.instrumenter.http; 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 { * received. * *

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. * *

The cardinality of the error type should be low. The instrumentations implementing this * method are recommended to document the custom values they support. * - *

Examples: {@code Bad Request}, {@code java.net.UnknownHostException}, {@code request - * cancelled}, {@code _OTHER}. + *

Examples: {@code timeout}, {@code java.net.UnknownHostException}, {@code + * server_certificate_invalid}, {@code 500}, {@code _OTHER}. */ @Nullable default String getErrorType( diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpMetricsAdvice.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpMetricsAdvice.java index ba6315b3b9..90721e1550 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpMetricsAdvice.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpMetricsAdvice.java @@ -151,7 +151,7 @@ final class HttpMetricsAdvice { 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)); } diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractor.java index 7450a973c3..02332c0b57 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractor.java @@ -10,6 +10,7 @@ import static io.opentelemetry.instrumentation.api.internal.AttributesExtractorU 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 @@ import javax.annotation.Nullable; /** * Extractor of HTTP - * server attributes. 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. */ public final class HttpServerAttributesExtractor extends HttpCommonAttributesExtractor< REQUEST, RESPONSE, HttpServerAttributesGetter> 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 AttributesExtractor create( HttpServerAttributesGetter httpAttributesGetter) { return builder(httpAttributesGetter).build(); diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractorBuilder.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractorBuilder.java index 9370e0c8c4..03d7a3b8fe 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractorBuilder.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesExtractorBuilder.java @@ -10,6 +10,7 @@ import static java.util.Collections.emptyList; 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 { } /** - * Configures the HTTP request headers that will be captured as span attributes as described in HTTP + * Configures the HTTP response headers that will be captured as span attributes as described in + * HTTP * semantic conventions. * - *

The HTTP request header values will be captured under the {@code http.request.header.} - * attribute key. The {@code } part in the attribute key is the normalized header name: - * lowercase, with dashes replaced by underscores. + *

The HTTP request header values will be captured under the {@code http.request.header.} + * attribute key. The {@code } part in the attribute key is the lowercase header name. * * @param requestHeaders A list of HTTP header names. */ @@ -78,12 +79,12 @@ public final class HttpServerAttributesExtractorBuilder { /** * Configures the HTTP response headers that will be captured as span attributes as described in * HTTP + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#common-attributes">HTTP * semantic conventions. * *

The HTTP response header values will be captured under the {@code - * http.response.header.} attribute key. The {@code } part in the attribute key is the - * normalized header name: lowercase, with dashes replaced by underscores. + * http.response.header.} attribute key. The {@code } part in the attribute key is the + * lowercase header name. * * @param responseHeaders A list of HTTP header names. */ @@ -127,6 +128,8 @@ public final class HttpServerAttributesExtractorBuilder { /** * Returns a new {@link HttpServerAttributesExtractor} with the settings of this {@link * HttpServerAttributesExtractorBuilder}. + * + * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor) */ public AttributesExtractor build() { return new HttpServerAttributesExtractor<>(this); diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesGetter.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesGetter.java index c77e21b45f..9a3deb1bf8 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesGetter.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerAttributesGetter.java @@ -47,8 +47,8 @@ public interface HttpServerAttributesGetter 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. * *

Examples: {@code /users/:userID?}, {@code {controller}/{action}/{id?}} */ diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerMetrics.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerMetrics.java index 4c53a47c62..65e5f9fe09 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerMetrics.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerMetrics.java @@ -15,6 +15,7 @@ import io.opentelemetry.api.metrics.DoubleHistogramBuilder; 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 @@ import javax.annotation.Nullable; /** * {@link OperationListener} which keeps track of HTTP + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-metrics.md#http-server">HTTP * server metrics. */ 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; diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRoute.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRoute.java index 267fbdbf44..2d1dab9ca1 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRoute.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRoute.java @@ -9,9 +9,9 @@ import io.opentelemetry.api.trace.Span; 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 ContextCustomizer create( HttpServerAttributesGetter getter) { @@ -53,10 +55,6 @@ public final class 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. - * - *

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 final class HttpServerRoute { * route using this method has strictly lower priority than the provided {@link * HttpServerRouteSource}, and the value returned from the {@link HttpServerRouteGetter} is * non-null. - * - *

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 void update( Context context, @@ -94,10 +88,6 @@ public final class HttpServerRoute { * route using this method has strictly lower priority than the provided {@link * HttpServerRouteSource}, and the value returned from the {@link HttpServerRouteBiGetter} is * non-null. - * - *

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 void update( Context context, @@ -113,12 +103,6 @@ public final class HttpServerRoute { } 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 diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteBuilder.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteBuilder.java index 4608dc9d52..2dc8cedf40 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteBuilder.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteBuilder.java @@ -9,12 +9,13 @@ import com.google.errorprone.annotations.CanIgnoreReturnValue; 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.internal.HttpConstants; import io.opentelemetry.instrumentation.api.internal.HttpRouteState; import java.util.HashSet; import java.util.Set; -/** A builder of {@link HttpSpanNameExtractor}. */ +/** A builder of {@link HttpServerRoute}. */ public final class HttpServerRouteBuilder { final HttpServerAttributesGetter getter; @@ -48,6 +49,8 @@ public final class HttpServerRouteBuilder { * Returns a {@link ContextCustomizer} that initializes an {@link HttpServerRoute} in the {@link * Context} returned from {@link Instrumenter#start(Context, Object)}. The returned customizer is * configured with the settings of this {@link HttpServerRouteBuilder}. + * + * @see InstrumenterBuilder#addContextCustomizer(ContextCustomizer) */ public ContextCustomizer build() { Set knownMethods = new HashSet<>(this.knownMethods); diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteSource.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteSource.java index 03c7721c31..c7940f7780 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteSource.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpServerRouteSource.java @@ -25,7 +25,7 @@ public enum HttpServerRouteSource { * annotated sub-resource method. Since multiple nested controllers may match the same request, * the one with the longest (most detailed) route will be chosen. */ - NESTED_CONTROLLER(4, false); + NESTED_CONTROLLER(4, /* useFirst= */ false); final int order; final boolean useFirst; diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractor.java index b26c417605..fa34810aa3 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractor.java @@ -5,63 +5,99 @@ package io.opentelemetry.instrumentation.api.instrumenter.http; +import io.opentelemetry.api.OpenTelemetry; +import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter; import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor; -import java.util.HashSet; import java.util.Set; -import javax.annotation.Nullable; /** * Extractor of the HTTP - * span name. Instrumentation of HTTP server or client frameworks should use this class to - * comply with OpenTelemetry HTTP semantic conventions. + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#name">HTTP + * span name. */ -public final class HttpSpanNameExtractor implements SpanNameExtractor { +public final class HttpSpanNameExtractor { /** - * Returns a {@link SpanNameExtractor} which should be used for HTTP requests with default - * configuration. HTTP attributes will be examined to determine the name of the span. + * Returns an HTTP client {@link SpanNameExtractor} with default configuration. + * + * @see Instrumenter#builder(OpenTelemetry, String, SpanNameExtractor) */ public static SpanNameExtractor create( - HttpCommonAttributesGetter getter) { + HttpClientAttributesGetter getter) { return builder(getter).build(); } /** - * Returns a new {@link HttpSpanNameExtractorBuilder} that can be used to configure the HTTP span - * name extractor. + * Returns an HTTP server {@link SpanNameExtractor} with default configuration. + * + * @see Instrumenter#builder(OpenTelemetry, String, SpanNameExtractor) + */ + public static SpanNameExtractor create( + HttpServerAttributesGetter getter) { + return builder(getter).build(); + } + + /** + * Returns a new {@link HttpSpanNameExtractorBuilder} that can be used to configure the HTTP + * client span name extractor. */ public static HttpSpanNameExtractorBuilder builder( - HttpCommonAttributesGetter getter) { - return new HttpSpanNameExtractorBuilder<>(getter); + HttpClientAttributesGetter getter) { + return new HttpSpanNameExtractorBuilder<>(getter, null); } - private final HttpCommonAttributesGetter getter; - private final Set knownMethods; - - HttpSpanNameExtractor(HttpSpanNameExtractorBuilder builder) { - this.getter = builder.httpAttributesGetter; - this.knownMethods = new HashSet<>(builder.knownMethods); + /** + * Returns a new {@link HttpSpanNameExtractorBuilder} that can be used to configure the HTTP + * server span name extractor. + */ + public static HttpSpanNameExtractorBuilder builder( + HttpServerAttributesGetter getter) { + return new HttpSpanNameExtractorBuilder<>(null, getter); } - @Override - public String extract(REQUEST request) { - String method = getter.getHttpRequestMethod(request); - String route = extractRoute(request); - if (method != null) { + static final class Client implements SpanNameExtractor { + + private final HttpClientAttributesGetter getter; + private final Set knownMethods; + + Client(HttpClientAttributesGetter getter, Set knownMethods) { + this.getter = getter; + this.knownMethods = knownMethods; + } + + @Override + public String extract(REQUEST request) { + String method = getter.getHttpRequestMethod(request); + if (method == null || !knownMethods.contains(method)) { + return "HTTP"; + } + return method; + } + } + + static final class Server implements SpanNameExtractor { + + private final HttpServerAttributesGetter getter; + private final Set knownMethods; + + Server(HttpServerAttributesGetter getter, Set knownMethods) { + this.getter = getter; + this.knownMethods = knownMethods; + } + + @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"; } return route == null ? method : method + " " + route; } - return "HTTP"; } - @Nullable - private String extractRoute(REQUEST request) { - if (getter instanceof HttpServerAttributesGetter) { - return ((HttpServerAttributesGetter) getter).getHttpRoute(request); - } - return null; - } + private HttpSpanNameExtractor() {} } diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractorBuilder.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractorBuilder.java index a3444508bb..4c72a8a921 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractorBuilder.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanNameExtractorBuilder.java @@ -5,20 +5,29 @@ package io.opentelemetry.instrumentation.api.instrumenter.http; +import static java.util.Objects.requireNonNull; + import com.google.errorprone.annotations.CanIgnoreReturnValue; +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.HttpConstants; import java.util.HashSet; import java.util.Set; +import javax.annotation.Nullable; /** A builder of {@link HttpSpanNameExtractor}. */ public final class HttpSpanNameExtractorBuilder { - final HttpCommonAttributesGetter httpAttributesGetter; + @Nullable final HttpClientAttributesGetter clientGetter; + @Nullable final HttpServerAttributesGetter serverGetter; Set knownMethods = HttpConstants.KNOWN_METHODS; - HttpSpanNameExtractorBuilder(HttpCommonAttributesGetter httpAttributesGetter) { - this.httpAttributesGetter = httpAttributesGetter; + public HttpSpanNameExtractorBuilder( + @Nullable HttpClientAttributesGetter clientGetter, + @Nullable HttpServerAttributesGetter serverGetter) { + this.clientGetter = clientGetter; + this.serverGetter = serverGetter; } /** @@ -45,8 +54,13 @@ public final class HttpSpanNameExtractorBuilder { /** * Returns a new {@link HttpSpanNameExtractor} with the settings of this {@link * HttpSpanNameExtractorBuilder}. + * + * @see Instrumenter#builder(OpenTelemetry, String, SpanNameExtractor) */ public SpanNameExtractor build() { - return new HttpSpanNameExtractor<>(this); + Set knownMethods = new HashSet<>(this.knownMethods); + return clientGetter != null + ? new HttpSpanNameExtractor.Client<>(clientGetter, knownMethods) + : new HttpSpanNameExtractor.Server<>(requireNonNull(serverGetter), knownMethods); } } diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanStatusExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanStatusExtractor.java index 289b0a9dfa..b1fb02d3c1 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanStatusExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/HttpSpanStatusExtractor.java @@ -6,23 +6,25 @@ package io.opentelemetry.instrumentation.api.instrumenter.http; import io.opentelemetry.api.trace.StatusCode; +import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder; import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusBuilder; import io.opentelemetry.instrumentation.api.instrumenter.SpanStatusExtractor; import javax.annotation.Nullable; /** * Extractor of the HTTP - * span status. Instrumentation of HTTP server or client frameworks should use this class to - * comply with OpenTelemetry HTTP semantic conventions. + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/http/http-spans.md#status">HTTP + * span status. */ public final class HttpSpanStatusExtractor implements SpanStatusExtractor { /** - * Returns the {@link SpanStatusExtractor} for HTTP requests, which will use the HTTP status code - * to determine the {@link StatusCode} if available or fallback to {@linkplain #getDefault() the + * Returns the HTTP client {@link SpanStatusExtractor}, which will use the HTTP status code to + * determine the {@link StatusCode} if available or fallback to {@linkplain #getDefault() the * default status} otherwise. + * + * @see InstrumenterBuilder#setSpanStatusExtractor(SpanStatusExtractor) */ public static SpanStatusExtractor create( HttpClientAttributesGetter getter) { @@ -30,9 +32,11 @@ public final class HttpSpanStatusExtractor } /** - * Returns the {@link SpanStatusExtractor} for HTTP requests, which will use the HTTP status code - * to determine the {@link StatusCode} if available or fallback to {@linkplain #getDefault() the + * Returns the HTTP server {@link SpanStatusExtractor}, which will use the HTTP status code to + * determine the {@link StatusCode} if available or fallback to {@linkplain #getDefault() the * default status} otherwise. + * + * @see InstrumenterBuilder#setSpanStatusExtractor(SpanStatusExtractor) */ public static SpanStatusExtractor create( HttpServerAttributesGetter getter) { diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/package-info.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/package-info.java new file mode 100644 index 0000000000..cd0fdabbec --- /dev/null +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/http/package-info.java @@ -0,0 +1,9 @@ +/** + * This module contains the implementation of the + * OpenTelemetry HTTP semantic conventions. + */ +@ParametersAreNonnullByDefault +package io.opentelemetry.instrumentation.api.instrumenter.http; + +import javax.annotation.ParametersAreNonnullByDefault; diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesExtractor.java index daa4c27866..5a94e19ded 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesExtractor.java @@ -8,6 +8,7 @@ package io.opentelemetry.instrumentation.api.instrumenter.network; 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.network.internal.AddressAndPortExtractor; import io.opentelemetry.instrumentation.api.instrumenter.network.internal.ClientAddressAndPortExtractor; import io.opentelemetry.instrumentation.api.instrumenter.network.internal.InternalClientAttributesExtractor; @@ -16,15 +17,16 @@ import javax.annotation.Nullable; /** * Extractor of client + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/general/attributes.md#client-attributes">client * attributes. */ public final class ClientAttributesExtractor implements AttributesExtractor { /** - * Returns a new {@link ClientAttributesExtractor} that will use the passed {@link - * ClientAttributesGetter}. + * Creates the client attributes extractor. + * + * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor) */ public static ClientAttributesExtractor create( ClientAttributesGetter getter) { diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesGetter.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesGetter.java index 9a1f9ff9bf..6c2875d1b8 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesGetter.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ClientAttributesGetter.java @@ -19,9 +19,10 @@ import javax.annotation.Nullable; public interface ClientAttributesGetter { /** - * Returns the client address - unix domain socket name, IPv4 or IPv6 address. + * Returns the client address - domain name if available without reverse DNS lookup; otherwise, IP + * address or Unix domain socket name. * - *

Examples: {@code /tmp/my.sock}, {@code 10.1.2.80} + *

Examples: {@code client.example.com}, {@code 10.1.2.80}, {@code /tmp/my.sock} */ @Nullable default String getClientAddress(REQUEST request) { diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesExtractor.java index 55e8da02bd..499ebbe2b0 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesExtractor.java @@ -8,6 +8,7 @@ package io.opentelemetry.instrumentation.api.instrumenter.network; 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.network.internal.AddressAndPortExtractor; import io.opentelemetry.instrumentation.api.instrumenter.network.internal.InternalNetworkAttributesExtractor; import io.opentelemetry.instrumentation.api.internal.SemconvStability; @@ -15,15 +16,16 @@ import javax.annotation.Nullable; /** * Extractor of network + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/general/attributes.md#other-network-attributes">network * attributes. */ public final class NetworkAttributesExtractor implements AttributesExtractor { /** - * Returns a new {@link NetworkAttributesExtractor} that will use the passed {@link - * NetworkAttributesGetter}. + * Creates the network attributes extractor. + * + * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor) */ public static NetworkAttributesExtractor create( NetworkAttributesGetter getter) { diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesGetter.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesGetter.java index e369b72f0b..7d03ae43a2 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesGetter.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/NetworkAttributesGetter.java @@ -19,19 +19,7 @@ import javax.annotation.Nullable; public interface NetworkAttributesGetter { /** - * Returns the OSI Transport Layer or Inter-process Communication - * method. - * - *

Examples: {@code tcp}, {@code udp} - */ - @Nullable - default String getNetworkTransport(REQUEST request, @Nullable RESPONSE response) { - return null; - } - - /** - * Returns the OSI Network Layer or non-OSI + * Returns the OSI network layer or non-OSI * equivalent. * *

Examples: {@code ipv4}, {@code ipv6} @@ -44,7 +32,19 @@ public interface NetworkAttributesGetter { } /** - * Returns the OSI Application Layer or + * Returns the OSI transport layer or inter-process communication + * method. + * + *

Examples: {@code tcp}, {@code udp} + */ + @Nullable + default String getNetworkTransport(REQUEST request, @Nullable RESPONSE response) { + return null; + } + + /** + * Returns the OSI application layer or * non-OSI equivalent. * *

Examples: {@code ampq}, {@code http}, {@code mqtt} @@ -55,7 +55,8 @@ public interface NetworkAttributesGetter { } /** - * Returns the version of the application layer protocol used. + * Returns the version of the protocol returned by {@link #getNetworkProtocolName(Object, + * Object)}. * *

Examples: {@code 3.1.1} */ @@ -82,7 +83,7 @@ public interface NetworkAttributesGetter { *

Examples: {@code 10.1.2.80}, {@code /tmp/my.sock} * *

By default, this method attempts to retrieve the local address using the {@link - * #getNetworkLocalInetSocketAddress(Object, Object)} method. If this method is not implemented, + * #getNetworkLocalInetSocketAddress(Object, Object)} method. If that method is not implemented, * it will simply return {@code null}. If the instrumented library does not expose {@link * InetSocketAddress} in its API, you might want to implement this method instead of {@link * #getNetworkLocalInetSocketAddress(Object, Object)}. @@ -98,7 +99,7 @@ public interface NetworkAttributesGetter { *

Examples: {@code 65123} * *

By default, this method attempts to retrieve the local port using the {@link - * #getNetworkLocalInetSocketAddress(Object, Object)} method. If this method is not implemented, + * #getNetworkLocalInetSocketAddress(Object, Object)} method. If that method is not implemented, * it will simply return {@code null}. If the instrumented library does not expose {@link * InetSocketAddress} in its API, you might want to implement this method instead of {@link * #getNetworkLocalInetSocketAddress(Object, Object)}. @@ -126,7 +127,7 @@ public interface NetworkAttributesGetter { *

Examples: {@code 10.1.2.80}, {@code /tmp/my.sock} * *

By default, this method attempts to retrieve the peer address using the {@link - * #getNetworkPeerInetSocketAddress(Object, Object)} method. If this method is not implemented, it + * #getNetworkPeerInetSocketAddress(Object, Object)} method. If that method is not implemented, it * will simply return {@code null}. If the instrumented library does not expose {@link * InetSocketAddress} in its API, you might want to implement this method instead of {@link * #getNetworkPeerInetSocketAddress(Object, Object)}. @@ -142,7 +143,7 @@ public interface NetworkAttributesGetter { *

Examples: {@code 65123} * *

By default, this method attempts to retrieve the peer port using the {@link - * #getNetworkPeerInetSocketAddress(Object, Object)} method. If this method is not implemented, it + * #getNetworkPeerInetSocketAddress(Object, Object)} method. If that method is not implemented, it * will simply return {@code null}. If the instrumented library does not expose {@link * InetSocketAddress} in its API, you might want to implement this method instead of {@link * #getNetworkPeerInetSocketAddress(Object, Object)}. diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesExtractor.java index 9eddcb0c1e..1d76570696 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesExtractor.java @@ -8,6 +8,7 @@ package io.opentelemetry.instrumentation.api.instrumenter.network; 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.network.internal.AddressAndPortExtractor; import io.opentelemetry.instrumentation.api.instrumenter.network.internal.InternalServerAttributesExtractor; import io.opentelemetry.instrumentation.api.instrumenter.network.internal.ServerAddressAndPortExtractor; @@ -16,15 +17,16 @@ import javax.annotation.Nullable; /** * Extractor of server + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/general/attributes.md#server-attributes">server * attributes. */ public final class ServerAttributesExtractor implements AttributesExtractor { /** - * Returns a new {@link ServerAttributesExtractor} that will use the passed {@link - * ServerAttributesGetter}. + * Creates the server attributes extractor. + * + * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor) */ public static ServerAttributesExtractor create( ServerAttributesGetter getter) { diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesGetter.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesGetter.java index fefc9c6301..141ddeed40 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesGetter.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/ServerAttributesGetter.java @@ -19,10 +19,10 @@ import javax.annotation.Nullable; public interface ServerAttributesGetter { /** - * Return the logical server hostname that matches server FQDN if available, and IP or socket - * address if FQDN is not known. + * Returns the server domain name if available without reverse DNS lookup; otherwise, IP address + * or Unix domain socket name. * - *

Examples: {@code example.com} + *

Examples: {@code client.example.com}, {@code 10.1.2.80}, {@code /tmp/my.sock} */ @Nullable default String getServerAddress(REQUEST request) { @@ -30,7 +30,7 @@ public interface ServerAttributesGetter { } /** - * Return the logical server port number. + * Return the server port number. * *

Examples: {@code 80}, {@code 8080}, {@code 443} */ diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/package-info.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/package-info.java new file mode 100644 index 0000000000..02156b6b99 --- /dev/null +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/network/package-info.java @@ -0,0 +1,9 @@ +/** + * This module contains the implementation of the + * OpenTelemetry server, client and shared network attributes semantic conventions. + */ +@ParametersAreNonnullByDefault +package io.opentelemetry.instrumentation.api.instrumenter.network; + +import javax.annotation.ParametersAreNonnullByDefault; diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/UrlAttributesExtractor.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/UrlAttributesExtractor.java index e8d6d02498..ba2203ac1a 100644 --- a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/UrlAttributesExtractor.java +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/UrlAttributesExtractor.java @@ -8,20 +8,22 @@ package io.opentelemetry.instrumentation.api.instrumenter.url; 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.url.internal.InternalUrlAttributesExtractor; import javax.annotation.Nullable; /** * Extractor of URL + * href="https://github.com/open-telemetry/semantic-conventions/blob/v1.23.0/docs/url/url.md">URL * attributes. */ public final class UrlAttributesExtractor implements AttributesExtractor { /** - * Returns a new {@link UrlAttributesExtractor} that will use the passed {@link - * UrlAttributesGetter}. + * Creates the URL attributes extractor. + * + * @see InstrumenterBuilder#addAttributesExtractor(AttributesExtractor) */ public static UrlAttributesExtractor create( UrlAttributesGetter getter) { diff --git a/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/package-info.java b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/package-info.java new file mode 100644 index 0000000000..d25b8e7376 --- /dev/null +++ b/instrumentation-api-semconv/src/main/java/io/opentelemetry/instrumentation/api/instrumenter/url/package-info.java @@ -0,0 +1,9 @@ +/** + * This module contains the implementation of the + * OpenTelemetry URL semantic conventions. + */ +@ParametersAreNonnullByDefault +package io.opentelemetry.instrumentation.api.instrumenter.url; + +import javax.annotation.ParametersAreNonnullByDefault;