SpringCloud/spring-cloud-sleuth
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added back the baggage docs

Browse Source
This commit is contained in:
Marcin Grzejszczak
2017-02-08 13:29:01 +01:00
parent 9d21d1b07b
commit 4a818eee73
2 changed files with 106 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
README.adoc
View File

@@ -229,8 +229,9 @@ Below you can find an example of a Logback configuration (file named https://git
<!-- Example for logging into the build folder of your project -->
<property name="LOG_FILE" value="${BUILD_FOLDER:-build}/${springAppName}"/>​
<!-- You can override this to have a custom pattern -->
<property name="CONSOLE_LOG_PATTERN"
value="%clr(%d{yyyy-MM-dd HH:mm:ss.SSS}){faint} %clr(${LOG_LEVEL_PATTERN:-%5p}) %clr([${springAppName:-},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-B3-ParentSpanId:-},%X{X-Span-Export:-}]){yellow} %clr(${PID:- }){magenta} %clr(---){faint} %clr([%15.15t]){faint} %clr(%-40.40logger{39}){cyan} %clr(:){faint} %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}"/>
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}"/>
<!-- Appender to log to console -->
<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
@@ -291,7 +292,8 @@ Below you can find an example of a Logback configuration (file named https://git
​
<root level="INFO">
<appender-ref ref="console"/>
<appender-ref ref="logstash"/>
<!-- uncomment this to have also JSON logs -->
<!--<appender-ref ref="logstash"/>-->
<!--<appender-ref ref="flatfile"/>-->
</root>
</configuration>
@@ -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.
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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*.

58
docs/src/main/asciidoc/intro.adoc
View File

@@ -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.
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>Brixton.RELEASE</version>
<version>Camden.RELEASE</version>
<type>pom</type>
<scope>import</scope>
</dependency>
@@ -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"
}
}