Add micrometer tracing documentation

Closes gh-30658
2026-09-24 02:09:05 +00:00 · 2022-10-21 10:04:40 +02:00
parent 7ddd1e2bed
commit e999513838
5 changed files with 211 additions and 13 deletions
@@ -23,9 +23,11 @@ include::actuator/loggers.adoc[]

 include::actuator/metrics.adoc[]

+include::actuator/tracing.adoc[]
+
 include::actuator/auditing.adoc[]

-include::actuator/tracing.adoc[]
+include::actuator/http-tracing.adoc[]

 include::actuator/process-monitoring.adoc[]

@@ -0,0 +1,16 @@
+[[actuator.tracing]]
+== HTTP Tracing
+
+You can enable HTTP Tracing by providing a bean of type `HttpTraceRepository` in your application's configuration.
+For convenience, Spring Boot offers `InMemoryHttpTraceRepository`, which stores traces for the last 100 (the default) request-response exchanges.
+`InMemoryHttpTraceRepository` is limited compared to other tracing solutions, and we recommend using it only for development environments.
+For production environments, we recommend using a production-ready tracing or observability solution, such as Zipkin or Spring Cloud Sleuth.
+Alternatively, you can create your own `HttpTraceRepository`.
+
+You can use the `httptrace` endpoint to obtain information about the request-response exchanges that are stored in the `HttpTraceRepository`.
+
+[[actuator.tracing.custom]]
+=== Custom HTTP tracing
+
+To customize the items that are included in each trace, use the configprop:management.trace.http.include[] configuration property.
+For advanced customization, consider registering your own `HttpExchangeTracer` implementation.
@@ -1,16 +1,118 @@
-[[actuator.tracing]]
-== HTTP Tracing
-You can enable HTTP Tracing by providing a bean of type `HttpTraceRepository` in your application's configuration.
-For convenience, Spring Boot offers `InMemoryHttpTraceRepository`, which stores traces for the last 100 (the default) request-response exchanges.
-`InMemoryHttpTraceRepository` is limited compared to other tracing solutions, and we recommend using it only for development environments.
-For production environments, we recommend using a production-ready tracing or observability solution, such as Zipkin or Spring Cloud Sleuth.
-Alternatively, you can create your own `HttpTraceRepository`.
+[[actuator.micrometer-tracing]]
+== Tracing

-You can use the `httptrace` endpoint to obtain information about the request-response exchanges that are stored in the `HttpTraceRepository`.
+Spring Boot Actuator provides dependency management and auto-configuration for https://micrometer.io/docs/tracing[Micrometer Tracing], a facade for popular tracer libraries.
+Micrometer Tracing hooks into Micrometer's `ObservationHandler`, which means a span is created for every completed observation.

+TIP: To learn more about Micrometer Tracing capabilities, see its https://micrometer.io/docs/tracing[reference documentation].

+[[actuator.micrometer-tracing.tracers]]
+=== Supported tracers

-[[actuator.tracing.custom]]
-=== Custom HTTP tracing
-To customize the items that are included in each trace, use the configprop:management.trace.http.include[] configuration property.
-For advanced customization, consider registering your own `HttpExchangeTracer` implementation.
+Spring Boot ships auto-configuration for the following tracers:
+
+* https://github.com/openzipkin/brave[OpenZipkin Brave] with https://zipkin.io/[Zipkin] or https://docs.wavefront.com/[Wavefront]
+* https://opentelemetry.io/[OpenTelemetry] with https://zipkin.io/[Zipkin] or https://docs.wavefront.com/[Wavefront]
+
+[[actuator.micrometer-tracing.getting-started]]
+=== Getting Started
+
+We need an example application that we can use to getting started with tracing.
+For our purposes, the simple "`Hello World!`" web application that's covered in the "`<<getting-started#getting-started.first-application>>`" section will suffice.
+We're going to use the OpenZipkin Brave tracer with Zipkin as trace backend.
+
+To recap, our main application code looks like this:
+
+include::code:MyApplication[]
+
+Now we have to add the following dependencies:
+
+* `org.springframework.boot:spring-boot-starter-actuator`
+* `io.micrometer:micrometer-tracing-bridge-brave` - which is needed to bridge the Micrometer Observation API to Brave.
+* `io.zipkin.reporter2:zipkin-reporter-brave` - which is needed to report traces to Zipkin.
+
+Add the following application properties:
+
+[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
+----
+	management.tracing.sampling.probability: 1.0
+----
+
+By default, Spring Boot samples only 10% of requests to prevent overwhelming the trace backend.
+This property switches it to 100% so that every request is sent to the trace backend.
+
+To collect and visualize the traces, we need a running trace backend.
+We use Zipkin as our trace backend here.
+The https://zipkin.io/pages/quickstart[Zipkin Quickstart guide] provides instructions how to start Zipkin locally.
+
+After Zipkin is running, you can start your application.
+
+If you open a web browser to `http://localhost:8080`, you should see the following output:
+
+[indent=0]
+----
+	Hello World!
+----
+
+Behind the scenes, an observation has been created for the HTTP request, which in turn gets bridged to Brave, which reports a new trace to Zipkin.
+
+Now open the Zipkin UI at `http://localhost:9411` and press the "Run Query" button to list all collected traces.
+You should see one trace.
+Press the "Show" button to see the details of that trace.
+
+TIP: You can include the current trace and span id in the logs by setting the `logging.pattern.level` property to `%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]`
+
+[[actuator.micrometer-tracing.tracer-implementations]]
+=== Tracer implementations
+
+As Micrometer Tracer supports multiple tracer implementations, there are multiple dependency combinations possible with Spring Boot.
+
+All tracer implementations need the `org.springframework.boot:spring-boot-starter-actuator` dependency.
+
+[[actuator.micrometer-tracing.tracer-implementations.brave-zipkin]]
+==== OpenZipkin Brave with Zipkin
+
+* `io.micrometer:micrometer-tracing-bridge-brave` - which is needed to bridge the Micrometer Observation API to Brave.
+* `io.zipkin.reporter2:zipkin-reporter-brave` - which is needed to report traces to Zipkin.
+
+NOTE: If your project doesn't use Spring MVC or Spring WebFlux, the `io.zipkin.reporter2:zipkin-sender-urlconnection` dependency is needed, too.
+
+[[actuator.micrometer-tracing.tracer-implementations.brave-wavefront]]
+==== OpenZipkin Brave with Wavefront
+
+* `io.micrometer:micrometer-tracing-bridge-brave` - which is needed to bridge the Micrometer Observation API to Brave.
+* `io.micrometer:micrometer-tracing-reporter-wavefront` - which is needed to report traces to Wavefront.
+
+[[actuator.micrometer-tracing.tracer-implementations.otel-zipkin]]
+==== OpenTelemetry with Zipkin
+
+* `io.micrometer:micrometer-tracing-bridge-otel` - which is needed to bride the Micrometer Observation API to OpenTelemetry.
+* `io.opentelemetry:opentelemetry-exporter-zipkin` - which is needed to report traces to Zipkin.
+
+[[actuator.micrometer-tracing.tracer-implementations.otel-wavefront]]
+==== OpenTelemetry with Wavefront
+
+* `io.micrometer:micrometer-tracing-bridge-otel` - which is needed to bride the Micrometer Observation API to OpenTelemetry.
+* `io.micrometer:micrometer-tracing-reporter-wavefront` - which is needed to report traces to Wavefront.
+
+[[actuator.micrometer-tracing.instrumentations]]
+=== Instrumentations
+
+Spring Boot auto-configures instrumentation for the following technologies out of the box:
+
+* Incoming HTTP calls via Spring MVC.
+* Incoming HTTP calls via Spring WebFlux.
+* Outgoing HTTP calls via `RestTemplate` constructed via `RestTemplateBuilder`.
+* Outgoing HTTP calls via `WebClient` constructed via `WebClient.Builder`.
+* Incoming GraphQL calls
+
+NOTE: Other Spring portfolio projects are using the Micrometer Observation, too.
+Every use of an observation gets translated into a span, so you may see even more spans reported in your project.
+
+[[actuator.micrometer-tracing.creating-spans]]
+=== Creating custom spans
+
+You can create your own spans by starting an observation.
+For this, inject `ObservationRegistry` into your component:
+
+include::code:CustomObservation[]
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2012-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.boot.docs.actuator.micrometertracing.creatingspans;
+
+import io.micrometer.observation.Observation;
+import io.micrometer.observation.ObservationRegistry;
+
+import org.springframework.stereotype.Component;
+
+@Component
+class CustomObservation {
+
+	private final ObservationRegistry observationRegistry;
+
+	CustomObservation(ObservationRegistry observationRegistry) {
+		this.observationRegistry = observationRegistry;
+	}
+
+	void someOperation() {
+		Observation observation = Observation.createNotStarted("some-operation", this.observationRegistry);
+		observation.lowCardinalityKeyValue("some-tag", "some-value");
+		observation.observe(() -> {
+			// Business logic ...
+		});
+	}
+
+}
@@ -0,0 +1,37 @@
+/*
+ * Copyright 2012-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.boot.docs.actuator.micrometertracing.gettingstarted;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@SpringBootApplication
+public class MyApplication {
+
+	@RequestMapping("/")
+	String home() {
+		return "Hello World!";
+	}
+
+	public static void main(String[] args) {
+		SpringApplication.run(MyApplication.class, args);
+	}
+
+}