Add Micrometer Tracing to sample apps (#160)

Also documents how to configure Micrometer Observations.

See #147

Author: onobc

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
+----
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-actuator</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>io.micrometer</groupId>
+        <artifactId>micrometer-tracing-bridge-brave</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>io.zipkin.reporter2</groupId>
+        <artifactId>zipkin-reporter-brave</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>io.zipkin.reporter2</groupId>
+        <artifactId>zipkin-sender-urlconnection</artifactId>
+    </dependency>
+</dependencies>
+----
+
+[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]

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 {

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"