diff --git a/spring-web/src/main/java/org/springframework/http/server/observation/OpenTelemetryServerHttpObservationDocumentation.java b/spring-web/src/main/java/org/springframework/http/server/observation/OpenTelemetryServerHttpObservationDocumentation.java new file mode 100644 index 000000000000..7ab2740ba8b5 --- /dev/null +++ b/spring-web/src/main/java/org/springframework/http/server/observation/OpenTelemetryServerHttpObservationDocumentation.java @@ -0,0 +1,156 @@ +/* + * Copyright 2002-present the original author or authors. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * https://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.springframework.http.server.observation; + +import io.micrometer.common.KeyValue; +import io.micrometer.common.docs.KeyName; +import io.micrometer.observation.Observation; +import io.micrometer.observation.ObservationConvention; +import io.micrometer.observation.docs.ObservationDocumentation; + +/** + * Documented {@link KeyValue KeyValues} for the HTTP server + * observations for Servlet-based web applications, following the stable OpenTelemetry semantic conventions. + * + *
This class is used by automated tools to document KeyValues attached to the
+ * HTTP server observations.
+ *
+ * @author Brian Clozel
+ * @author Tommy Ludwig
+ * @since 7.0
+ * @see OpenTelemetry Semantic Conventions for HTTP Metrics (v1.36.0)
+ * @see OpenTelemetry Semantic Conventions for HTTP Spans (v1.36.0)
+ */
+public enum OpenTelemetryServerHttpObservationDocumentation implements ObservationDocumentation {
+
+ /**
+ * HTTP request observations for Servlet-based servers.
+ */
+ HTTP_SERVLET_SERVER_REQUESTS {
+ @Override
+ public Class extends ObservationConvention extends Observation.Context>> getDefaultConvention() {
+ return OpenTelemetryServerRequestObservationConvention.class;
+ }
+
+ @Override
+ public KeyName[] getLowCardinalityKeyNames() {
+ return LowCardinalityKeyNames.values();
+ }
+
+ @Override
+ public KeyName[] getHighCardinalityKeyNames() {
+ return HighCardinalityKeyNames.values();
+ }
+
+ };
+
+ public enum LowCardinalityKeyNames implements KeyName {
+
+ /**
+ * Name of the HTTP request method or {@value KeyValue#NONE_VALUE} if the
+ * request was not received properly. Normalized to known methods defined in internet standards.
+ */
+ METHOD {
+ @Override
+ public String asString() {
+ return "http.request.method";
+ }
+
+ },
+
+ /**
+ * HTTP response raw status code, or {@code "UNKNOWN"} if no response was
+ * created.
+ */
+ STATUS {
+ @Override
+ public String asString() {
+ return "http.response.status_code";
+ }
+ },
+
+ /**
+ * URI pattern for the matching handler if available, falling back to
+ * {@code REDIRECTION} for 3xx responses, {@code NOT_FOUND} for 404
+ * responses, {@code root} for requests with no path info, and
+ * {@code UNKNOWN} for all other requests.
+ */
+ ROUTE {
+ @Override
+ public String asString() {
+ return "http.route";
+ }
+ },
+
+ /**
+ * Fully qualified name of the exception thrown during the exchange, or
+ * {@value KeyValue#NONE_VALUE} if no exception was thrown.
+ */
+ EXCEPTION {
+ @Override
+ public String asString() {
+ return "error.type";
+ }
+ },
+
+ /**
+ * The scheme of the original client request, if known (e.g. from Forwarded#proto, X-Forwarded-Proto, or a similar header). Otherwise, the scheme of the immediate peer request.
+ */
+ SCHEME {
+ @Override
+ public String asString() {
+ return "url.scheme";
+ }
+ },
+
+ /**
+ * Outcome of the HTTP server exchange.
+ * @see org.springframework.http.HttpStatus.Series
+ */
+ OUTCOME {
+ @Override
+ public String asString() {
+ return "outcome";
+ }
+ }
+ }
+
+ public enum HighCardinalityKeyNames implements KeyName {
+
+ /**
+ * HTTP request URL.
+ */
+ URL_PATH {
+ @Override
+ public String asString() {
+ return "url.path";
+ }
+ },
+
+ /**
+ * Original HTTP method sent by the client in the request line.
+ */
+ METHOD_ORIGINAL {
+ @Override
+ public String asString() {
+ return "http.request.method_original";
+ }
+ }
+
+ }
+
+}
diff --git a/spring-web/src/main/java/org/springframework/http/server/observation/OpenTelemetryServerRequestObservationConvention.java b/spring-web/src/main/java/org/springframework/http/server/observation/OpenTelemetryServerRequestObservationConvention.java
new file mode 100644
index 000000000000..8a1dcfd95a72
--- /dev/null
+++ b/spring-web/src/main/java/org/springframework/http/server/observation/OpenTelemetryServerRequestObservationConvention.java
@@ -0,0 +1,229 @@
+/*
+ * Copyright 2002-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.http.server.observation;
+
+import java.util.Set;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.common.KeyValues;
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.http.HttpMethod;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.HttpStatusCode;
+import org.springframework.http.server.observation.OpenTelemetryServerHttpObservationDocumentation.HighCardinalityKeyNames;
+import org.springframework.http.server.observation.OpenTelemetryServerHttpObservationDocumentation.LowCardinalityKeyNames;
+
+/**
+ * A {@link ServerRequestObservationConvention} based on the stable OpenTelemetry semantic conventions.
+ *
+ * @author Brian Clozel
+ * @author Tommy Ludwig
+ * @since 7.0
+ * @see OpenTelemetryServerHttpObservationDocumentation
+ */
+public class OpenTelemetryServerRequestObservationConvention implements ServerRequestObservationConvention {
+
+ private static final String NAME = "http.server.request.duration";
+
+ private static final KeyValue METHOD_UNKNOWN = KeyValue.of(LowCardinalityKeyNames.METHOD, "_OTHER");
+
+ private static final KeyValue SCHEME_UNKNOWN = KeyValue.of(LowCardinalityKeyNames.SCHEME, "UNKNOWN");
+
+ private static final KeyValue STATUS_UNKNOWN = KeyValue.of(LowCardinalityKeyNames.STATUS, "UNKNOWN");
+
+ private static final KeyValue HTTP_OUTCOME_SUCCESS = KeyValue.of(LowCardinalityKeyNames.OUTCOME, "SUCCESS");
+
+ private static final KeyValue HTTP_OUTCOME_UNKNOWN = KeyValue.of(LowCardinalityKeyNames.OUTCOME, "UNKNOWN");
+
+ private static final KeyValue ROUTE_UNKNOWN = KeyValue.of(LowCardinalityKeyNames.ROUTE, "UNKNOWN");
+
+ private static final KeyValue ROUTE_ROOT = KeyValue.of(LowCardinalityKeyNames.ROUTE, "root");
+
+ private static final KeyValue ROUTE_NOT_FOUND = KeyValue.of(LowCardinalityKeyNames.ROUTE, "NOT_FOUND");
+
+ private static final KeyValue ROUTE_REDIRECTION = KeyValue.of(LowCardinalityKeyNames.ROUTE, "REDIRECTION");
+
+ private static final KeyValue EXCEPTION_NONE = KeyValue.of(LowCardinalityKeyNames.EXCEPTION, KeyValue.NONE_VALUE);
+
+ private static final KeyValue HTTP_URL_UNKNOWN = KeyValue.of(HighCardinalityKeyNames.URL_PATH, "UNKNOWN");
+
+ private static final KeyValue ORIGINAL_METHOD_UNKNOWN = KeyValue.of(HighCardinalityKeyNames.METHOD_ORIGINAL, "UNKNOWN");
+
+ private static final Set
+ * The {@code {method}} MUST be {@code {http.request.method}} if the method represents the original
+ * method known to the instrumentation. In other cases (when Customize Toolbar… is
+ * set to {@code _OTHER}), {@code {method}} MUST be HTTP.
+ *
+ * The {@code target} SHOULD be the {@code {http.route}}.
+ * @param context context
+ * @return contextual name
+ * @see OpenTelemetry Semantic Convention HTTP Span Name (v1.36.0)
+ */
+ @Override
+ public String getContextualName(ServerRequestObservationContext context) {
+ if (context.getCarrier() == null) {
+ return "HTTP";
+ }
+ String maybeMethod = getMethodValue(context);
+ String method = maybeMethod == null ? "HTTP" : maybeMethod;
+ String target = context.getPathPattern();
+ if (target != null) {
+ return method + " " + target;
+ }
+ return method;
+ }
+
+ @Override
+ public KeyValues getLowCardinalityKeyValues(ServerRequestObservationContext context) {
+ // Make sure that KeyValues entries are already sorted by name for better performance
+ return KeyValues.of(exception(context), method(context), status(context), pathTemplate(context), outcome(context), scheme(context));
+ }
+
+ @Override
+ public KeyValues getHighCardinalityKeyValues(ServerRequestObservationContext context) {
+ // Make sure that KeyValues entries are already sorted by name for better performance
+ return KeyValues.of(methodOriginal(context), httpUrl(context));
+ }
+
+ protected KeyValue method(ServerRequestObservationContext context) {
+ String method = getMethodValue(context);
+ if (method != null) {
+ return KeyValue.of(LowCardinalityKeyNames.METHOD, method);
+ }
+ return METHOD_UNKNOWN;
+ }
+
+ protected @Nullable String getMethodValue(ServerRequestObservationContext context) {
+ if (context.getCarrier() != null) {
+ String httpMethod = context.getCarrier().getMethod();
+ if (HTTP_METHODS.contains(httpMethod)) {
+ return httpMethod;
+ }
+ }
+ return null;
+ }
+
+ protected KeyValue scheme(ServerRequestObservationContext context) {
+ if (context.getCarrier() != null) {
+ return KeyValue.of(LowCardinalityKeyNames.SCHEME, context.getCarrier().getScheme());
+ }
+ return SCHEME_UNKNOWN;
+ }
+
+ protected KeyValue status(ServerRequestObservationContext context) {
+ return (context.getResponse() != null) ?
+ KeyValue.of(LowCardinalityKeyNames.STATUS, Integer.toString(context.getResponse().getStatus())) :
+ STATUS_UNKNOWN;
+ }
+
+ protected KeyValue pathTemplate(ServerRequestObservationContext context) {
+ if (context.getCarrier() != null) {
+ String pattern = context.getPathPattern();
+ if (pattern != null) {
+ if (pattern.isEmpty()) {
+ return ROUTE_ROOT;
+ }
+ return KeyValue.of(LowCardinalityKeyNames.ROUTE, pattern);
+ }
+ if (context.getResponse() != null) {
+ HttpStatus status = HttpStatus.resolve(context.getResponse().getStatus());
+ if (status != null) {
+ if (status.is3xxRedirection()) {
+ return ROUTE_REDIRECTION;
+ }
+ if (status == HttpStatus.NOT_FOUND) {
+ return ROUTE_NOT_FOUND;
+ }
+ }
+ }
+ }
+ return ROUTE_UNKNOWN;
+ }
+
+ protected KeyValue exception(ServerRequestObservationContext context) {
+ Throwable error = context.getError();
+ if (error != null) {
+ return KeyValue.of(LowCardinalityKeyNames.EXCEPTION, error.getClass().getName());
+ }
+ return EXCEPTION_NONE;
+ }
+
+ protected KeyValue outcome(ServerRequestObservationContext context) {
+ try {
+ if (context.getResponse() != null) {
+ HttpStatusCode statusCode = HttpStatusCode.valueOf(context.getResponse().getStatus());
+ return HttpOutcome.forStatus(statusCode);
+ }
+ }
+ catch (IllegalArgumentException ex) {
+ return HTTP_OUTCOME_UNKNOWN;
+ }
+ return HTTP_OUTCOME_UNKNOWN;
+ }
+
+ protected KeyValue httpUrl(ServerRequestObservationContext context) {
+ if (context.getCarrier() != null) {
+ return KeyValue.of(HighCardinalityKeyNames.URL_PATH, context.getCarrier().getRequestURI());
+ }
+ return HTTP_URL_UNKNOWN;
+ }
+
+ protected KeyValue methodOriginal(ServerRequestObservationContext context) {
+ if (context.getCarrier() != null) {
+ return KeyValue.of(HighCardinalityKeyNames.METHOD_ORIGINAL, context.getCarrier().getMethod());
+ }
+ return ORIGINAL_METHOD_UNKNOWN;
+ }
+
+ static class HttpOutcome {
+
+ static KeyValue forStatus(HttpStatusCode statusCode) {
+ if (statusCode.is2xxSuccessful()) {
+ return HTTP_OUTCOME_SUCCESS;
+ }
+ else if (statusCode instanceof HttpStatus status) {
+ return KeyValue.of(LowCardinalityKeyNames.OUTCOME, status.series().name());
+ }
+ else {
+ return HTTP_OUTCOME_UNKNOWN;
+ }
+ }
+ }
+
+}
diff --git a/spring-web/src/test/java/org/springframework/http/server/observation/OpenTelemetryServerRequestObservationConventionTests.java b/spring-web/src/test/java/org/springframework/http/server/observation/OpenTelemetryServerRequestObservationConventionTests.java
new file mode 100644
index 000000000000..03ee93e1e604
--- /dev/null
+++ b/spring-web/src/test/java/org/springframework/http/server/observation/OpenTelemetryServerRequestObservationConventionTests.java
@@ -0,0 +1,162 @@
+/*
+ * Copyright 2002-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.http.server.observation;
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.observation.Observation;
+import org.junit.jupiter.api.Test;
+
+import org.springframework.web.testfixture.servlet.MockHttpServletRequest;
+import org.springframework.web.testfixture.servlet.MockHttpServletResponse;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link OpenTelemetryServerRequestObservationConvention}.
+ * @author Brian Clozel
+ * @author Tommy Ludwig
+ */
+class OpenTelemetryServerRequestObservationConventionTests {
+
+ private final OpenTelemetryServerRequestObservationConvention convention = new OpenTelemetryServerRequestObservationConvention();
+
+ private final MockHttpServletRequest request = new MockHttpServletRequest("GET", "/test/resource");
+
+ private final MockHttpServletResponse response = new MockHttpServletResponse();
+
+ private final ServerRequestObservationContext context = new ServerRequestObservationContext(this.request, this.response);
+
+
+ @Test
+ void shouldHaveName() {
+ assertThat(convention.getName()).isEqualTo("http.server.request.duration");
+ }
+
+ @Test
+ void shouldHaveContextualName() {
+ assertThat(convention.getContextualName(this.context)).isEqualTo("GET");
+ }
+
+ @Test
+ void contextualNameShouldUsePathPatternWhenAvailable() {
+ this.context.setPathPattern("/test/{name}");
+ assertThat(convention.getContextualName(this.context)).isEqualTo("GET /test/{name}");
+ }
+
+ @Test
+ void supportsOnlyHttpRequestsObservationContext() {
+ assertThat(this.convention.supportsContext(this.context)).isTrue();
+ assertThat(this.convention.supportsContext(new Observation.Context())).isFalse();
+ }
+
+ @Test
+ void addsKeyValuesForExchange() {
+ this.request.setMethod("POST");
+ this.request.setRequestURI("/test/resource");
+
+ assertThat(this.convention.getLowCardinalityKeyValues(this.context)).hasSize(6)
+ .contains(KeyValue.of("http.request.method", "POST"), KeyValue.of("http.route", "UNKNOWN"), KeyValue.of("http.response.status_code", "200"),
+ KeyValue.of("error.type", "none"), KeyValue.of("outcome", "SUCCESS"), KeyValue.of("url.scheme", "http"));
+ assertThat(this.convention.getHighCardinalityKeyValues(this.context)).hasSize(2)
+ .contains(KeyValue.of("url.path", "/test/resource"), KeyValue.of("http.request.method_original", "POST"));
+ }
+
+ @Test
+ void addsKeyValuesForExchangeWithPathPattern() {
+ this.request.setRequestURI("/test/resource");
+ this.context.setPathPattern("/test/{name}");
+
+ assertThat(this.convention.getLowCardinalityKeyValues(this.context)).hasSize(6)
+ .contains(KeyValue.of("http.request.method", "GET"), KeyValue.of("http.route", "/test/{name}"), KeyValue.of("http.response.status_code", "200"),
+ KeyValue.of("error.type", "none"), KeyValue.of("outcome", "SUCCESS"), KeyValue.of("url.scheme", "http"));
+ assertThat(this.convention.getHighCardinalityKeyValues(this.context)).hasSize(2)
+ .contains(KeyValue.of("url.path", "/test/resource"), KeyValue.of("http.request.method_original", "GET"));
+ }
+
+ @Test
+ void addsKeyValuesForErrorExchange() {
+ this.request.setRequestURI("/test/resource");
+ this.context.setError(new IllegalArgumentException("custom error"));
+ this.response.setStatus(500);
+
+ assertThat(this.convention.getLowCardinalityKeyValues(this.context)).hasSize(6)
+ .contains(KeyValue.of("http.request.method", "GET"), KeyValue.of("http.route", "UNKNOWN"), KeyValue.of("http.response.status_code", "500"),
+ KeyValue.of("error.type", "java.lang.IllegalArgumentException"), KeyValue.of("outcome", "SERVER_ERROR"), KeyValue.of("url.scheme", "http"));
+ assertThat(this.convention.getHighCardinalityKeyValues(this.context)).hasSize(2)
+ .contains(KeyValue.of("url.path", "/test/resource"), KeyValue.of("http.request.method_original", "GET"));
+ }
+
+ @Test
+ void addsKeyValuesForRedirectExchange() {
+ this.request.setRequestURI("/test/redirect");
+ this.response.setStatus(302);
+ this.response.addHeader("Location", "https://example.org/other");
+
+ assertThat(this.convention.getLowCardinalityKeyValues(this.context)).hasSize(6)
+ .contains(KeyValue.of("http.request.method", "GET"), KeyValue.of("http.route", "REDIRECTION"), KeyValue.of("http.response.status_code", "302"),
+ KeyValue.of("error.type", "none"), KeyValue.of("outcome", "REDIRECTION"), KeyValue.of("url.scheme", "http"));
+ assertThat(this.convention.getHighCardinalityKeyValues(this.context)).hasSize(2)
+ .contains(KeyValue.of("url.path", "/test/redirect"), KeyValue.of("http.request.method_original", "GET"));
+ }
+
+ @Test
+ void addsKeyValuesForNotFoundExchange() {
+ this.request.setRequestURI("/test/notFound");
+ this.response.setStatus(404);
+
+ assertThat(this.convention.getLowCardinalityKeyValues(this.context)).hasSize(6)
+ .contains(KeyValue.of("http.request.method", "GET"), KeyValue.of("http.route", "NOT_FOUND"), KeyValue.of("http.response.status_code", "404"),
+ KeyValue.of("error.type", "none"), KeyValue.of("outcome", "CLIENT_ERROR"), KeyValue.of("url.scheme", "http"));
+ assertThat(this.convention.getHighCardinalityKeyValues(this.context)).hasSize(2)
+ .contains(KeyValue.of("url.path", "/test/notFound"), KeyValue.of("http.request.method_original", "GET"));
+ }
+
+ @Test
+ void addsKeyValuesForUnknownHttpMethodExchange() {
+ this.request.setMethod("SPRING");
+ this.request.setRequestURI("/test");
+ this.response.setStatus(404);
+
+ assertThat(this.convention.getContextualName(this.context)).isEqualTo("HTTP");
+ assertThat(this.convention.getLowCardinalityKeyValues(this.context)).hasSize(6)
+ .contains(KeyValue.of("http.request.method", "_OTHER"), KeyValue.of("http.route", "NOT_FOUND"), KeyValue.of("http.response.status_code", "404"),
+ KeyValue.of("error.type", "none"), KeyValue.of("outcome", "CLIENT_ERROR"), KeyValue.of("url.scheme", "http"));
+ assertThat(this.convention.getHighCardinalityKeyValues(this.context)).hasSize(2)
+ .contains(KeyValue.of("url.path", "/test"), KeyValue.of("http.request.method_original", "SPRING"));
+ }
+
+ @Test
+ void setsContextualNameWithPathPatternButInvalidMethod() {
+ this.request.setMethod("CUSTOM");
+ this.context.setPathPattern("/test/{name}");
+
+ assertThat(this.convention.getContextualName(this.context)).isEqualTo("HTTP /test/{name}");
+ }
+
+ @Test
+ void addsKeyValuesForInvalidStatusExchange() {
+ this.request.setRequestURI("/test/invalidStatus");
+ this.response.setStatus(0);
+
+ assertThat(this.convention.getLowCardinalityKeyValues(this.context)).hasSize(6)
+ .contains(KeyValue.of("http.request.method", "GET"), KeyValue.of("http.route", "UNKNOWN"), KeyValue.of("http.response.status_code", "0"),
+ KeyValue.of("error.type", "none"), KeyValue.of("outcome", "UNKNOWN"), KeyValue.of("url.scheme", "http"));
+ assertThat(this.convention.getHighCardinalityKeyValues(this.context)).hasSize(2)
+ .contains(KeyValue.of("url.path", "/test/invalidStatus"), KeyValue.of("http.request.method_original", "GET"));
+ }
+
+}