Polish "Add micrometer tracing documentation"

spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc

@@ -2,7 +2,7 @@
 == Tracing
 
 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.
+Micrometer Tracing hooks into Micrometer's `ObservationHandler`, which means a https://micrometer.io/docs/tracing#_glossary[span] is reported for every completed observation.
 
 TIP: To learn more about Micrometer Tracing capabilities, see its https://micrometer.io/docs/tracing[reference documentation].
 
@@ -11,25 +11,27 @@ TIP: To learn more about Micrometer Tracing capabilities, see its https://microm
 
 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]
+* https://github.com/openzipkin/brave[OpenZipkin Brave] 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.
+We're going to use the OpenTelemetry tracer with Zipkin as trace backend.
 
 To recap, our main application code looks like this:
 
 include::code:MyApplication[]
 
+NOTE: There's an added logger statement in the `home()` method, which will be important later.
+
 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.
+* `io.micrometer:micrometer-tracing-bridge-otel` - which is needed to bridge the Micrometer Observation API to OpenTelemetry.
+* `io.opentelemetry:opentelemetry-exporter-zipkin` - which is needed to report https://micrometer.io/docs/tracing#_glossary[traces] to Zipkin.
 
 Add the following application properties:
 
@@ -54,7 +56,7 @@ If you open a web browser to `http://localhost:8080`, you should see the followi
 	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.
+Behind the scenes, an observation has been created for the HTTP request, which in turn gets bridged to OpenTelemetry, 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.
@@ -69,20 +71,6 @@ As Micrometer Tracer supports multiple tracer implementations, there are multipl
 
 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
 
@@ -95,19 +83,19 @@ NOTE: If your project doesn't use Spring MVC or Spring WebFlux, the `io.zipkin.r
 * `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
+[[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.
 
-Spring Boot auto-configures instrumentation for the following technologies out of the box:
+NOTE: If your project doesn't use Spring MVC or Spring WebFlux, the `io.zipkin.reporter2:zipkin-sender-urlconnection` dependency is needed, too.
 
-* 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
+[[actuator.micrometer-tracing.tracer-implementations.brave-wavefront]]
+==== OpenZipkin Brave with Wavefront
 
-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.
+* `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.creating-spans]]
 === Creating custom spans
@@ -116,3 +104,10 @@ You can create your own spans by starting an observation.
 For this, inject `ObservationRegistry` into your component:
 
 include::code:CustomObservation[]
+
+This will create an observation named "some-operation" with the tag "some-tag=some-value".
+Completing an observation will create a metric and a span.
+
+NOTE: Low cardinality tags will be added to metrics and traces, while high cardinality tags will only be added to traces.
+
+TIP: If you want to create a span without creating a metric, you need to use the https://micrometer.io/docs/tracing#_using_micrometer_tracing_directly[lower-level `Tracer` API] from Micrometer.

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/gettingstarted/MyApplication.java

@@ -16,6 +16,9 @@
 
 package org.springframework.boot.docs.actuator.micrometertracing.gettingstarted;
 
+import org.apache.commons.logging.Log;
+import org.apache.commons.logging.LogFactory;
+
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.web.bind.annotation.RequestMapping;
@@ -25,8 +28,11 @@ import org.springframework.web.bind.annotation.RestController;
 @SpringBootApplication
 public class MyApplication {
 
+	private static final Log logger = LogFactory.getLog(MyApplication.class);
+
 	@RequestMapping("/")
 	String home() {
+		logger.info("home() has been called");
 		return "Hello World!";
 	}