[doc] Enhance context propagation reference documentation (#2841)

docs/asciidoc/http-client.adoc

@@ -486,9 +486,17 @@ include::{examplesdir}/tracing/custom/Application.java[lines=18..85]
 <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.
-<4> Custom `ChannelHandler` that uses context propagation library.
+<4> Custom `ChannelHandler` that uses context propagation library. This concrete example overrides only
+`ChannelOutboundHandlerAdapter#write`, if it is needed, the same logic can be used for the rest of the methods.
+Also, this concrete example sets all `ThreadLocal` values for which there is a value in the given `Channel`,
+if another behaviour is needed please check https://micrometer.io/docs/contextPropagation[`context propagation library API`].
+For example, you may want to set only some of the `ThreadLocal` values.
 ====
 
+NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the `ObservationRegistry` created by this framework.
+For this purpose you need to invoke {javadoc}/reactor/netty/Metrics.html#observationRegistry-io.micrometer.observation.ObservationRegistry-[`reactor.netty.Metrics#observationRegistry`].
+You may also need to configure the Reactor Netty `ObservationHandlers` using the API provided by the framework.
+
 == Unix Domain Sockets
 The `HTTP` client supports Unix Domain Sockets (UDS) when native transport is in use.
 

docs/asciidoc/http-server.adoc

@@ -662,9 +662,17 @@ include::{examplesdir}/tracing/custom/Application.java[lines=18..85]
 <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.
-<4> Custom `ChannelHandler` that uses context propagation library.
+<4> Custom `ChannelHandler` that uses context propagation library. This concrete example overrides only
+`ChannelOutboundHandlerAdapter#write`, if it is needed, the same logic can be used for the rest of the methods.
+Also, this concrete example sets all `ThreadLocal` values for which there is a value in the given `Channel`,
+if another behaviour is needed please check https://micrometer.io/docs/contextPropagation[`context propagation library API`].
+For example, you may want to set only some of the `ThreadLocal` values.
 ====
 
+NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the `ObservationRegistry` created by this framework.
+For this purpose you need to invoke {javadoc}/reactor/netty/Metrics.html#observationRegistry-io.micrometer.observation.ObservationRegistry-[`reactor.netty.Metrics#observationRegistry`].
+You may also need to configure the Reactor Netty `ObservationHandlers` using the API provided by the framework.
+
 == Unix Domain Sockets
 The `HTTP` server supports Unix Domain Sockets (UDS) when native transport is in use.
 

docs/asciidoc/tcp-client.adoc

@@ -368,9 +368,17 @@ include::{examplesdir}/tracing/custom/Application.java[lines=18..80]
 ----
 <1> Initializes Brave, Zipkin, and the Observation registry.
 <2> Enables the built-in integration with Micrometer.
-<3> Custom `ChannelHandler` that uses context propagation library.
+<3> Custom `ChannelHandler` that uses context propagation library. This concrete example overrides only
+`ChannelOutboundHandlerAdapter#connect`, if it is needed, the same logic can be used for the rest of the methods.
+Also, this concrete example sets all `ThreadLocal` values for which there is a value in the given `Channel`,
+if another behaviour is needed please check https://micrometer.io/docs/contextPropagation[`context propagation library API`].
+For example, you may want to set only some of the `ThreadLocal` values.
 ====
 
+NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the `ObservationRegistry` created by this framework.
+For this purpose you need to invoke {javadoc}/reactor/netty/Metrics.html#observationRegistry-io.micrometer.observation.ObservationRegistry-[`reactor.netty.Metrics#observationRegistry`].
+You may also need to configure the Reactor Netty `ObservationHandlers` using the API provided by the framework.
+
 == Unix Domain Sockets
 The `TCP` client supports Unix Domain Sockets (UDS) when native transport is in use.
 

docs/asciidoc/tcp-server.adoc

@@ -336,9 +336,17 @@ include::{examplesdir}/tracing/custom/Application.java[lines=18..86]
 ----
 <1> Initializes Brave, Zipkin, and the Observation registry.
 <2> Enables the built-in integration with Micrometer.
-<3> Custom `ChannelHandler` that uses context propagation library.
+<3> Custom `ChannelHandler` that uses context propagation library. This concrete example overrides only
+`ChannelInboundHandlerAdapter#channelActive`, if it is needed, the same logic can be used for the rest of the methods.
+Also, this concrete example sets all `ThreadLocal` values for which there is a value in the given `Channel`,
+if another behaviour is needed please check https://micrometer.io/docs/contextPropagation[`context propagation library API`].
+For example, you may want to set only some of the `ThreadLocal` values.
 ====
 
+NOTE: When you enable Reactor Netty tracing within a framework, you may need to let Reactor Netty use the `ObservationRegistry` created by this framework.
+For this purpose you need to invoke {javadoc}/reactor/netty/Metrics.html#observationRegistry-io.micrometer.observation.ObservationRegistry-[`reactor.netty.Metrics#observationRegistry`].
+You may also need to configure the Reactor Netty `ObservationHandlers` using the API provided by the framework.
+
 == Unix Domain Sockets
 The `TCP` server supports Unix Domain Sockets (UDS) when native transport is in use.
 

reactor-netty-core/src/contextPropagationTest/java/reactor/netty/ChannelContextAccessorTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2022-2023 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.
@@ -52,7 +52,7 @@ void test(Context context, String expectation) {
 
 		TestThreadLocalHolder.value("test2");
 
-		try (ContextSnapshot.Scope scope = ContextSnapshot.captureFrom(channel).setThreadLocals()) {
+		try (ContextSnapshot.Scope scope = ContextSnapshot.setAllThreadLocalsFrom(channel)) {
 			assertThat(TestThreadLocalHolder.value()).isEqualTo(expectation);
 		}
 		finally {

reactor-netty-core/src/contextPropagationTest/java/reactor/netty/ContextPropagationTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2022-2023 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.
@@ -134,7 +134,7 @@ public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise)
 				}
 				if (msg instanceof ByteBuf) {
 					ByteBuf buffer1;
-					try (ContextSnapshot.Scope scope = ContextSnapshot.captureFrom(ctx.channel()).setThreadLocals()) {
+					try (ContextSnapshot.Scope scope = ContextSnapshot.setAllThreadLocalsFrom(ctx.channel())) {
 						buffer1 = Unpooled.wrappedBuffer(TestThreadLocalHolder.value().getBytes(Charset.defaultCharset()));
 					}
 					ByteBuf buffer2 = Unpooled.wrappedBuffer(TestThreadLocalHolder.value().getBytes(Charset.defaultCharset()));

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2022-2023 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.
@@ -75,7 +75,7 @@ public boolean isSharable() {
 		@Override
 		@SuppressWarnings({"FutureReturnValueIgnored", "try"})
 		public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) {
-			try (ContextSnapshot.Scope scope = ContextSnapshot.captureFrom(ctx.channel()).setThreadLocals()) {
+			try (ContextSnapshot.Scope scope = ContextSnapshot.setAllThreadLocalsFrom(ctx.channel())) {
 				System.out.println("Current Observation in Scope: " + OBSERVATION_REGISTRY.getCurrentObservation());
 				//"FutureReturnValueIgnored" this is deliberate
 				ctx.write(msg, promise);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2022-2023 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.
@@ -75,7 +75,7 @@ public boolean isSharable() {
 		@Override
 		@SuppressWarnings({"FutureReturnValueIgnored", "try"})
 		public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) {
-			try (ContextSnapshot.Scope scope = ContextSnapshot.captureFrom(ctx.channel()).setThreadLocals()) {
+			try (ContextSnapshot.Scope scope = ContextSnapshot.setAllThreadLocalsFrom(ctx.channel())) {
 				System.out.println("Current Observation in Scope: " + OBSERVATION_REGISTRY.getCurrentObservation());
 				//"FutureReturnValueIgnored" this is deliberate
 				ctx.write(msg, promise);

reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/tcp/client/tracing/custom/Application.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2022-2023 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.
@@ -70,7 +70,7 @@ public boolean isSharable() {
 		@Override
 		@SuppressWarnings({"FutureReturnValueIgnored", "try"})
 		public void connect(ChannelHandlerContext ctx, SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise) {
-			try (ContextSnapshot.Scope scope = ContextSnapshot.captureFrom(ctx.channel()).setThreadLocals()) {
+			try (ContextSnapshot.Scope scope = ContextSnapshot.setAllThreadLocalsFrom(ctx.channel())) {
 				System.out.println("Current Observation in Scope: " + OBSERVATION_REGISTRY.getCurrentObservation());
 				//"FutureReturnValueIgnored" this is deliberate
 				ctx.connect(remoteAddress, localAddress, promise);

reactor-netty-examples/src/main/java/reactor/netty/examples/documentation/tcp/server/tracing/custom/Application.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2022-2023 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.
@@ -72,7 +72,7 @@ static final class CustomChannelInboundHandler extends ChannelInboundHandlerAdap
 		@Override
 		@SuppressWarnings("try")
 		public void channelActive(ChannelHandlerContext ctx) {
-			try (ContextSnapshot.Scope scope = ContextSnapshot.captureFrom(ctx.channel()).setThreadLocals()) {
+			try (ContextSnapshot.Scope scope = ContextSnapshot.setAllThreadLocalsFrom(ctx.channel())) {
 				System.out.println("Current Observation in Scope: " + OBSERVATION_REGISTRY.getCurrentObservation());
 				ctx.fireChannelActive();
 			}

reactor-netty-http/src/contextPropagationTest/java/reactor/netty/ContextPropagationTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 VMware, Inc. or its affiliates, All Rights Reserved.
+ * Copyright (c) 2022-2023 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.
@@ -182,7 +182,7 @@ public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise)
 				TestThreadLocalHolder.value(threadLocalValue);
 				if (msg instanceof FullHttpRequest) {
 					ByteBuf buffer1;
-					try (ContextSnapshot.Scope scope = ContextSnapshot.captureFrom(ctx.channel()).setThreadLocals()) {
+					try (ContextSnapshot.Scope scope = ContextSnapshot.setAllThreadLocalsFrom(ctx.channel())) {
 						buffer1 = Unpooled.wrappedBuffer(TestThreadLocalHolder.value().getBytes(Charset.defaultCharset()));
 					}
 					ByteBuf buffer2 = Unpooled.wrappedBuffer(TestThreadLocalHolder.value().getBytes(Charset.defaultCharset()));