From 90a39b8f84a928fc2bc155d3d4bcd6fffe8b9b70 Mon Sep 17 00:00:00 2001 From: Chris Bono Date: Wed, 12 Oct 2022 17:09:40 -0500 Subject: [PATCH] Add Micrometer Tracing to sample apps (#160) Also documents how to configure Micrometer Observations. See #147 --- .../src/main/asciidoc/pulsar.adoc | 74 +++++++++++++++++-- spring-pulsar-sample-apps/build.gradle | 6 ++ .../src/main/resources/application.yml | 7 ++ 3 files changed, 82 insertions(+), 5 deletions(-) diff --git a/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc b/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc index abf9cb1c..e578b355 100644 --- a/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc +++ b/spring-pulsar-docs/src/main/asciidoc/pulsar.adoc @@ -1338,11 +1338,9 @@ Headers can also be extracted in the same manner when receiving payload as `List === Observability [[observation]] -==== Micrometer Observation +==== Micrometer Observations The `PulsarTemplate` and `PulsarListener` are instrumented with the Micrometer observations API. -When enabled, send and receive operations are traced and timed. - -To enable, set `observationEnabled` on each component. +When a Micrometer `ObservationRegistry` bean is provided, send and receive operations are traced and timed. ===== Custom tags The default implementation adds the `bean.name` tag for template observations and `listener.id` tag for listener observations. @@ -1356,7 +1354,73 @@ include::observation/_spans.adoc[leveloffset=+2] Refer to https://micrometer.io/docs/tracing[Micrometer Tracing] for more information. -==== Appendix +===== Manual Configuration Without Spring Boot +If you are not using Spring Boot then you will need to configure and provide an `ObservationRegistry` as well as Micrometer Tracing. Refer to https://micrometer.io/docs/tracing[Micrometer Tracing] for more information. + +===== Auto-Configuration With Spring Boot +If you are using Spring Boot, the Spring Boot Actuator auto-configures an instance of `ObservationRegistry` for you. +If `micrometer-core` is on the classpath every stopped Observation leads to a timer. + +Spring Boot also auto-configures Micrometer Tracing for you. This includes support for Brave OpenTelemetry, Zipkin and Wavefront. When using the Micrometer Observation API, finishing observations will lead to spans reported to Zipkin or Wavefront. Tracing can be controlled with properties under `management.tracing`. Zipkin can be configured with `management.zipkin.tracing` while Wavefront uses `management.wavefront`. + +====== Example Configuration +The following illustrates the steps to configure your Spring Boot app to use Zipkin with Brave. + +**Step 1:** Add the required dependencies to your application [small]#(Maven or Gradle, respectively)#: + +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + + org.springframework.boot + spring-boot-starter-actuator + + + io.micrometer + micrometer-tracing-bridge-brave + + + io.zipkin.reporter2 + zipkin-reporter-brave + + + io.zipkin.reporter2 + zipkin-sender-urlconnection + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +dependencies { + implementation 'org.springframework.boot:spring-boot-starter-actuator' + implementation 'io.micrometer:micrometer-tracing-bridge-brave' + implementation 'io.zipkin.reporter2:zipkin-reporter-brave' + implementation 'io.zipkin.reporter2:zipkin-sender-urlconnection' +} +---- +NOTE: The `'io.zipkin.reporter2:zipkin-sender-urlconnection'` dependency is only needed if your application does not have a configured WebClient or RestTemplate. + +**Step 2:** Add the required properties to your application: + +[source,yaml,indent=0,subs="verbatim"] +---- +management: + tracing.enabled: true + zipkin: + tracing.endpoint: "http://localhost:9411/api/v2/spans" +---- +The `tracing.endpoint` above expects Zipkin is running locally as described https://zipkin.io/pages/quickstart.html[here]. + +At this point, your application should be recording traces when you send and receive Pulsar messages. You should be able to view them in the Zipkin UI [small]#(when running locally http://localhost:9411)#. + +TIP: The above configuration can also be seen on the link:{github}/blob/main/spring-pulsar-sample-apps/README.adoc[Spring Pulsar Sample Apps]. + +The steps would be very similar to configure in any of the other supporting Tracing environments. + +=== Appendix The reference documentation has the following appendices: [horizontal] diff --git a/spring-pulsar-sample-apps/build.gradle b/spring-pulsar-sample-apps/build.gradle index d7d1d662..78b61bfa 100644 --- a/spring-pulsar-sample-apps/build.gradle +++ b/spring-pulsar-sample-apps/build.gradle @@ -8,6 +8,12 @@ description = 'Spring Pulsar Sample Applications' dependencies { api project(':spring-pulsar-spring-boot-starter') implementation 'com.google.code.findbugs:jsr305' + + // observability + implementation 'org.springframework.boot:spring-boot-starter-actuator' + implementation 'io.micrometer:micrometer-tracing-bridge-brave' + implementation 'io.zipkin.reporter2:zipkin-reporter-brave' + implementation 'io.zipkin.reporter2:zipkin-sender-urlconnection' } springBoot { diff --git a/spring-pulsar-sample-apps/src/main/resources/application.yml b/spring-pulsar-sample-apps/src/main/resources/application.yml index 45c3b356..489039f3 100644 --- a/spring-pulsar-sample-apps/src/main/resources/application.yml +++ b/spring-pulsar-sample-apps/src/main/resources/application.yml @@ -1,3 +1,10 @@ logging: level: org.apache.pulsar: error + +management: + tracing: + enabled: false + zipkin: + tracing: + endpoint: "http://localhost:9411/api/v2/spans"