From ff6d9aa88182aa31b6802c191de881c3bfe2dc63 Mon Sep 17 00:00:00 2001 From: Moritz Halbritter Date: Fri, 21 Oct 2022 13:16:11 +0200 Subject: [PATCH] Polish "Add micrometer tracing documentation" --- .../src/docs/asciidoc/actuator/tracing.adoc | 55 +++++++++---------- .../gettingstarted/MyApplication.java | 6 ++ 2 files changed, 31 insertions(+), 30 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc index 529395557cc..a5ca6822485 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc +++ b/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 "`<>`" 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. diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/gettingstarted/MyApplication.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/gettingstarted/MyApplication.java index feef3257a62..52397ff2013 100644 --- a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/gettingstarted/MyApplication.java +++ b/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!"; }