diff --git a/README.adoc b/README.adoc
index 768bfdd49..c7bf411e4 100644
--- a/README.adoc
+++ b/README.adoc
@@ -229,8 +229,9 @@ Below you can find an example of a Logback configuration (file named https://git
+
+ value="%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}"/>
@@ -291,7 +292,8 @@ Below you can find an example of a Logback configuration (file named https://git
-
+
+
@@ -300,6 +302,49 @@ Below you can find an example of a Logback configuration (file named https://git
NOTE: If you're using a custom `logback-spring.xml` then you have to pass the `spring.application.name` in
`bootstrap` instead of `application` property file. Otherwise your custom logback file won't read the property properly.
+==== Propagating Span Context
+
+The span context is the state that must get propagated to any child Spans across process boundaries.
+Part of the Span Context is the Baggage. The trace and span IDs are a required part of the span context.
+Baggage is an optional part.
+
+Baggage is a set of key:value pairs stored in the span context. Baggage travels together with the trace
+and is attached to every span. Spring Cloud Sleuth will understand that a header is baggage related if the HTTP
+ header is prefixed with `baggage-` and for messaging it starts with `baggage_`.
+
+IMPORTANT: There's currently no limitation of the count or size of baggage items. However, keep in mind that
+too many can decrease system throughput or increase RPC latency. In extreme cases, it could crash the app due
+to exceeding transport-level message or header capacity.
+
+Example of setting baggage on a span:
+
+[source,java]
+----
+Span initialSpan = this.tracer.createSpan("span");
+initialSpan.setBaggageItem("foo", "bar");
+----
+
+===== Baggage vs. Span Tags
+
+Baggage travels with the trace (i.e. every child span contains the baggage of its parent). Zipkin has no knowledge of
+baggage and will not even receive that information.
+
+Tags are attached to a specific span - they are presented for that particular span only. However you
+can search by tag to find the trace, where there exists a span having the searched tag value.
+
+If you want to be able to lookup a span based on baggage, you should add corresponding entry as a tag in the root span.
+
+[source,java]
+----
+@Autowired Tracer tracer;
+
+Span span = tracer.getCurrentSpan();
+String baggageKey = "key";
+String baggageValue = "foo";
+span.setBaggageItem(baggageKey, baggageValue);
+tracer.addTag(baggageKey, baggageValue);
+----
+
=== Adding to the project
==== Only Sleuth (log correlation)
@@ -315,7 +360,7 @@ the `spring-cloud-starter-sleuth` module to your project.
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -336,7 +381,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}
@@ -360,7 +405,7 @@ If you want both Sleuth and Zipkin just add the `spring-cloud-starter-zipkin` de
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -381,7 +426,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}
@@ -405,7 +450,7 @@ If you want both Sleuth and Zipkin just add the `spring-cloud-sleuth-stream` dep
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -437,7 +482,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}
@@ -467,7 +512,7 @@ dependency
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -499,7 +544,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}
@@ -599,7 +644,7 @@ IMPORTANT: If using Zipkin or Stream, configure the percentage of spans exported
NOTE: the SLF4J MDC is always set and logback users will immediately see the trace and span ids in logs per the example
above. Other logging systems have to configure their own formatter to get the same result. The default is
- `logging.pattern.level` set to `%clr(%5p) %clr([${spring.application.name:},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}]){yellow}`
+ `logging.pattern.level` set to `%5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}]`
(this is a Spring Boot feature for logback users).
*This means that if you're not using SLF4J this pattern WILL NOT be automatically applied*.
diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/src/main/asciidoc/intro.adoc
index 822312a97..1fb913bb7 100644
--- a/docs/src/main/asciidoc/intro.adoc
+++ b/docs/src/main/asciidoc/intro.adoc
@@ -183,6 +183,48 @@ include::https://raw.githubusercontent.com/spring-cloud-samples/sleuth-documenta
NOTE: If you're using a custom `logback-spring.xml` then you have to pass the `spring.application.name` in
`bootstrap` instead of `application` property file. Otherwise your custom logback file won't read the property properly.
+==== Propagating Span Context
+
+The span context is the state that must get propagated to any child Spans across process boundaries.
+Part of the Span Context is the Baggage. The trace and span IDs are a required part of the span context.
+Baggage is an optional part.
+
+Baggage is a set of key:value pairs stored in the span context. Baggage travels together with the trace
+and is attached to every span. Spring Cloud Sleuth will understand that a header is baggage related if the HTTP
+ header is prefixed with `baggage-` and for messaging it starts with `baggage_`.
+
+IMPORTANT: There's currently no limitation of the count or size of baggage items. However, keep in mind that
+too many can decrease system throughput or increase RPC latency. In extreme cases, it could crash the app due
+to exceeding transport-level message or header capacity.
+
+Example of setting baggage on a span:
+
+[source,java]
+----
+include::{github-raw}/spring-cloud-sleuth-core/src/test/java/org/springframework/cloud/sleuth/instrument/web/multiple/MultipleHopsIntegrationTests.java[tags=baggage,indent=0]
+----
+
+===== Baggage vs. Span Tags
+
+Baggage travels with the trace (i.e. every child span contains the baggage of its parent). Zipkin has no knowledge of
+baggage and will not even receive that information.
+
+Tags are attached to a specific span - they are presented for that particular span only. However you
+can search by tag to find the trace, where there exists a span having the searched tag value.
+
+If you want to be able to lookup a span based on baggage, you should add corresponding entry as a tag in the root span.
+
+[source,java]
+----
+@Autowired Tracer tracer;
+
+Span span = tracer.getCurrentSpan();
+String baggageKey = "key";
+String baggageValue = "foo";
+span.setBaggageItem(baggageKey, baggageValue);
+tracer.addTag(baggageKey, baggageValue);
+----
+
=== Adding to the project
==== Only Sleuth (log correlation)
@@ -198,7 +240,7 @@ the `spring-cloud-starter-sleuth` module to your project.
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -219,7 +261,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}
@@ -243,7 +285,7 @@ If you want both Sleuth and Zipkin just add the `spring-cloud-starter-zipkin` de
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -264,7 +306,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}
@@ -288,7 +330,7 @@ If you want both Sleuth and Zipkin just add the `spring-cloud-sleuth-stream` dep
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -320,7 +362,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}
@@ -350,7 +392,7 @@ dependency
org.springframework.cloud
spring-cloud-dependencies
- Brixton.RELEASE
+ Camden.RELEASE
pom
import
@@ -382,7 +424,7 @@ the Spring BOM
----
dependencyManagement { <1>
imports {
- mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+ mavenBom "org.springframework.cloud:spring-cloud-dependencies:Camden.RELEASE"
}
}