Merge branch '3.1.x'

Closes gh-36113

spring-boot-project/spring-boot-docs/build.gradle

@@ -90,6 +90,7 @@ dependencies {
 	implementation("ch.qos.logback:logback-classic")
 	implementation("com.zaxxer:HikariCP")
 	implementation("io.micrometer:micrometer-core")
+	implementation("io.micrometer:micrometer-tracing")
 	implementation("io.micrometer:micrometer-registry-graphite")
 	implementation("io.micrometer:micrometer-registry-jmx")
 	implementation("io.projectreactor.netty:reactor-netty-http")

spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc

@@ -171,3 +171,18 @@ include::code:CustomObservation[]
 This will create an observation named "some-operation" with the tag "some-tag=some-value".
 
 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.
+
+[[actuator.micrometer-tracing.baggage]]
+=== Baggage
+You can create baggage with the `Tracer` API:
+
+include::code:CreatingBaggage[]
+
+This example creates baggage named `baggage1` with the value `value1`.
+The baggage is automatically propagated over the network if you're using W3C propagation.
+If you're using B3 propagation, baggage is not automatically propagated.
+To manually propagate baggage over the network, use the configprop:management.tracing.baggage.remote-fields[] configuration property (this works for W3C, too).
+For the example above, setting this property to `baggage1` results in an HTTP header `baggage1: value1`.
+
+If you want to propagate the baggage to the MDC, use the configprop:management.tracing.baggage.correlation.fields[] configuration property.
+For the example above, setting this property to `baggage1` results in an MDC entry named `baggage1`.

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/baggage/CreatingBaggage.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2012-2023 the original author or authors.
+ *
+ * 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 org.springframework.boot.docs.actuator.micrometertracing.baggage;
+
+import io.micrometer.tracing.BaggageInScope;
+import io.micrometer.tracing.Tracer;
+
+import org.springframework.stereotype.Component;
+
+@Component
+class CreatingBaggage {
+
+	private final Tracer tracer;
+
+	CreatingBaggage(Tracer tracer) {
+		this.tracer = tracer;
+	}
+
+	void doSomething() {
+		try (BaggageInScope scope = this.tracer.createBaggageInScope("baggage1", "value1")) {
+			// Business logic
+		}
+	}
+
+}