diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/ghpages.sh b/spring-cloud-sleuth/1.0.10.RELEASE/ghpages.sh new file mode 100644 index 00000000..57c5da3a --- /dev/null +++ b/spring-cloud-sleuth/1.0.10.RELEASE/ghpages.sh @@ -0,0 +1,330 @@ +#!/bin/bash -x + +set -e + +# Set default props like MAVEN_PATH, ROOT_FOLDER etc. +function set_default_props() { + # The script should be executed from the root folder + ROOT_FOLDER=`pwd` + echo "Current folder is ${ROOT_FOLDER}" + + if [[ ! -e "${ROOT_FOLDER}/.git" ]]; then + echo "You're not in the root folder of the project!" + exit 1 + fi + + # Prop that will let commit the changes + COMMIT_CHANGES="no" + MAVEN_PATH=${MAVEN_PATH:-} + echo "Path to Maven is [${MAVEN_PATH}]" + REPO_NAME=${PWD##*/} + echo "Repo name is [${REPO_NAME}]" + SPRING_CLOUD_STATIC_REPO=${SPRING_CLOUD_STATIC_REPO:-git@github.com:spring-cloud/spring-cloud-static.git} + echo "Spring Cloud Static repo is [${SPRING_CLOUD_STATIC_REPO}" +} + +# Check if gh-pages exists and docs have been built +function check_if_anything_to_sync() { + git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + + if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 + fi + + if ! [ -d docs/target/generated-docs ] && ! [ "${BUILD}" == "yes" ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 + fi +} + +function retrieve_current_branch() { + # Code getting the name of the current branch. For master we want to publish as we did until now + # http://stackoverflow.com/questions/1593051/how-to-programmatically-determine-the-current-checked-out-git-branch + # If there is a branch already passed will reuse it - otherwise will try to find it + CURRENT_BRANCH=${BRANCH} + if [[ -z "${CURRENT_BRANCH}" ]] ; then + CURRENT_BRANCH=$(git symbolic-ref -q HEAD) + CURRENT_BRANCH=${CURRENT_BRANCH##refs/heads/} + CURRENT_BRANCH=${CURRENT_BRANCH:-HEAD} + fi + echo "Current branch is [${CURRENT_BRANCH}]" + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" +} + +# Switches to the provided value of the release version. We always prefix it with `v` +function switch_to_tag() { + git checkout v${VERSION} +} + +# Build the docs if switch is on +function build_docs_if_applicable() { + if [[ "${BUILD}" == "yes" ]] ; then + ./mvnw clean install -P docs -pl docs -DskipTests + fi +} + +# Get the name of the `docs.main` property +# Get whitelisted branches - assumes that a `docs` module is available under `docs` profile +function retrieve_doc_properties() { + MAIN_ADOC_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args='${docs.main}' \ + --non-recursive \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec) + echo "Extracted 'main.adoc' from Maven build [${MAIN_ADOC_VALUE}]" + + + WHITELIST_PROPERTY=${WHITELIST_PROPERTY:-"docs.whitelisted.branches"} + WHITELISTED_BRANCHES_VALUE=$("${MAVEN_PATH}"mvn -q \ + -Dexec.executable="echo" \ + -Dexec.args="\${${WHITELIST_PROPERTY}}" \ + org.codehaus.mojo:exec-maven-plugin:1.3.1:exec \ + -P docs \ + -pl docs) + echo "Extracted '${WHITELIST_PROPERTY}' from Maven build [${WHITELISTED_BRANCHES_VALUE}]" +} + +# Stash any outstanding changes +function stash_changes() { + git diff-index --quiet HEAD && dirty=$? || (echo "Failed to check if the current repo is dirty. Assuming that it is." && dirty="1") + if [ "$dirty" != "0" ]; then git stash; fi +} + +# Switch to gh-pages branch to sync it with current branch +function add_docs_from_target() { + local DESTINATION_REPO_FOLDER + if [[ -z "${DESTINATION}" && -z "${CLONE}" ]] ; then + DESTINATION_REPO_FOLDER=${ROOT_FOLDER} + elif [[ "${CLONE}" == "yes" ]]; then + mkdir -p ${ROOT_FOLDER}/target + local clonedStatic=${ROOT_FOLDER}/target/spring-cloud-static + if [[ ! -e "${clonedStatic}/.git" ]]; then + echo "Cloning Spring Cloud Static to target" + git clone ${SPRING_CLOUD_STATIC_REPO} ${clonedStatic} && git checkout gh-pages + else + echo "Spring Cloud Static already cloned - will pull changes" + cd ${clonedStatic} && git checkout gh-pages && git pull origin gh-pages + fi + DESTINATION_REPO_FOLDER=${clonedStatic}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + else + if [[ ! -e "${DESTINATION}/.git" ]]; then + echo "[${DESTINATION}] is not a git repository" + exit 1 + fi + DESTINATION_REPO_FOLDER=${DESTINATION}/${REPO_NAME} + mkdir -p ${DESTINATION_REPO_FOLDER} + echo "Destination was provided [${DESTINATION}]" + fi + cd ${DESTINATION_REPO_FOLDER} + git checkout gh-pages + git pull origin gh-pages + + # Add git branches + ################################################################### + if [[ -z "${VERSION}" ]] ; then + copy_docs_for_current_version + else + copy_docs_for_provided_version + fi + commit_changes_if_applicable +} + + +# Copies the docs by using the retrieved properties from Maven build +function copy_docs_for_current_version() { + if [[ "${CURRENT_BRANCH}" == "master" ]] ; then + echo -e "Current branch is master - will copy the current docs only to the root folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f ${ROOT_FOLDER}/ + git add -A ${ROOT_FOLDER}/$file + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Current branch is [${CURRENT_BRANCH}]" + # http://stackoverflow.com/questions/29300806/a-bash-script-to-check-if-a-string-is-present-in-a-comma-separated-list-of-strin + if [[ ",${WHITELISTED_BRANCHES_VALUE}," = *",${CURRENT_BRANCH},"* ]] ; then + mkdir -p ${ROOT_FOLDER}/${CURRENT_BRANCH} + echo -e "Branch [${CURRENT_BRANCH}] is whitelisted! Will copy the current docs to the [${CURRENT_BRANCH}] folder" + for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ "${file}" == "${MAIN_ADOC_VALUE}.html" ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/index.html + else + cp -rf $f ${ROOT_FOLDER}/${CURRENT_BRANCH} + git add -A ${ROOT_FOLDER}/${CURRENT_BRANCH}/$file + fi + fi + done + COMMIT_CHANGES="yes" + else + echo -e "Branch [${CURRENT_BRANCH}] is not on the white list! Check out the Maven [${WHITELIST_PROPERTY}] property in + [docs] module available under [docs] profile. Won't commit any changes to gh-pages for this branch." + fi + fi +} + +# Copies the docs by using the explicitly provided version +function copy_docs_for_provided_version() { + local FOLDER=${DESTINATION_REPO_FOLDER}/${VERSION} + mkdir -p ${FOLDER} + echo -e "Current tag is [v${VERSION}] Will copy the current docs to the [${FOLDER}] folder" + for f in ${ROOT_FOLDER}/docs/target/generated-docs/*; do + file=${f#${ROOT_FOLDER}/docs/target/generated-docs/*} + copy_docs_for_branch ${file} ${FOLDER} + done + COMMIT_CHANGES="yes" + CURRENT_BRANCH="v${VERSION}" +} + +# Copies the docs from target to the provided destination +# Params: +# $1 - file from target +# $2 - destination to which copy the files +function copy_docs_for_branch() { + local file=$1 + local destination=$2 + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^${file}$; then + # Not ignored... + # We want users to access 1.0.0.RELEASE/ instead of 1.0.0.RELEASE/spring-cloud.sleuth.html + if [[ ("${file}" == "${MAIN_ADOC_VALUE}.html") || ("${file}" == "${REPO_NAME}.html") ]] ; then + # We don't want to copy the spring-cloud-sleuth.html + # we want it to be converted to index.html + cp -rf $f ${destination}/index.html + git add -A ${destination}/index.html + else + cp -rf $f ${destination} + git add -A ${destination}/$file + fi + fi +} + +function commit_changes_if_applicable() { + if [[ "${COMMIT_CHANGES}" == "yes" ]] ; then + COMMIT_SUCCESSFUL="no" + git commit -a -m "Sync docs from ${CURRENT_BRANCH} to gh-pages" && COMMIT_SUCCESSFUL="yes" || echo "Failed to commit changes" + + # Uncomment the following push if you want to auto push to + # the gh-pages branch whenever you commit to master locally. + # This is a little extreme. Use with care! + ################################################################### + if [[ "${COMMIT_SUCCESSFUL}" == "yes" ]] ; then + git push origin gh-pages + fi + fi +} + +# Switch back to the previous branch and exit block +function checkout_previous_branch() { + # If -version was provided we need to come back to root project + cd ${ROOT_FOLDER} + git checkout ${CURRENT_BRANCH} || echo "Failed to check the branch... continuing with the script" + if [ "$dirty" != "0" ]; then git stash pop; fi + exit 0 +} + +# Assert if properties have been properly passed +function assert_properties() { +echo "VERSION [${VERSION}], DESTINATION [${DESTINATION}], CLONE [${CLONE}]" +if [[ "${VERSION}" != "" && (-z "${DESTINATION}" && -z "${CLONE}") ]] ; then echo "Version was set but destination / clone was not!"; exit 1;fi +if [[ ("${DESTINATION}" != "" && "${CLONE}" != "") && -z "${VERSION}" ]] ; then echo "Destination / clone was set but version was not!"; exit 1;fi +if [[ "${DESTINATION}" != "" && "${CLONE}" == "yes" ]] ; then echo "Destination and clone was set. Pick one!"; exit 1;fi +} + +# Prints the usage +function print_usage() { +cat </` +- if the destination switch is passed (-d) then the script will check if the provided dir is a git repo and then will + switch to gh-pages of that repo and copy the generated docs to `docs//` + +USAGE: + +You can use the following options: + +-v|--version - the script will apply the whole procedure for a particular library version +-d|--destination - the root of destination folder where the docs should be copied. You have to use the full path. + E.g. point to spring-cloud-static folder. Can't be used with (-c) +-b|--build - will run the standard build process after checking out the branch +-c|--clone - will automatically clone the spring-cloud-static repo instead of providing the destination. + Obviously can't be used with (-d) + +EOF +} + + +# ========================================== +# ____ ____ _____ _____ _____ _______ +# / ____|/ ____| __ \|_ _| __ \__ __| +# | (___ | | | |__) | | | | |__) | | | +# \___ \| | | _ / | | | ___/ | | +# ____) | |____| | \ \ _| |_| | | | +# |_____/ \_____|_| \_\_____|_| |_| +# +# ========================================== + +while [[ $# > 0 ]] +do +key="$1" +case ${key} in + -v|--version) + VERSION="$2" + shift # past argument + ;; + -d|--destination) + DESTINATION="$2" + shift # past argument + ;; + -b|--build) + BUILD="yes" + ;; + -c|--clone) + CLONE="yes" + ;; + -h|--help) + print_usage + exit 0 + ;; + *) + echo "Invalid option: [$1]" + print_usage + exit 1 + ;; +esac +shift # past argument or value +done + +assert_properties +set_default_props +check_if_anything_to_sync +if [[ -z "${VERSION}" ]] ; then + retrieve_current_branch +else + switch_to_tag +fi +build_docs_if_applicable +retrieve_doc_properties +stash_changes +add_docs_from_target +checkout_previous_branch \ No newline at end of file diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/.gitkeep b/spring-cloud-sleuth/1.0.10.RELEASE/images/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/dependencies.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/dependencies.png new file mode 100644 index 00000000..d0eceb6f Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/dependencies.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/kibana.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/kibana.png new file mode 100644 index 00000000..bc44a43f Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/kibana.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/parents.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/parents.png new file mode 100644 index 00000000..7f868f75 Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/parents.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/pws.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/pws.png new file mode 100644 index 00000000..a791bd74 Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/pws.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/trace-id.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/trace-id.png new file mode 100644 index 00000000..0603bb08 Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/trace-id.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-trace-screenshot.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-trace-screenshot.png new file mode 100644 index 00000000..f0452f0f Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-trace-screenshot.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-traces.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-traces.png new file mode 100644 index 00000000..673ece9a Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-traces.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-ui.png b/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-ui.png new file mode 100644 index 00000000..34b0215b Binary files /dev/null and b/spring-cloud-sleuth/1.0.10.RELEASE/images/zipkin-ui.png differ diff --git a/spring-cloud-sleuth/1.0.10.RELEASE/index.html b/spring-cloud-sleuth/1.0.10.RELEASE/index.html new file mode 100644 index 00000000..6d7acd9c --- /dev/null +++ b/spring-cloud-sleuth/1.0.10.RELEASE/index.html @@ -0,0 +1,2339 @@ + + + + + + + + +Spring Cloud Sleuth + + + + + +
+
+
+
+

1.0.10.RELEASE

+
+
+

Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud.

+
+
+
+
+

Terminology

+
+

Spring Cloud Sleuth borrows Dapper’s terminology.

+
+
+

Span: The basic unit of work. For example, sending an RPC is a new span, as is sending a response to an +RPC. Span’s are identified by a unique 64-bit ID for the span and another 64-bit ID for the trace the span +is a part of. Spans also have other data, such as descriptions, timestamped events, key-value +annotations (tags), the ID of the span that caused them, and process ID’s (normally IP address).

+
+
+

Spans are started and stopped, and they keep track of their timing information. Once you create a +span, you must stop it at some point in the future.

+
+
+ + + + + +
+
Tip
+		 +The initial span that starts a trace is called a root span. The value of span id +of that span is equal to trace id. +
+
+
+

Trace: A set of spans forming a tree-like structure. For example, if you are running a distributed +big-data store, a trace might be formed by a put request.

+
+
+

Annotation: is used to record existence of an event in time. Some of the core annotations used to define +the start and stop of a request are:

+
+
+
    +
  • +

    cs - Client Sent - The client has made a request. This annotation depicts the start of the span.

    +
    • +
  • +

    sr - Server Received - The server side got the request and will start processing it. +If one subtracts the cs timestamp from this timestamp one will receive the network latency.

    +
    • +
  • +

    ss - Server Sent - Annotated upon completion of request processing (when the response +got sent back to the client). If one subtracts the sr timestamp from this timestamp one +will receive the time needed by the server side to process the request.

    +
    • +
  • +

    cr - Client Received - Signifies the end of the span. The client has successfully received the +response from the server side. If one subtracts the cs timestamp from this timestamp one +will receive the whole time needed by the client to receive the response from the server.

    +
    • +
+
+
+

Visualization of what Span and Trace will look in a system together with the Zipkin annotations:

+
+
+
+Trace Info propagation +
+
+
+

Each color of a note signifies a span (7 spans - from A to G). If you have such information in the note:

+
+
+
+
Trace Id = X
+Span Id = D
+Client Sent
+
+
+
+

That means that the current span has Trace-Id set to X, Span-Id set to D. It also has emitted + Client Sent event.

+
+
+

This is how the visualization of the parent / child relationship of spans would look like:

+
+
+
+Parent child relationship +
+
+
+
+

Purpose

+
+

In the following sections the example from the image above will be taken into consideration.

+
+
+

Distributed tracing with Zipkin

+
+

Altogether there are 10 spans . If you go to traces in Zipkin you will see this number:

+
+
+
+Traces +
+
+
+

However if you pick a particular trace then you will see 7 spans:

+
+
+
+Traces Info propagation +
+
+
+ + + + + +
+
Note
+		 +When picking a particular trace you will see merged spans. That means that if there were 2 spans sent to +Zipkin with Server Received and Server Sent / Client Received and Client Sent +annotations then they will presented as a single span. +
+
+
+

In the image depicting the visualization of what Span and Trace is you can see 20 +colorful labels. How does it happen that in Zipkin 10 spans are received?

+
+
+
    +
  • +

    2 span A labels signify span started and closed. Upon closing a single span is sent to Zipkin.

    +
    • +
  • +

    4 span B labels are in fact are single span with 4 annotations. However this span is composed of +two separate instances. One sent from service 1 and one from service 2. So in fact two span instances will be sent +to Zipkin and merged there.

    +
    • +
  • +

    2 span C labels signify span started and closed. Upon closing a single span is sent to Zipkin.

    +
    • +
  • +

    4 span B labels are in fact are single span with 4 annotations. However this span is composed of +two separate instances. One sent from service 2 and one from service 3. So in fact two span instances will be sent +to Zipkin and merged there.

    +
    • +
  • +

    2 span E labels signify span started and closed. Upon closing a single span is sent to Zipkin.

    +
    • +
  • +

    4 span B labels are in fact are single span with 4 annotations. However this span is composed of +two separate instances. One sent from service 2 and one from service 4. So in fact two span instances will be sent +to Zipkin and merged there.

    +
    • +
  • +

    2 span G labels signify span started and closed. Upon closing a single span is sent to Zipkin.

    +
    • +
+
+
+

So 1 span from A, 2 spans from B, 1 span from C, 2 spans from D, 1 span from E, 2 spans from F and 1 from G. +Altogether 10 spans.

+
+
+
+Zipkin deployed on Pivotal Web Services +
+
Click Pivotal Web Services icon to see it live!Click Pivotal Web Services icon to see it live!
+
+
+

The dependency graph in Zipkin would look like this:

+
+
+
+Dependencies +
+
+
+
+Zipkin deployed on Pivotal Web Services +
+
Click Pivotal Web Services icon to see it live!Click Pivotal Web Services icon to see it live!
+
+
+
+

Log correlation

+
+

When grepping the logs of those four applications by trace id equal to e.g. 2485ec27856c56f4 one would get the following:

+
+
+
+
service1.log:2016-02-26 11:15:47.561  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Hello from service1. Calling service2
+service2.log:2016-02-26 11:15:47.710  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Hello from service2. Calling service3 and then service4
+service3.log:2016-02-26 11:15:47.895  INFO [service3,2485ec27856c56f4,1210be13194bfe5,true] 68060 --- [nio-8083-exec-1] i.s.c.sleuth.docs.service3.Application   : Hello from service3
+service2.log:2016-02-26 11:15:47.924  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service3 [Hello from service3]
+service4.log:2016-02-26 11:15:48.134  INFO [service4,2485ec27856c56f4,1b1845262ffba49d,true] 68061 --- [nio-8084-exec-1] i.s.c.sleuth.docs.service4.Application   : Hello from service4
+service2.log:2016-02-26 11:15:48.156  INFO [service2,2485ec27856c56f4,9aa10ee6fbde75fa,true] 68059 --- [nio-8082-exec-1] i.s.c.sleuth.docs.service2.Application   : Got response from service4 [Hello from service4]
+service1.log:2016-02-26 11:15:48.182  INFO [service1,2485ec27856c56f4,2485ec27856c56f4,true] 68058 --- [nio-8081-exec-1] i.s.c.sleuth.docs.service1.Application   : Got response from service2 [Hello from service2, response from service3 [Hello from service3] and from service4 [Hello from service4]]
+
+
+
+

If you’re using a log aggregating tool like Kibana, +Splunk etc. you can order the events that took place. An example of +Kibana would look like this:

+
+
+
+Log correlation with Kibana +
+
+
+

If you want to use Logstash here is the Grok pattern for Logstash:

+
+
+
+
filter {
+       # pattern matching logback pattern
+       grok {
+              match => { "message" => "%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
+       }
+}
+
+
+
+ + + + + +
+
Note
+		 +If you want to use Grok together with the logs from Cloud Foundry you have to use this pattern: +
+
+
+
+
filter {
+       # pattern matching logback pattern
+       grok {
+              match => { "message" => "(?m)OUT\s+%{TIMESTAMP_ISO8601:timestamp}\s+%{LOGLEVEL:severity}\s+\[%{DATA:service},%{DATA:trace},%{DATA:span},%{DATA:exportable}\]\s+%{DATA:pid}---\s+\[%{DATA:thread}\]\s+%{DATA:class}\s+:\s+%{GREEDYDATA:rest}" }
+       }
+}
+
+
+
+
JSON Logback with Logstash
+
+

Often you do not want to store your logs in a text file but in a JSON file that Logstash can immediately pick. To do that you have to do the following (for readability +we’re passing the dependencies in the groupId:artifactId:version notation.

+
+
+

Dependencies setup

+
+
+
    +
  • +

    Ensure that Logback is on the classpath (ch.qos.logback:logback-core)

    +
    • +
  • +

    Add Logstash Logback encode - example for version 4.6 : net.logstash.logback:logstash-logback-encoder:4.6

    +
    • +
+
+
+

Logback setup

+
+
+

Below you can find an example of a Logback configuration (file named https://github.com/spring-cloud-samples/sleuth-documentation-apps/blob/master/service1/src/main/resources/logback-spring.xml[logback-spring.xml]) that:

+
+
+
    +
  • +

    logs information from the application in a JSON format to a build/${spring.application.name}.json file

    +
    • +
  • +

    has commented out two additional appenders - console and standard log file

    +
    • +
  • +

    has the same logging pattern as the one presented in the previous section

    +
    • +
+
+
+
+
<?xml version="1.0" encoding="UTF-8"?>
+<configuration>
+	<include resource="org/springframework/boot/logging/logback/defaults.xml"/>
+	​
+	<springProperty scope="context" name="springAppName" source="spring.application.name"/>
+	<!-- Example for logging into the build folder of your project -->
+	<property name="LOG_FILE" value="${BUILD_FOLDER:-build}/${springAppName}"/>​
+
+	<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-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}"/>
+
+	<!-- Appender to log to console -->
+	<appender name="console" class="ch.qos.logback.core.ConsoleAppender">
+		<filter class="ch.qos.logback.classic.filter.ThresholdFilter">
+			<!-- Minimum logging level to be presented in the console logs-->
+			<level>INFO</level>
+		</filter>
+		<encoder>
+			<pattern>${CONSOLE_LOG_PATTERN}</pattern>
+			<charset>utf8</charset>
+		</encoder>
+	</appender>
+
+	<!-- Appender to log to file -->​
+	<appender name="flatfile" class="ch.qos.logback.core.rolling.RollingFileAppender">
+		<file>${LOG_FILE}</file>
+		<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+			<fileNamePattern>${LOG_FILE}.%d{yyyy-MM-dd}.gz</fileNamePattern>
+			<maxHistory>7</maxHistory>
+		</rollingPolicy>
+		<encoder>
+			<pattern>${CONSOLE_LOG_PATTERN}</pattern>
+			<charset>utf8</charset>
+		</encoder>
+	</appender>
+	​
+	<!-- Appender to log to file in a JSON format -->
+	<appender name="logstash" class="ch.qos.logback.core.rolling.RollingFileAppender">
+		<file>${LOG_FILE}.json</file>
+		<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+			<fileNamePattern>${LOG_FILE}.json.%d{yyyy-MM-dd}.gz</fileNamePattern>
+			<maxHistory>7</maxHistory>
+		</rollingPolicy>
+		<encoder class="net.logstash.logback.encoder.LoggingEventCompositeJsonEncoder">
+			<providers>
+				<timestamp>
+					<timeZone>UTC</timeZone>
+				</timestamp>
+				<pattern>
+					<pattern>
+						{
+						"severity": "%level",
+						"service": "${springAppName:-}",
+						"trace": "%X{X-B3-TraceId:-}",
+						"span": "%X{X-B3-SpanId:-}",
+						"exportable": "%X{X-Span-Export:-}",
+						"pid": "${PID:-}",
+						"thread": "%thread",
+						"class": "%logger{40}",
+						"rest": "%message"
+						}
+					</pattern>
+				</pattern>
+			</providers>
+		</encoder>
+	</appender>
+	​
+	<root level="INFO">
+		<!--<appender-ref ref="console"/>-->
+		<appender-ref ref="logstash"/>
+		<!--<appender-ref ref="flatfile"/>-->
+	</root>
+</configuration>
+
+
+
+ + + + + +
+
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. +
+
+
+
+
+
+

Adding to the project

+
+

Only Sleuth (log correlation)

+
+

If you want to profit only from Spring Cloud Sleuth without the Zipkin integration just add +the spring-cloud-starter-sleuth module to your project.

+
+
+
Maven
+
+
<dependencyManagement> (1)
+         <dependencies>
+             <dependency>
+                 <groupId>org.springframework.cloud</groupId>
+                 <artifactId>spring-cloud-dependencies</artifactId>
+                 <version>Brixton.RELEASE</version>
+                 <type>pom</type>
+                 <scope>import</scope>
+             </dependency>
+         </dependencies>
+   </dependencyManagement>
+
+   <dependency> (2)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-starter-sleuth</artifactId>
+   </dependency>
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-starter-sleuth

    +
    3. +
+
+
+
Gradle
+
+
dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies { (2)
+    compile "org.springframework.cloud:spring-cloud-starter-sleuth"
+}
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-starter-sleuth

    +
    3. +
+
+
+
+

Sleuth with Zipkin via HTTP

+
+

If you want both Sleuth and Zipkin just add the spring-cloud-starter-zipkin dependency.

+
+
+
Maven
+
+
<dependencyManagement> (1)
+         <dependencies>
+             <dependency>
+                 <groupId>org.springframework.cloud</groupId>
+                 <artifactId>spring-cloud-dependencies</artifactId>
+                 <version>Brixton.RELEASE</version>
+                 <type>pom</type>
+                 <scope>import</scope>
+             </dependency>
+         </dependencies>
+   </dependencyManagement>
+
+   <dependency> (2)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-starter-zipkin</artifactId>
+   </dependency>
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-starter-zipkin

    +
    3. +
+
+
+
Gradle
+
+
dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies { (2)
+    compile "org.springframework.cloud:spring-cloud-starter-zipkin"
+}
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-starter-zipkin

    +
    3. +
+
+
+
+

Sleuth with Zipkin via Spring Cloud Stream

+
+

If you want both Sleuth and Zipkin just add the spring-cloud-sleuth-stream dependency.

+
+
+
Maven
+
+
<dependencyManagement> (1)
+         <dependencies>
+             <dependency>
+                 <groupId>org.springframework.cloud</groupId>
+                 <artifactId>spring-cloud-dependencies</artifactId>
+                 <version>Brixton.RELEASE</version>
+                 <type>pom</type>
+                 <scope>import</scope>
+             </dependency>
+         </dependencies>
+   </dependencyManagement>
+
+   <dependency> (2)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-sleuth-stream</artifactId>
+   </dependency>
+   <dependency> (3)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-starter-sleuth</artifactId>
+   </dependency>
+   <!-- EXAMPLE FOR RABBIT BINDING -->
+   <dependency> (4)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-stream-binder-rabbit</artifactId>
+   </dependency>
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-sleuth-stream

    +
    3. +
  3. +

    Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

    +
    4. +
  4. +

    Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

    +
    5. +
+
+
+
Gradle
+
+
dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies {
+    compile "org.springframework.cloud:spring-cloud-sleuth-stream" (2)
+    compile "org.springframework.cloud:spring-cloud-starter-sleuth" (3)
+    // Example for Rabbit binding
+    compile "org.springframework.cloud:spring-cloud-stream-binder-rabbit" (4)
+}
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-sleuth-stream

    +
    3. +
  3. +

    Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

    +
    4. +
  4. +

    Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

    +
    5. +
+
+
+
+

Spring Cloud Sleuth Stream Zipkin Collector

+
+

If you want to start a Spring Cloud Sleuth Stream Zipkin collector just add the spring-cloud-sleuth-zipkin-stream +dependency

+
+
+
Maven
+
+
<dependencyManagement> (1)
+         <dependencies>
+             <dependency>
+                 <groupId>org.springframework.cloud</groupId>
+                 <artifactId>spring-cloud-dependencies</artifactId>
+                 <version>Brixton.RELEASE</version>
+                 <type>pom</type>
+                 <scope>import</scope>
+             </dependency>
+         </dependencies>
+   </dependencyManagement>
+
+   <dependency> (2)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-sleuth-zipkin-stream</artifactId>
+   </dependency>
+   <dependency> (3)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-starter-sleuth</artifactId>
+   </dependency>
+   <!-- EXAMPLE FOR RABBIT BINDING -->
+   <dependency> (4)
+       <groupId>org.springframework.cloud</groupId>
+       <artifactId>spring-cloud-stream-binder-rabbit</artifactId>
+   </dependency>
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-sleuth-zipkin-stream

    +
    3. +
  3. +

    Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

    +
    4. +
  4. +

    Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

    +
    5. +
+
+
+
Gradle
+
+
dependencyManagement { (1)
+    imports {
+        mavenBom "org.springframework.cloud:spring-cloud-dependencies:Brixton.RELEASE"
+    }
+}
+
+dependencies {
+    compile "org.springframework.cloud:spring-cloud-sleuth-zipkin-stream" (2)
+    compile "org.springframework.cloud:spring-cloud-starter-sleuth" (3)
+    // Example for Rabbit binding
+    compile "org.springframework.cloud:spring-cloud-stream-binder-rabbit" (4)
+}
+
+
+
+
    +
  1. +

    In order not to pick versions by yourself it’s much better if you add the dependency management via +the Spring BOM

    +
    2. +
  2. +

    Add the dependency to spring-cloud-sleuth-zipkin-stream

    +
    3. +
  3. +

    Add the dependency to spring-cloud-starter-sleuth - that way all dependant dependencies will be downloaded

    +
    4. +
  4. +

    Add a binder (e.g. Rabbit binder) to tell Spring Cloud Stream what it should bind to

    +
    5. +
+
+
+

and then just annotate your main class with @EnableZipkinStreamServer annotation:

+
+
+
+
package example;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.cloud.sleuth.zipkin.stream.EnableZipkinStreamServer;
+
+@SpringBootApplication
+@EnableZipkinStreamServer
+public class ZipkinStreamServerApplication {
+
+	public static void main(String[] args) throws Exception {
+		SpringApplication.run(ZipkinStreamServerApplication.class, args);
+	}
+
+}
+
+
+
+
+
+

Features

+
+
+
    +
  • +

    Adds trace and span ids to the Slf4J MDC, so you can extract all the logs from a given trace or span in a log aggregator. Example logs:

    +
    +
    +
    2016-02-02 15:30:57.902  INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
+2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b,false] 23030 --- [nio-8081-exec-3] ...
+2016-02-02 15:31:01.936  INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9,false] 23030 --- [nio-8081-exec-4] ...
    +
    +
    +
    +

    notice the [appname,traceId,spanId,exportable] entries from the MDC:

    +
    +
    +
      +
    • +

      spanId - the id of a specific operation that took place

      +
      • +
    • +

      appname - the name of the application that logged the span

      +
      • +
    • +

      traceId - the id of the latency graph that contains the span

      +
      • +
    • +

      exportable - whether the log should be exported to Zipkin or not. When would you like the span not to be +exportable? In the case in which you want to wrap some operation in a Span and have it written to the logs +only.

      +
      • +
    +
    +
    • +
  • +

    Provides an abstraction over common distributed tracing data models: traces, spans (forming a DAG), annotations, +key-value annotations. Loosely based on HTrace, but Zipkin (Dapper) compatible.

    +
    • +
  • +

    Sleuth records timing information to aid in latency analysis. Using sleuth, you can pinpoint causes of +latency in your applications. Sleuth is written to not log too much, and to not cause your production application to crash.

    +
    +
      +
    • +

      propagates structural data about your call-graph in-band, and the rest out-of-band.

      +
      • +
    • +

      includes opinionated instrumentation of layers such as HTTP

      +
      • +
    • +

      includes sampling policy to manage volume

      +
      • +
    • +

      can report to a Zipkin system for query and visualization

      +
      • +
    +
    +
    • +
  • +

    Instruments common ingress and egress points from Spring applications (servlet filter, async endpoints, +rest template, scheduled actions, message channels, zuul filters, feign client).

    +
    • +
  • +

    Sleuth includes default logic to join a trace across http or messaging boundaries. For example, http propagation +works via Zipkin-compatible request headers. This propagation logic is defined and customized via +SpanInjector and SpanExtractor implementations.

    +
    • +
  • +

    Provides simple metrics of accepted / dropped spans.

    +
    • +
  • +

    If spring-cloud-sleuth-zipkin then the app will generate and collect Zipkin-compatible traces. +By default it sends them via HTTP to a Zipkin server on localhost (port 9411). +Configure the location of the service using spring.zipkin.baseUrl.

    +
    • +
  • +

    If spring-cloud-sleuth-stream then the app will generate and collect traces via Spring Cloud Stream. +Your app automatically becomes a producer of tracer messages that are sent over your broker of choice +(e.g. RabbitMQ, Apache Kafka, Redis).

    +
    • +
+
+
+ + + + + +
+
Important
+		 +If using Zipkin or Stream, configure the percentage of spans exported using spring.sleuth.sampler.percentage +(default 0.1, i.e. 10%). Otherwise you might think that Sleuth is not working cause it’s omitting some spans. +
+
+
+ + + + + +
+
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} + (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. +
+
+
+
+
+

Sampling

+
+
+

In distributed tracing the data volumes can be very high so sampling +can be important (you usually don’t need to export all spans to get a +good picture of what is happening). Spring Cloud Sleuth has a +Sampler strategy that you can implement to take control of the +sampling algorithm. Samplers do not stop span (correlation) ids from +being generated, but they do prevent the tags and events being +attached and exported. By default you get a strategy that continues to +trace if a span is already active, but new ones are always marked as +non-exportable. If all your apps run with this sampler you will see +traces in logs, but not in any remote store. For testing the default +is often enough, and it probably is all you need if you are only using +the logs (e.g. with an ELK aggregator). If you are exporting span data +to Zipkin or Spring Cloud Stream, there is also an AlwaysSampler +that exports everything and a PercentageBasedSampler that samples a +fixed fraction of spans.

+
+
+ + + + + +
+
Note
+		 +the PercentageBasedSampler is the default if you are using +spring-cloud-sleuth-zipkin or spring-cloud-sleuth-stream. You can +configure the exports using spring.sleuth.sampler.percentage. +
+
+
+

A sampler can be installed just by creating a bean definition, e.g:

+
+
+
+
@Bean
+public Sampler defaultSampler() {
+	return new AlwaysSampler();
+}
+
+
+
+
+
+

Instrumentation

+
+
+

Spring Cloud Sleuth instruments all your Spring application +automatically, so you shouldn’t have to do anything to activate +it. The instrumentation is added using a variety of technologies +according to the stack that is available, e.g. for a servlet web +application we use a Filter, and for Spring Integration we use +ChannelInterceptors.

+
+
+

You can customize the keys used in span tags. To limit the volume of +span data, by default an HTTP request will be tagged only with a +handful of metadata like the status code, host and URL. You can add +request headers by configuring spring.sleuth.keys.http.headers (a +list of header names).

+
+
+ + + + + +
+
Note
+		 +Remember that tags are only collected and exported if there is a +Sampler that allows it (by default there is not, so there is no +danger of accidentally collecting too much data without configuring +something). +
+
+
+ + + + + +
+
Note
+		 +Currently the instrumentation in Spring Cloud Sleuth is eager - it means that +we’re actively trying to pass the tracing context between threads. Also timing events +are captured even when sleuth isn’t exporting data to a tracing system. +This approach may change in the future towards being lazy on this matter. +
+
+
+
+
+

Span lifecycle

+
+
+

You can do the following operations on the Span by means of org.springframework.cloud.sleuth.Tracer interface:

+
+
+
    +
  • +

    start - when you start a span its name is assigned and start timestamp is recorded.

    +
    • +
  • +

    close - the span gets finished (the end time of the span is recorded) and if +the span is exportable then it will be eligible for collection to Zipkin. +The span is also removed from the current thread.

    +
    • +
  • +

    continue - a new instance of span will be created whereas it will be a copy of the +one that it continues.

    +
    • +
  • +

    detach - the span doesn’t get stopped or closed. It only gets removed from the current thread.

    +
    • +
  • +

    create with explicit parent - you can create a new span and set an explicit parent to it

    +
    • +
+
+
+ + + + + +
+
Tip
+		 +Spring creates the instance of Tracer for you. In order to use it all you need is to just autowire it. +
+
+
+

Creating and closing spans

+
+

You can manually create spans by using the Tracer interface.

+
+
+
+
// Start a span. If there was a span present in this thread it will become
+// the `newSpan`'s parent.
+Span newSpan = this.tracer.createSpan("calculateTax");
+try {
+	// ...
+	// You can tag a span
+	this.tracer.addTag("taxValue", taxValue);
+	// ...
+	// You can log an event on a span
+	newSpan.logEvent("taxCalculated");
+} finally {
+	// Once done remember to close the span. This will allow collecting
+	// the span to send it to Zipkin
+	this.tracer.close(newSpan);
+}
+
+
+
+

In this example we could see how to create a new instance of span. Assuming that there already +was a span present in this thread then it would become the parent of that span.

+
+
+ + + + + +
+
Important
+		 +Always clean after you create a span! Don’t forget to close a span if you want to send it to Zipkin. +
+
+
+
+

Continuing spans

+
+

Sometimes you don’t want to create a new span but you want to continue one. Example of such a +situation might be (of course it all depends on the use-case):

+
+
+
    +
  • +

    AOP - If there was already a span created before an aspect was reached then you might not want to create a new span.

    +
    • +
  • +

    Hystrix - executing a Hystrix command is most likely a logical part of the current processing. It’s in fact +only a technical implementation detail that you wouldn’t necessarily want to reflect in tracing as a separate being.

    +
    • +
+
+
+

The continued instance of span is equal to the one that it continues:

+
+
+
+
Span continuedSpan = this.tracer.continueSpan(spanToContinue);
+assertThat(continuedSpan).isEqualTo(spanToContinue);
+
+
+
+

To continue a span you can use the Tracer interface.

+
+
+
+
// let's assume that we're in a thread Y and we've received
+// the `initialSpan` from thread X
+Span continuedSpan = this.tracer.continueSpan(initialSpan);
+try {
+	// ...
+	// You can tag a span
+	this.tracer.addTag("taxValue", taxValue);
+	// ...
+	// You can log an event on a span
+	continuedSpan.logEvent("taxCalculated");
+} finally {
+	// Once done remember to detach the span. That way you'll
+	// safely remove it from the current thread without closing it
+	this.tracer.detach(continuedSpan);
+}
+
+
+
+ + + + + +
+
Important
+		 +Always clean after you create a span! Don’t forget to detach a span if some work was done started in one + thread (e.g. thread X) and it’s waiting for other threads (e.g. Y, Z) to finish. + Then the spans in the threads Y, Z should be detached at the end of their work. When the results are collected + the span in thread X should be closed. +
+
+
+
+

Creating spans with an explicit parent

+
+

There is a possibility that you want to start a new span and provide an explicit parent of that span. +Let’s assume that the parent of a span is in one thread and you want to start a new span in another thread. The +startSpan method of the Tracer interface is the method you are looking for.

+
+
+
+
// let's assume that we're in a thread Y and we've received
+// the `initialSpan` from thread X. `initialSpan` will be the parent
+// of the `newSpan`
+Span newSpan = this.tracer.createSpan("calculateCommission", initialSpan);
+try {
+	// ...
+	// You can tag a span
+	this.tracer.addTag("commissionValue", commissionValue);
+	// ...
+	// You can log an event on a span
+	newSpan.logEvent("commissionCalculated");
+} finally {
+	// Once done remember to close the span. This will allow collecting
+	// the span to send it to Zipkin. The tags and events set on the
+	// newSpan will not be present on the parent
+	this.tracer.close(newSpan);
+}
+
+
+
+ + + + + +
+
Important
+		 +After having created such a span remember to close it. Otherwise you will see a lot of warnings in your logs + related to the fact that you have a span present in the current thread other than the one you’re trying to close. + What’s worse your spans won’t get closed properly thus will not get collected to Zipkin. +
+
+
+
+
+
+

Naming spans

+
+
+

Picking a span name is not a trivial task. Span name should depict an operation name. The name should +be low cardinality (e.g. not include identifiers).

+
+
+

Since there is a lot of instrumentation going on some of the span names will be +artificial like:

+
+
+
    +
  • +

    controller-method-name when received by a Controller with a method name conrollerMethodName

    +
    • +
  • +

    async for asynchronous operations done via wrapped Callable and Runnable.

    +
    • +
  • +

    @Scheduled annotated methods will return the simple name of the class.

    +
    • +
+
+
+

Fortunately, for the asynchronous processing you can provide explicit naming.

+
+
+

@SpanName annotation

+
+

You can do name the span explicitly via the @SpanName annotation.

+
+
+
+
@SpanName("calculateTax")
+class TaxCountingRunnable implements Runnable {
+
+	@Override public void run() {
+		// perform logic
+	}
+}
+
+
+
+

In this case, when processed in the following manner:

+
+
+
+
Runnable runnable = new TraceRunnable(tracer, spanNamer, new TaxCountingRunnable());
+Future<?> future = executorService.submit(runnable);
+// ... some additional logic ...
+future.get();
+
+
+
+

The span will be named calculateTax.

+
+
+
+

toString() method

+
+

It’s pretty rare to create separate classes for Runnable or Callable. Typically one creates an anonymous +instance of those classes. You can’t annotate such classes thus to override that, if there is no @SpanName annotation present, +we’re checking if the class has a custom implementation of the toString() method.

+
+
+

So executing such code:

+
+
+
+
Runnable runnable = new TraceRunnable(tracer, spanNamer, new Runnable() {
+	@Override public void run() {
+		// perform logic
+	}
+
+	@Override public String toString() {
+		return "calculateTax";
+	}
+});
+Future<?> future = executorService.submit(runnable);
+// ... some additional logic ...
+future.get();
+
+
+
+

will lead in creating a span named calculateTax.

+
+
+
+
+
+

Customizations

+
+
+

Thanks to the SpanInjector and SpanExtractor you can customize the way spans +are created and propagated.

+
+
+

There are currently two built-in ways to pass tracing information between processes:

+
+
+
    +
  • +

    via Spring Integration

    +
    • +
  • +

    via HTTP

    +
    • +
+
+
+

Span ids are extracted from Zipkin-compatible (B3) headers (either Message +or HTTP headers), to start or join an existing trace. Trace information is +injected into any outbound requests so the next hop can extract them.

+
+
+

Spring Integration

+
+

For Spring Integration these are the beans responsible for creation of a Span from a Message + and filling in the MessageBuilder with tracing information.

+
+
+
+
@Bean
+public SpanExtractor<Message> messagingSpanExtractor() {
+    ...
+}
+
+@Bean
+public SpanInjector<MessageBuilder> messagingSpanInjector() {
+    ...
+}
+
+
+
+

You can override them by providing your own implementation and by adding a @Primary annotation +to your bean definition.

+
+
+
+

HTTP

+
+

For HTTP these are the beans responsible for creation of a Span from a HttpServletRequest + and filling in the HttpServletResponse with tracing information.

+
+
+
+
@Bean
+public SpanExtractor<HttpServletRequest> httpServletRequestSpanExtractor() {
+    ...
+}
+
+@Bean
+public SpanInjector<HttpServletResponse> httpServletResponseSpanInjector() {
+    ...
+}
+
+
+
+

You can override them by providing your own implementation and by adding a @Primary annotation +to your bean definition.

+
+
+
+

Example

+
+

Let’s assume that instead of the standard Zipkin compatible tracing HTTP header names +you have

+
+
+
    +
  • +

    for trace id - correlationId

    +
    • +
  • +

    for span id - mySpanId

    +
    • +
+
+
+

This is a an example of a SpanExtractor

+
+
+
+
static class CustomHttpServletRequestSpanExtractor
+		implements SpanExtractor<HttpServletRequest> {
+
+	@Override
+	public Span joinTrace(HttpServletRequest carrier) {
+		long traceId = Span.hexToId(carrier.getHeader("correlationId"));
+		long spanId = Span.hexToId(carrier.getHeader("mySpanId"));
+		// extract all necessary headers
+		Span.SpanBuilder builder = Span.builder().traceId(traceId).spanId(spanId);
+		// build rest of the Span
+		return builder.build();
+	}
+}
+
+
+
+

The following SpanInjector could be created

+
+
+
+
static class CustomHttpServletResponseSpanInjector
+		implements SpanInjector<HttpServletResponse> {
+
+	@Override
+	public void inject(Span span, HttpServletResponse carrier) {
+		carrier.addHeader("correlationId", Span.idToHex(span.getTraceId()));
+		carrier.addHeader("mySpanId", Span.idToHex(span.getSpanId()));
+		// inject the rest of Span values to the header
+	}
+}
+
+
+
+

And you could register them like this:

+
+
+
+
@Bean
+@Primary
+SpanExtractor<HttpServletRequest> customHttpServletRequestSpanExtractor() {
+	return new CustomHttpServletRequestSpanExtractor();
+}
+
+@Bean
+@Primary
+SpanInjector<HttpServletResponse> customHttpServletResponseSpanInjector() {
+	return new CustomHttpServletResponseSpanInjector();
+}
+
+
+
+
+

Custom SA tag in Zipkin

+
+

Sometimes you want to create a manual Span that will wrap a call to an external service which is not instrumented. +What you can do is to create a span with the peer.service tag that will contain a value of the service that you want to call. +Below you can see an example of a call to Redis that is wrapped in such a span.

+
+
+
+
org.springframework.cloud.sleuth.Span newSpan = tracer.createSpan("redis");
+try {
+	newSpan.tag("redis.op", "get");
+	newSpan.tag("lc", "redis");
+	newSpan.logEvent(org.springframework.cloud.sleuth.Span.CLIENT_SEND);
+	// call redis service e.g
+	// return (SomeObj) redisTemplate.opsForHash().get("MYHASH", someObjKey);
+} finally {
+	newSpan.tag("peer.service", "redisService");
+	newSpan.tag("peer.ipv4", "1.2.3.4");
+	newSpan.tag("peer.port", "1234");
+	newSpan.logEvent(org.springframework.cloud.sleuth.Span.CLIENT_RECV);
+	tracer.close(newSpan);
+}
+
+
+
+ + + + + +
+
Important
+		 +Remember not to add both peer.service tag and the SA tag! You have to add only peer.service. +
+
+
+
+
+
+

Span Data as Messages

+
+
+

You can accumulate and send span data over +Spring Cloud Stream by +including the spring-cloud-sleuth-stream jar as a dependency, and +adding a Channel Binder implementation +(e.g. spring-cloud-starter-stream-rabbit for RabbitMQ or +spring-cloud-starter-stream-kafka for Kafka). This will +automatically turn your app into a producer of messages with payload +type Spans.

+
+
+

Zipkin Consumer

+
+

There is a special convenience annotation for setting up a message consumer +for the Span data and pushing it into a Zipkin SpanStore. This application

+
+
+
+
@SpringBootApplication
+@EnableZipkinStreamServer
+public class Consumer {
+	public static void main(String[] args) {
+		SpringApplication.run(Consumer.class, args);
+	}
+}
+
+
+
+

will listen for the Span data on whatever transport you provide via a +Spring Cloud Stream Binder (e.g. include +spring-cloud-starter-stream-rabbit for RabbitMQ, and similar +starters exist for Redis and Kafka). If you add the following UI dependency

+
+
+
+
<groupId>io.zipkin.java</groupId>
+<artifactId>zipkin-autoconfigure-ui</artifactId>
+
+
+
+

Then you’ll have your app a +Zipkin server, which hosts +the UI and api on port 9411.

+
+
+

The default SpanStore is in-memory (good for demos and getting +started quickly). For a more robust solution you can add MySQL and +spring-boot-starter-jdbc to your classpath and enable the JDBC +SpanStore via configuration, e.g.:

+
+
+
+
spring:
+  rabbitmq:
+    host: ${RABBIT_HOST:localhost}
+  datasource:
+    schema: classpath:/mysql.sql
+    url: jdbc:mysql://${MYSQL_HOST:localhost}/test
+    username: root
+    password: root
+# Switch this on to create the schema on startup:
+    initialize: true
+    continueOnError: true
+  sleuth:
+    enabled: false
+zipkin:
+  storage:
+    type: mysql
+
+
+
+ + + + + +
+
Note
+		 +The @EnableZipkinStreamServer is also annotated with +@EnableZipkinServer so the process will also expose the standard +Zipkin server endpoints for collecting spans over HTTP, and for +querying in the Zipkin Web UI. +
+
+
+
+

Custom Consumer

+
+

A custom consumer can also easily be implemented using +spring-cloud-sleuth-stream and binding to the SleuthSink. Example:

+
+
+
+
@EnableBinding(SleuthSink.class)
+@SpringBootApplication(exclude = SleuthStreamAutoConfiguration.class)
+@MessageEndpoint
+public class Consumer {
+
+    @ServiceActivator(inputChannel = SleuthSink.INPUT)
+    public void sink(Spans input) throws Exception {
+        // ... process spans
+    }
+}
+
+
+
+ + + + + +
+
Note
+		 +the sample consumer application above explicitly excludes +SleuthStreamAutoConfiguration so it doesn’t send messages to itself, +but this is optional (you might actually want to trace requests into +the consumer app). +
+
+
+
+
+
+

Metrics

+
+
+

Currently Spring Cloud Sleuth registers very simple metrics related to spans. +It’s using the Spring Boot’s metrics support +to calculate the number of accepted and dropped spans. Each time a span gets +sent to Zipkin the number of accepted spans will increase. If there’s an error then +the number of dropped spans will get increased.

+
+
+
+
+

Integrations

+
+
+

Runnable and Callable

+
+

If you’re wrapping your logic in Runnable or Callable it’s enough to wrap those classes in their Sleuth representative.

+
+
+

Example for Runnable:

+
+
+
+
Runnable runnable = new Runnable() {
+	@Override
+	public void run() {
+		// do some work
+	}
+
+	@Override
+	public String toString() {
+		return "spanNameFromToStringMethod";
+	}
+};
+// Manual `TraceRunnable` creation with explicit "calculateTax" Span name
+Runnable traceRunnable = new TraceRunnable(tracer, spanNamer, runnable, "calculateTax");
+// Wrapping `Runnable` with `Tracer`. The Span name will be taken either from the
+// `@SpanName` annotation or from `toString` method
+Runnable traceRunnableFromTracer = tracer.wrap(runnable);
+
+
+
+

Example for Callable:

+
+
+
+
Callable<String> callable = new Callable<String>() {
+	@Override
+	public String call() throws Exception {
+		return someLogic();
+	}
+
+	@Override
+	public String toString() {
+		return "spanNameFromToStringMethod";
+	}
+};
+// Manual `TraceCallable` creation with explicit "calculateTax" Span name
+Callable<String> traceCallable = new TraceCallable<>(tracer, spanNamer, callable, "calculateTax");
+// Wrapping `Callable` with `Tracer`. The Span name will be taken either from the
+// `@SpanName` annotation or from `toString` method
+Callable<String> traceCallableFromTracer = tracer.wrap(callable);
+
+
+
+

That way you will ensure that a new Span is created and closed for each execution.

+
+
+
+

Hystrix

+
+

Custom Concurrency Strategy

+
+

We’re registering a custom HystrixConcurrencyStrategy +that wraps all Callable instances into their Sleuth representative - +the TraceCallable. The strategy either starts or continues a span depending on the fact whether tracing was already going +on before the Hystrix command was called. To disable the custom Hystrix Concurrency Strategy set the spring.sleuth.hystrix.strategy.enabled to false.

+
+
+
+

Manual Command setting

+
+

Assuming that you have the following HystrixCommand:

+
+
+
+
HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) {
+	@Override
+	protected String run() throws Exception {
+		return someLogic();
+	}
+};
+
+
+
+

In order to pass the tracing information you have to wrap the same logic in the Sleuth version of the HystrixCommand which is the +TraceCommand:

+
+
+
+
TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, traceKeys, setter) {
+	@Override
+	public String doRun() throws Exception {
+		return someLogic();
+	}
+};
+
+
+
+
+
+

RxJava

+
+

We’re registering a custom RxJavaSchedulersHook +that wraps all Action0 instances into their Sleuth representative - +the TraceAction. The hook either starts or continues a span depending on the fact whether tracing was already going +on before the Action was scheduled. To disable the custom RxJavaSchedulersHook set the spring.sleuth.rxjava.schedulers.hook.enabled to false.

+
+
+

You can define a list of regular expressions for thread names, for which you don’t want a Span to be created. Just provide a comma separated list +of regular expressions in the spring.sleuth.rxjava.schedulers.ignoredthreads property.

+
+
+
+

HTTP integration

+
+

Features from this section can be disabled by providing the spring.sleuth.web.enabled property with value equal to false.

+
+
+

HTTP Filter

+
+

Via the TraceFilter all sampled incoming requests result in creation of a Span. That Span’s name is http: + the path to which + the request was sent. E.g. if the request was sent to /foo/bar then the name will be http:/foo/bar. You can configure which URIs you would + like to skip via the spring.sleuth.web.skipPattern property. If you have ManagementServerProperties on classpath then + its value of contextPath gets appended to the provided skip pattern.

+
+
+
+

HandlerInterceptor

+
+

Since we want the span names to be precise we’re using a TraceHandlerInterceptor that either wraps an + existing HandlerInterceptor or is added directly to the list of existing HandlerInterceptors. The + TraceHandlerInterceptor adds a special request attribute to the given HttpServletRequest. If the + the TraceFilter doesn’t see this attribute set it will create a "fallback" span which is an additional + span created on the server side so that the trace is presented properly in the UI. Seeing that most likely + signifies that there is a missing instrumentation. In that case please file an issue in Spring Cloud Sleuth.

+
+
+
+

Async Servlet support

+
+

If your controller returns a Callable or a WebAsyncTask Spring Cloud Sleuth will continue the existing span instead of creating a new one.

+
+
+
+
+

HTTP client integration

+
+

Synchronous Rest Template

+
+

We’re injecting a RestTemplate interceptor that ensures that all the tracing information is passed to the requests. Each time a +call is made a new Span is created. It gets closed upon receiving the response. In order to block the synchronous RestTemplate features +just set spring.sleuth.web.client.enabled to false.

+
+
+ + + + + +
+
Important
+		 +You have to register RestTemplate as a bean so that the interceptors will get injected. +If you create a RestTemplate instance with a new keyword then the instrumentation WILL NOT work. +
+
+
+
+

Asynchronous Rest Template

+
+

Custom instrumentation is set to create and close Spans upon sending and receiving requests. You can customize the ClientHttpRequestFactory +and the AsyncClientHttpRequestFactory by registering your beans. Remember to use tracing compatible implementations (e.g. don’t forget to +wrap ThreadPoolTaskScheduler in a TraceAsyncListenableTaskExecutor). Example of custom request factories:

+
+
+
+
@EnableAutoConfiguration
+@Configuration
+public static class TestConfiguration {
+
+	@Bean
+	ClientHttpRequestFactory mySyncClientFactory() {
+		return new MySyncClientHttpRequestFactory();
+	}
+
+	@Bean
+	AsyncClientHttpRequestFactory myAsyncClientFactory() {
+		return new MyAsyncClientHttpRequestFactory();
+	}
+}
+
+
+
+

To block the AsyncRestTemplate features set spring.sleuth.web.async.client.enabled to false. +To disable creation of the default TraceAsyncClientHttpRequestFactoryWrapper set spring.sleuth.web.async.client.factory.enabled +to false. If you don’t want to create AsyncRestClient at all set spring.sleuth.web.async.client.template.enabled to false.

+
+
+
+
+

Feign

+
+

By default Spring Cloud Sleuth provides integration with feign via the TraceFeignClientAutoConfiguration. You can disable it entirely +by setting spring.sleuth.feign.enabled to false. If you do so then no Feign related instrumentation will take place.

+
+
+

Part of Feign instrumentation is done via a FeignBeanPostProcessor. You can disable it by providing the spring.sleuth.feign.processor.enabled equal to false. +If you set it like this then Spring Cloud Sleuth will not instrument any of your custom Feign components. All the default instrumentation +however will be still there.

+
+
+
+

Asynchronous communication

+
+

@Async annotated methods

+
+

In Spring Cloud Sleuth we’re instrumenting async related components so that the tracing information is passed between threads. +You can disable this behaviour by setting the value of spring.sleuth.async.enabled to false.

+
+
+

If you annotate your method with @Async then we’ll automatically create a new Span with the following characteristics:

+
+
+
    +
  • +

    the Span name will be the annotated method name

    +
    • +
  • +

    the Span will be tagged with that method’s class name and the method name too

    +
    • +
+
+
+
+

@Scheduled annotated methods

+
+

In Spring Cloud Sleuth we’re instrumenting scheduled method execution so that the tracing information is passed between threads. You can disable this behaviour +by setting the value of spring.sleuth.scheduled.enabled to false.

+
+
+

If you annotate your method with @Scheduled then we’ll automatically create a new Span with the following characteristics:

+
+
+
    +
  • +

    the Span name will be the annotated method name

    +
    • +
  • +

    the Span will be tagged with that method’s class name and the method name too

    +
    • +
+
+
+

If you want to skip Span creation for some @Scheduled annotated classes you can set the +spring.sleuth.scheduled.skipPattern with a regular expression that will match the fully qualified name of the +@Scheduled annotated class.

+
+
+
+

Executor, ExecutorService and ScheduledExecutorService

+
+

We’re providing LazyTraceExecutor, TraceableExecutorService and TraceableScheduledExecutorService. Those implementations +are creating Spans each time a new task is submitted, invoked or scheduled.

+
+
+

Here you can see an example of how to pass tracing information with TraceableExecutorService when working with CompletableFuture:

+
+
+
+
CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
+	// perform some logic
+	return 1_000_000L;
+}, new TraceableExecutorService(executorService,
+		// 'calculateTax' explicitly names the span - this param is optional
+		tracer, traceKeys, spanNamer, "calculateTax"));
+
+
+
+
+
+

Messaging

+
+

Spring Cloud Sleuth integrates with Spring Integration. It creates spans for publish and +subscribe events. To disable Spring Integration instrumentation, set spring.sleuth.integration.enabled to false.

+
+
+

Spring Cloud Sleuth up till version 1.0.4 is sending invalid tracing headers when using messaging. Those headers are actually +the same as the ones sent in HTTP (they contain a -) in its name. For the sake of +backwards compatibility in 1.0.4 we’ve started sending both valid and invalid headers. Please upgrade to 1.0.4 because +in Spring Cloud Sleuth 1.1 we will remove the support for the deprecated headers.

+
+
+

Since 1.0.4 you can provide the spring.sleuth.integration.patterns pattern to explicitly +provide the names of channels that you want to include for tracing. By default all channels +are included.

+
+
+
+

Zuul

+
+

We’re registering Zuul filters to propagate the tracing information (the request header is enriched with tracing data). +To disable Zuul support set the spring.sleuth.zuul.enabled property to false.

+
+
+
+
+
+

Running examples

+
+
+

You can find the running examples deployed in the Pivotal Web Services. Check them out in the following links:

+
+
+ +
+
+
+
+ + \ No newline at end of file