From 2b398827de6569558b2f8fa043a0491c99c3bbfc Mon Sep 17 00:00:00 2001
From: Moritz Halbritter <mkammerer@vmware.com>
Date: Thu, 29 Jun 2023 11:30:58 +0200
Subject: [PATCH] Add "baggage" section to tracing docs

Closes gh-34977
---
 .../spring-boot-docs/build.gradle             |  1 +
 .../src/docs/asciidoc/actuator/tracing.adoc   | 17 +++++++-
 .../baggage/CreatingBaggage.java              | 39 +++++++++++++++++++
 3 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/baggage/CreatingBaggage.java

diff --git a/spring-boot-project/spring-boot-docs/build.gradle b/spring-boot-project/spring-boot-docs/build.gradle
index 6bcadfe323..55af24f7f8 100644
--- a/spring-boot-project/spring-boot-docs/build.gradle
+++ b/spring-boot-project/spring-boot-docs/build.gradle
@@ -73,6 +73,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")
diff --git a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc
index 80e6305cd7..28cac4d2f9 100644
--- a/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc
+++ b/spring-boot-project/spring-boot-docs/src/docs/asciidoc/actuator/tracing.adoc
@@ -65,7 +65,7 @@ Now open the Zipkin UI at `http://localhost:9411` and press the "Run Query" butt
 You should see one trace.
 Press the "Show" button to see the details of that trace.
 
-TIP: You can include the current trace and span id in the logs by setting the `logging.pattern.level` property to `%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]`
+TIP: You can include the current trace and span id in the logs by setting the configprop:logging.pattern.level[] property to `%5p [${spring.application.name:},%X{traceId:-},%X{spanId:-}]`
 
 
 
@@ -138,3 +138,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`.
diff --git a/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/baggage/CreatingBaggage.java b/spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/actuator/micrometertracing/baggage/CreatingBaggage.java
new file mode 100644
index 0000000000..89fe2c34fc
--- /dev/null
+++ b/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.createBaggage("baggage1", "value1").makeCurrent()) {
+			// Business logic
+		}
+	}
+
+}