Merge #2558 into 2.0.0-M3

build.gradle

@@ -91,6 +91,10 @@ ext {
 	// Used only in tests
 	contextPropagationVersion = '1.0.0-RC1' //optional baseline
 
+	// Used only in examples
+	braveVersion = '5.14.1'
+	zipkinSenderVersion = '2.16.3'
+
 	jsr305Version = '3.0.2'
 
 	// Logging

docs/asciidoc/http-client.adoc

@@ -432,6 +432,42 @@ include::{examplesdir}/metrics/custom/Application.java[lines=18..35]
 <1> Enables HTTP client metrics and provides {javadoc}/reactor/netty5/http/client/HttpClientMetricsRecorder.html[`HttpClientMetricsRecorder`] implementation.
 ====
 
+== Tracing
+The HTTP client supports built-in integration with https://micrometer.io/docs/tracing[`Micrometer Tracing`].
+
+The following table provides information for the HTTP client spans:
+
+[width="100%",options="header"]
+|=======
+| contextual name | description
+| HTTP <HTTP METHOD> | Information and total time for the request.
+See <<observability-spans-http-client-response-span>>.
+| hostname resolution | Information and time spent for resolving the address.
+See <<observability-spans-hostname-resolution-span>>.
+| connect | Information and time spent for connecting to the remote address.
+See <<observability-spans-connect-span>>.
+| tls handshake | Information and time spent for TLS handshake.
+See <<observability-spans-tls-handshake-span>>.
+|=======
+
+The following example enables that integration. This concrete example uses `Brave` and reports the information to `Zipkin`.
+See the https://micrometer.io/docs/tracing#_micrometer_tracing_opentelemetry_setup[`Micrometer Tracing`] documentation for `OpenTelemetry` setup.
+
+====
+[source,java,indent=0]
+.{examplesdir}/tracing/Application.java
+----
+include::{examplesdir}/tracing/Application.java[lines=18..90]
+----
+<1> Initializes Brave, Zipkin, and the Observation registry.
+<2> Templated URIs are used as an URI tag value when possible.
+<3> Enables the built-in integration with Micrometer.
+====
+
+The result in `Zipkin` looks like:
+
+image::images/http-client-tracing.png[]
+
 == Unix Domain Sockets
 The `HTTP` client supports Unix Domain Sockets (UDS) for all transports (native and NIO).
 

docs/asciidoc/http-server.adoc

@@ -614,6 +614,36 @@ include::{examplesdir}/metrics/custom/Application.java[lines=18..41]
 <1> Enables HTTP server metrics and provides {javadoc}/reactor/netty5/http/server/HttpServerMetricsRecorder.html[`HttpServerMetricsRecorder`] implementation.
 ====
 
+== Tracing
+The HTTP server supports built-in integration with https://micrometer.io/docs/tracing[`Micrometer Tracing`].
+
+The following table provides information for the HTTP server spans:
+
+[width="100%",options="header"]
+|=======
+| contextual name | description
+| <HTTP METHOD>_<URI> | Information and total time for the request.
+See <<observability-spans-http-server-response-span>>.
+|=======
+
+The following example enables that integration. This concrete example uses `Brave` and reports the information to `Zipkin`.
+See the https://micrometer.io/docs/tracing#_micrometer_tracing_opentelemetry_setup[`Micrometer Tracing`] documentation for `OpenTelemetry` setup.
+
+====
+[source,java,indent=0]
+.{examplesdir}/tracing/Application.java
+----
+include::{examplesdir}/tracing/Application.java[lines=18..91]
+----
+<1> Initializes Brave, Zipkin, and the Observation registry.
+<2> Templated URIs are used as an URI tag value when possible.
+<3> Enables the built-in integration with Micrometer.
+====
+
+The result in `Zipkin` looks like:
+
+image::images/http-server-tracing.png[]
+
 == Unix Domain Sockets
 The `HTTP` server supports Unix Domain Sockets (UDS) for all transports (native and NIO).
 

docs/asciidoc/tcp-client.adoc

@@ -322,6 +322,39 @@ include::{examplesdir}/metrics/custom/Application.java[lines=18..37]
 <1> Enables TCP client metrics and provides {javadoc}/reactor/netty5/channel/ChannelMetricsRecorder.html[`ChannelMetricsRecorder`] implementation.
 ====
 
+== Tracing
+The TCP client supports built-in integration with https://micrometer.io/docs/tracing[`Micrometer Tracing`].
+
+The following table provides information for the TCP client spans:
+
+[width="100%",options="header"]
+|=======
+| contextual name | description
+| hostname resolution | Information and time spent for resolving the address.
+See <<observability-spans-hostname-resolution-span>>.
+| connect | Information and time spent for connecting to the remote address.
+See <<observability-spans-connect-span>>.
+| tls handshake | Information and time spent for TLS handshake.
+See <<observability-spans-tls-handshake-span>>.
+|=======
+
+The following example enables that integration. This concrete example uses `Brave` and reports the information to `Zipkin`.
+See the https://micrometer.io/docs/tracing#_micrometer_tracing_opentelemetry_setup[`Micrometer Tracing`] documentation for `OpenTelemetry` setup.
+
+====
+[source,java,indent=0]
+.{examplesdir}/tracing/Application.java
+----
+include::{examplesdir}/tracing/Application.java[lines=18..81]
+----
+<1> Initializes Brave, Zipkin, and the Observation registry.
+<2> Enables the built-in integration with Micrometer.
+====
+
+The result in `Zipkin` looks like:
+
+image::images/tcp-client-tracing.png[]
+
 == Unix Domain Sockets
 The `TCP` client supports Unix Domain Sockets (UDS) for all transports (native and NIO).
 

docs/asciidoc/tcp-server.adoc

@@ -294,6 +294,35 @@ include::{examplesdir}/metrics/custom/Application.java[lines=18..35]
 <1> Enables TCP server metrics and provides {javadoc}/reactor/netty5/channel/ChannelMetricsRecorder.html[`ChannelMetricsRecorder`] implementation.
 ====
 
+== Tracing
+The TCP server supports built-in integration with https://micrometer.io/docs/tracing[`Micrometer Tracing`].
+
+The following table provides information for the TCP server spans:
+
+[width="100%",options="header"]
+|=======
+| contextual name | description
+| tls handshake | Information and time spent for TLS handshake.
+See <<observability-spans-tls-handshake-span>>.
+|=======
+
+The following example enables that integration. This concrete example uses `Brave` and reports the information to `Zipkin`.
+See the https://micrometer.io/docs/tracing#_micrometer_tracing_opentelemetry_setup[`Micrometer Tracing`] documentation for `OpenTelemetry` setup.
+
+====
+[source,java,indent=0]
+.{examplesdir}/tracing/Application.java
+----
+include::{examplesdir}/tracing/Application.java[lines=18..81]
+----
+<1> Initializes Brave, Zipkin, and the Observation registry.
+<2> Enables the built-in integration with Micrometer.
+====
+
+The result in `Zipkin` looks like:
+
+image::images/tcp-server-tracing.png[]
+
 == Unix Domain Sockets
 The `TCP` server supports Unix Domain Sockets (UDS) for all transports (native and NIO).
 

reactor-netty5-examples/build.gradle

@@ -19,6 +19,10 @@ dependencies {
 	api "com.fasterxml.jackson.core:jackson-databind:$jacksonDatabindVersion"
 
 	api "io.micrometer:micrometer-core:$micrometerVersion"
+	api "io.micrometer:micrometer-tracing:$micrometerTracingVersion"
+	api "io.micrometer:micrometer-tracing-bridge-brave:$micrometerTracingVersion"
+	api "io.zipkin.brave:brave:$braveVersion"
+	api "io.zipkin.reporter2:zipkin-sender-urlconnection:$zipkinSenderVersion"
 
 	api "io.netty:netty5-transport-native-epoll:$nettyVersion:linux-x86_64"
 

reactor-netty5-examples/src/main/java/reactor/netty5/examples/documentation/http/client/tracing/Application.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ *
+ * 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 reactor.netty5.examples.documentation.http.client.tracing;
+
+import brave.Tracing;
+import brave.handler.SpanHandler;
+import brave.propagation.StrictCurrentTraceContext;
+import brave.sampler.Sampler;
+import io.micrometer.tracing.CurrentTraceContext;
+import io.micrometer.tracing.Tracer;
+import io.micrometer.tracing.brave.bridge.BraveBaggageManager;
+import io.micrometer.tracing.brave.bridge.BraveCurrentTraceContext;
+import io.micrometer.tracing.brave.bridge.BravePropagator;
+import io.micrometer.tracing.brave.bridge.BraveTracer;
+import io.micrometer.tracing.propagation.Propagator;
+import reactor.netty5.http.client.HttpClient;
+import reactor.netty5.http.observability.ReactorNettyPropagatingSenderTracingObservationHandler;
+import reactor.netty5.observability.ReactorNettyTracingObservationHandler;
+import zipkin2.reporter.AsyncReporter;
+import zipkin2.reporter.brave.ZipkinSpanHandler;
+import zipkin2.reporter.urlconnection.URLConnectionSender;
+
+import static reactor.netty5.Metrics.OBSERVATION_REGISTRY;
+
+public class Application {
+
+	public static void main(String[] args) {
+		init(); //<1>
+
+		HttpClient client =
+				HttpClient.create()
+				          .metrics(true, s -> {
+				              if (s.startsWith("/stream/")) { //<2>
+				                  return "/stream/{n}";
+				              }
+				              return s;
+				          }); //<3>
+
+		client.get()
+		      .uri("https://httpbin.org/stream/3")
+		      .responseContent()
+		      .blockLast();
+	}
+
+	/**
+	 * This setup is based on
+	 * <a href="https://micrometer.io/docs/tracing#_micrometer_tracing_brave_setup">Micrometer Tracing Brave Setup</a>
+	 */
+	static void init() {
+		SpanHandler spanHandler = ZipkinSpanHandler
+				.create(AsyncReporter.create(URLConnectionSender.create("http://localhost:9411/api/v2/spans")));
+
+		StrictCurrentTraceContext braveCurrentTraceContext = StrictCurrentTraceContext.create();
+
+		CurrentTraceContext bridgeContext = new BraveCurrentTraceContext(braveCurrentTraceContext);
+
+		Tracing tracing =
+				Tracing.newBuilder()
+				       .currentTraceContext(braveCurrentTraceContext)
+				       .supportsJoin(false)
+				       .traceId128Bit(true)
+				       .sampler(Sampler.ALWAYS_SAMPLE)
+				       .addSpanHandler(spanHandler)
+				       .localServiceName("reactor-netty-examples")
+				       .build();
+
+		brave.Tracer braveTracer = tracing.tracer();
+
+		Tracer tracer = new BraveTracer(braveTracer, bridgeContext, new BraveBaggageManager());
+
+		Propagator propagator = new BravePropagator(tracing);
+
+		OBSERVATION_REGISTRY.observationConfig()
+		                    .observationHandler(new ReactorNettyPropagatingSenderTracingObservationHandler(tracer, propagator))
+		                    .observationHandler(new ReactorNettyTracingObservationHandler(tracer));
+	}
+}

reactor-netty5-examples/src/main/java/reactor/netty5/examples/documentation/http/server/tracing/Application.java

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ *
+ * 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 reactor.netty5.examples.documentation.http.server.tracing;
+
+import brave.Tracing;
+import brave.handler.SpanHandler;
+import brave.propagation.StrictCurrentTraceContext;
+import brave.sampler.Sampler;
+import io.micrometer.tracing.CurrentTraceContext;
+import io.micrometer.tracing.Tracer;
+import io.micrometer.tracing.brave.bridge.BraveBaggageManager;
+import io.micrometer.tracing.brave.bridge.BraveCurrentTraceContext;
+import io.micrometer.tracing.brave.bridge.BravePropagator;
+import io.micrometer.tracing.brave.bridge.BraveTracer;
+import io.micrometer.tracing.propagation.Propagator;
+import reactor.core.publisher.Mono;
+import reactor.netty5.DisposableServer;
+import reactor.netty5.http.observability.ReactorNettyPropagatingReceiverTracingObservationHandler;
+import reactor.netty5.http.server.HttpServer;
+import zipkin2.reporter.AsyncReporter;
+import zipkin2.reporter.brave.ZipkinSpanHandler;
+import zipkin2.reporter.urlconnection.URLConnectionSender;
+
+import static reactor.netty5.Metrics.OBSERVATION_REGISTRY;
+
+public class Application {
+
+	public static void main(String[] args) {
+		init(); //<1>
+
+		DisposableServer server =
+				HttpServer.create()
+				          .metrics(true, s -> {
+				              if (s.startsWith("/stream/")) { //<2>
+				                  return "/stream/{n}";
+				              }
+				              return s;
+				          }) //<3>
+				          .route(r -> r.get("/stream/{n}",
+				              (req, res) -> res.sendString(Mono.just(req.param("n")))))
+				          .bindNow();
+
+		server.onDispose()
+		      .block();
+	}
+
+	/**
+	 * This setup is based on
+	 * <a href="https://micrometer.io/docs/tracing#_micrometer_tracing_brave_setup">Micrometer Tracing Brave Setup</a>
+	 */
+	static void init() {
+		SpanHandler spanHandler = ZipkinSpanHandler
+				.create(AsyncReporter.create(URLConnectionSender.create("http://localhost:9411/api/v2/spans")));
+
+		StrictCurrentTraceContext braveCurrentTraceContext = StrictCurrentTraceContext.create();
+
+		CurrentTraceContext bridgeContext = new BraveCurrentTraceContext(braveCurrentTraceContext);
+
+		Tracing tracing =
+				Tracing.newBuilder()
+				       .currentTraceContext(braveCurrentTraceContext)
+				       .supportsJoin(false)
+				       .traceId128Bit(true)
+				       .sampler(Sampler.ALWAYS_SAMPLE)
+				       .addSpanHandler(spanHandler)
+				       .localServiceName("reactor-netty-examples")
+				       .build();
+
+		brave.Tracer braveTracer = tracing.tracer();
+
+		Tracer tracer = new BraveTracer(braveTracer, bridgeContext, new BraveBaggageManager());
+
+		Propagator propagator = new BravePropagator(tracing);
+
+		OBSERVATION_REGISTRY.observationConfig()
+		                    .observationHandler(new ReactorNettyPropagatingReceiverTracingObservationHandler(tracer, propagator));
+	}
+}