Document Observability support in reference docs

Closes gh-29524

framework-docs/src/main/java/org/springframework/docs/integration/observability/config/conventions/CustomServerRequestObservationConvention.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2002-2022 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.docs.integration.observability.config.conventions;
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.common.KeyValues;
+
+import org.springframework.http.server.observation.ServerHttpObservationDocumentation;
+import org.springframework.http.server.observation.ServerRequestObservationContext;
+import org.springframework.http.server.observation.ServerRequestObservationConvention;
+
+public class CustomServerRequestObservationConvention implements ServerRequestObservationConvention {
+
+	@Override
+	public String getName() {
+		// will be used as the metric name
+		return "http.server.requests";
+	}
+
+	@Override
+	public String getContextualName(ServerRequestObservationContext context) {
+		// will be used for the trace name
+		return "http " + context.getCarrier().getMethod().toLowerCase();
+	}
+
+	@Override
+	public KeyValues getLowCardinalityKeyValues(ServerRequestObservationContext context) {
+		return KeyValues.of(method(context), status(context), exception(context));
+	}
+
+
+	@Override
+	public KeyValues getHighCardinalityKeyValues(ServerRequestObservationContext context) {
+		return KeyValues.of(httpUrl(context));
+	}
+
+
+	protected KeyValue method(ServerRequestObservationContext context) {
+		// You should reuse as much as possible the corresponding ObservationDocumentation for key names
+		return KeyValue.of(ServerHttpObservationDocumentation.LowCardinalityKeyNames.METHOD, context.getCarrier().getMethod());
+	}
+
+	// @fold:on // status(), exception(), httpUrl()...
+	private KeyValue exception(ServerRequestObservationContext context) {
+		String exception = (context.getError() != null) ? context.getError().getClass().getSimpleName() : KeyValue.NONE_VALUE;
+		return KeyValue.of(ServerHttpObservationDocumentation.LowCardinalityKeyNames.EXCEPTION, exception);
+	}
+
+	private KeyValue status(ServerRequestObservationContext context) {
+		return KeyValue.of(ServerHttpObservationDocumentation.LowCardinalityKeyNames.STATUS, String.valueOf(context.getResponse().getStatus()));
+	}
+
+	private KeyValue httpUrl(ServerRequestObservationContext context) {
+		return KeyValue.of(ServerHttpObservationDocumentation.HighCardinalityKeyNames.HTTP_URL, context.getCarrier().getRequestURI());
+	}
+	// @fold:off
+
+}

framework-docs/src/main/java/org/springframework/docs/integration/observability/config/conventions/ExtendedServerRequestObservationConvention.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2002-2022 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.docs.integration.observability.config.conventions;
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.common.KeyValues;
+
+import org.springframework.http.server.observation.DefaultServerRequestObservationConvention;
+import org.springframework.http.server.observation.ServerRequestObservationContext;
+
+public class ExtendedServerRequestObservationConvention extends DefaultServerRequestObservationConvention {
+
+	@Override
+	public KeyValues getLowCardinalityKeyValues(ServerRequestObservationContext context) {
+		// here, we just want to have an additional KeyValue to the observation, keeping the default values
+		return super.getLowCardinalityKeyValues(context).and(custom(context));
+	}
+
+	protected KeyValue custom(ServerRequestObservationContext context) {
+		return KeyValue.of("custom.method", context.getCarrier().getMethod());
+	}
+
+}

framework-docs/src/main/java/org/springframework/docs/integration/observability/config/conventions/ServerRequestObservationFilter.java

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2002-2022 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.docs.integration.observability.config.conventions;
+
+
+import io.micrometer.common.KeyValue;
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationFilter;
+
+import org.springframework.http.server.observation.ServerRequestObservationContext;
+
+public class ServerRequestObservationFilter implements ObservationFilter {
+
+	@Override
+	public Observation.Context map(Observation.Context context) {
+		if (context instanceof ServerRequestObservationContext serverContext) {
+			context.setName("custom.observation.name");
+			context.addLowCardinalityKeyValue(KeyValue.of("project", "spring"));
+			String customAttribute = (String) serverContext.getCarrier().getAttribute("customAttribute");
+			context.addLowCardinalityKeyValue(KeyValue.of("custom.attribute", customAttribute));
+		}
+		return context;
+	}
+}