From 4a818eee73ac9a885a3a6d559b2325397da36133 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Wed, 8 Feb 2017 13:29:01 +0100 Subject: [PATCH] Added back the baggage docs --- README.adoc | 67 ++++++++++++++++++++++++++----- docs/src/main/asciidoc/intro.adoc | 58 ++++++++++++++++++++++---- 2 files changed, 106 insertions(+), 19 deletions(-) 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" } }