Improve documentation for Spring Boot's OpenTelemetry support

Closes gh-47960

Author: mhalbritter

documentation/spring-boot-docs/build.gradle

@@ -151,6 +151,8 @@ dependencies {
 	implementation("io.micrometer:micrometer-registry-graphite")
 	implementation("io.micrometer:micrometer-registry-jmx")
 	implementation("io.opentelemetry.instrumentation:opentelemetry-logback-appender-1.0")
+	implementation("io.opentelemetry:opentelemetry-sdk-metrics")
+	implementation("io.opentelemetry:opentelemetry-exporter-otlp")
 	implementation("io.projectreactor.netty:reactor-netty-http")
 	implementation("jakarta.annotation:jakarta.annotation-api")
 	implementation("jakarta.jms:jakarta.jms-api")

documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/observability.adoc

@@ -82,6 +82,18 @@ The preceding example will prevent all observations whose name contains "denied"
 
 
 
+[[actuator.observability.annotations]]
+== Micrometer Observation Annotations support
+
+To enable scanning of observability annotations like javadoc:io.micrometer.observation.annotation.Observed[format=annotation], javadoc:io.micrometer.core.annotation.Timed[format=annotation], javadoc:io.micrometer.core.annotation.Counted[format=annotation], javadoc:io.micrometer.core.aop.MeterTag[format=annotation] and javadoc:io.micrometer.tracing.annotation.NewSpan[format=annotation], you need to set the configprop:management.observations.annotations.enabled[] property to `true`.
+This feature is supported by Micrometer directly.
+Please refer to the {url-micrometer-docs-concepts}/timers.html#_the_timed_annotation[Micrometer], {url-micrometer-docs-observation}/components.html#micrometer-observation-annotations[Micrometer Observation] and {url-micrometer-tracing-docs}/api.html#_aspect_oriented_programming[Micrometer Tracing] reference docs.
+
+NOTE: When you annotate methods or classes which are already instrumented (for example, xref:reference:actuator/metrics.adoc#actuator.metrics.supported.spring-data-repository[Spring Data repositories] or xref:reference:actuator/metrics.adoc#actuator.metrics.supported.spring-mvc[Spring MVC controllers]), you will get duplicate observations.
+In that case you can either disable the automatic instrumentation using xref:reference:actuator/observability.adoc#actuator.observability.preventing-observations[properties] or an javadoc:io.micrometer.observation.ObservationPredicate[] and rely on your annotations, or you can remove your annotations.
+
+
+
 [[actuator.observability.opentelemetry]]
 == OpenTelemetry Support
 
@@ -101,24 +113,72 @@ Auto-configured attributes will be merged with attributes from the `OTEL_RESOURC
 
 If you have defined your own javadoc:io.opentelemetry.sdk.resources.Resource[] bean, this will no longer be the case.
 
-NOTE: Spring Boot does not provide auto-configuration for OpenTelemetry metrics or logging.
-OpenTelemetry tracing is only auto-configured when used together with xref:actuator/tracing.adoc[Micrometer Tracing].
+NOTE: Spring Boot does not provide automatic exporting of OpenTelemetry metrics or logs.
+Exporting OpenTelemetry traces is only auto-configured when used together with xref:actuator/tracing.adoc[Micrometer Tracing].
+
+
+
+[[actuator.observability.opentelemetry.environment-variables]]
+=== Environment variables
+
+Spring Boot supports the following environment variables to configure the OpenTelemetry resource:
+
+* https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration[`OTEL_RESOURCE_ATTRIBUTES`]
+* https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#general-sdk-configuration[`OTEL_SERVICE_NAME`]
 
 NOTE: The `OTEL_RESOURCE_ATTRIBUTES` environment variable consists of a list of key-value pairs.
 For example: `key1=value1,key2=value2,key3=spring%20boot`.
 All attribute values are treated as strings, and any characters outside the baggage-octet range must be **percent-encoded**.
 
+Micrometer also supports the following environment variables to configure the metrics export over OTLP:
 
-The next sections will provide more details about logging, metrics and traces.
+* https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint[`OTEL_EXPORTER_OTLP_ENDPOINT`]
+* https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_metrics_endpoint[`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`]
+* https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_headers[`OTEL_EXPORTER_OTLP_HEADERS`]
+* https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_metrics_headers[`OTEL_EXPORTER_OTLP_METRICS_HEADERS`]
 
+Logging and tracing use the OpenTelemetry SDK directly, so all environment variables https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/[supported by OpenTelemetry] also work.
 
+[[actuator.observability.opentelemetry.logging]]
+=== Logging
 
-[[actuator.observability.annotations]]
-== Micrometer Observation Annotations support
+The javadoc:org.springframework.boot.opentelemetry.autoconfigure.logging.OpenTelemetryLoggingAutoConfiguration[] configures OpenTelemetry's javadoc:io.opentelemetry.sdk.logs.SdkLoggerProvider[].
+Exporting logs via OTLP is supported through the javadoc:org.springframework.boot.opentelemetry.autoconfigure.logging.otlp.OtlpLoggingAutoConfiguration[], which enables OTLP log exporting over HTTP or gRPC.
 
-To enable scanning of observability annotations like javadoc:io.micrometer.observation.annotation.Observed[format=annotation], javadoc:io.micrometer.core.annotation.Timed[format=annotation], javadoc:io.micrometer.core.annotation.Counted[format=annotation], javadoc:io.micrometer.core.aop.MeterTag[format=annotation] and javadoc:io.micrometer.tracing.annotation.NewSpan[format=annotation], you need to set the configprop:management.observations.annotations.enabled[] property to `true`.
-This feature is supported by Micrometer directly.
-Please refer to the {url-micrometer-docs-concepts}/timers.html#_the_timed_annotation[Micrometer], {url-micrometer-docs-observation}/components.html#micrometer-observation-annotations[Micrometer Observation] and {url-micrometer-tracing-docs}/api.html#_aspect_oriented_programming[Micrometer Tracing] reference docs.
+However, while there is a `SdkLoggerProvider` bean, Spring Boot doesn't support bridging logs to this bean out of the box.
+This can be done with 3rd-party log bridges, as described in the xref:reference:actuator/loggers.adoc#actuator.loggers.opentelemetry[Logging with OpenTelemetry] section.
 
-NOTE: When you annotate methods or classes which are already instrumented (for example, xref:reference:actuator/metrics.adoc#actuator.metrics.supported.spring-data-repository[Spring Data repositories] or xref:reference:actuator/metrics.adoc#actuator.metrics.supported.spring-mvc[Spring MVC controllers]), you will get duplicate observations.
-In that case you can either disable the automatic instrumentation using xref:reference:actuator/observability.adoc#actuator.observability.preventing-observations[properties] or an javadoc:io.micrometer.observation.ObservationPredicate[] and rely on your annotations, or you can remove your annotations.
+
+
+[[actuator.observability.opentelemetry.metrics]]
+=== Metrics
+
+The choice of metrics in the Spring portfolio is Micrometer, which means that metrics are not collected and exported through the OpenTelemetry's javadoc:io.opentelemetry.sdk.metrics.SdkMeterProvider[].
+Spring Boot doesn't provide a `SdkMeterProvider` bean.
+
+
+However, Micrometer metrics can be exported via OTLP to any OpenTelemetry capable backend using the javadoc:io.micrometer.registry.otlp.OtlpMeterRegistry[], as described in the xref:reference:actuator/metrics.adoc#actuator.metrics.export.otlp[Metrics with OTLP] section.
+
+NOTE: Micrometer's OTLP registry doesn't use the `Resource` bean, but setting `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_SERVICE_NAME` or configprop:management.opentelemetry.resource-attributes[] works.
+
+[[actuator.observability.opentelemetry.metrics.api-and-sdk]]
+==== Metrics via the OpenTelemetry API and SDK
+
+If you or a dependency you include make use of OpenTelemetry's javadoc:io.opentelemetry.api.metrics.MeterProvider[], those metrics are not exported.
+
+We strongly recommend that you report your metrics with Micrometer.
+If a dependency you include uses OpenTelemetry's `MeterProvider`, you can include this configuration in your application to configure a `MeterProvider` bean, which you then have to wire into your dependency:
+
+include-code::OpenTelemetryMetricsConfiguration[]
+
+This configuration also enables metrics export via OTLP over HTTP.
+
+
+
+[[actuator.observability.opentelemetry.tracing]]
+=== Tracing
+
+If Micrometer tracing is used, the javadoc:org.springframework.boot.micrometer.tracing.opentelemetry.autoconfigure.OpenTelemetryTracingAutoConfiguration[] configures OpenTelemetry's javadoc:io.opentelemetry.sdk.trace.SdkTracerProvider[].
+Exporting traces through OTLP is enabled by the javadoc:org.springframework.boot.micrometer.tracing.opentelemetry.autoconfigure.otlp.OtlpTracingAutoConfiguration[], which supports exporting traces with OTLP over HTTP or gRPC.
+
+We strongly recommend using the Micrometer Observation or Tracing API instead of using the OpenTelemetry API directly.

documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/observability/opentelemetry/metrics/apiandsdk/OpenTelemetryMetricsConfiguration.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright 2012-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.boot.docs.actuator.observability.opentelemetry.metrics.apiandsdk;
+
+import java.time.Duration;
+
+import io.opentelemetry.exporter.otlp.http.metrics.OtlpHttpMetricExporter;
+import io.opentelemetry.sdk.metrics.SdkMeterProvider;
+import io.opentelemetry.sdk.metrics.export.MetricExporter;
+import io.opentelemetry.sdk.metrics.export.MetricReader;
+import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader;
+import io.opentelemetry.sdk.resources.Resource;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration(proxyBeanMethods = false)
+class OpenTelemetryMetricsConfiguration {
+
+	@Bean
+	OtlpHttpMetricExporter metricExporter() {
+		String endpoint = "http://localhost:4318/v1/metrics";
+		return OtlpHttpMetricExporter.builder().setEndpoint(endpoint).build();
+	}
+
+	@Bean
+	PeriodicMetricReader metricReader(MetricExporter exporter) {
+		Duration interval = Duration.ofMinutes(1);
+		return PeriodicMetricReader.builder(exporter).setInterval(interval).build();
+	}
+
+	@Bean
+	SdkMeterProvider meterProvider(Resource resource, MetricReader metricReader) {
+		return SdkMeterProvider.builder().registerMetricReader(metricReader).setResource(resource).build();
+	}
+
+}

platform/spring-boot-dependencies/build.gradle

@@ -1548,6 +1548,7 @@ bom {
 			javadoc("micrometer-core", version -> "https://javadoc.io/doc/io.micrometer/micrometer-core/%s".formatted(version), "io.micrometer.core")
 			javadoc("micrometer-observation", version -> "https://javadoc.io/doc/io.micrometer/micrometer-observation/%s".formatted(version), "io.micrometer.observation")
 			javadoc("micrometer-registry-graphite", version -> "https://javadoc.io/doc/io.micrometer/micrometer-registry-graphite/%s".formatted(version), "io.micrometer.graphite")
+			javadoc("micrometer-registry-otlp", version -> "https://javadoc.io/doc/io.micrometer/micrometer-registry-otlp/%s".formatted(version), "io.micrometer.registry.otlp")
 			javadoc("micrometer-registry-jmx", version -> "https://javadoc.io/doc/io.micrometer/micrometer-registry-jmx/%s".formatted(version), "io.micrometer.jmx")
 			javadoc("micrometer-new-relic", version -> "https://javadoc.io/doc/io.micrometer/micrometer-registry-new-relic/%s".formatted(version), "io.micrometer.newrelic")
 			docs(version -> "https://docs.micrometer.io/micrometer/reference/%s.%s"