From 89298ad6006ad4113d16b6737f17fc704d92058b Mon Sep 17 00:00:00 2001 From: Adrian Cole Date: Mon, 6 Apr 2020 16:39:16 +0800 Subject: [PATCH] Adds more robust introduction (#1603) --- .../main/asciidoc/spring-cloud-sleuth.adoc | 33 +++++++++++++++---- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/docs/src/main/asciidoc/spring-cloud-sleuth.adoc b/docs/src/main/asciidoc/spring-cloud-sleuth.adoc index 1517e2a5e..51d252c1f 100644 --- a/docs/src/main/asciidoc/spring-cloud-sleuth.adoc +++ b/docs/src/main/asciidoc/spring-cloud-sleuth.adoc @@ -12,20 +12,39 @@ include::intro.adoc[] include::features.adoc[] -== Introduction to Brave +== Introduction + +Spring Cloud Sleuth is a layer over https://github.com/openzipkin/brave[Brave]. Brave is a distributed tracing instrumentation library. Brave typically intercepts production requests to gather timing data, correlate and propagate -trace contexts. While typically trace data is sent to Zipkin server, -third-party plugins are available to send to alternate services such as Amazon -X-Ray. +trace contexts. -Spring Cloud Sleuth is a layer over https://github.com/openzipkin/brave[Brave]. -It configures everything you need to get started with tracing. Sleuth +Trace data, also called spans, are typically reported to https://zipkin.io[Zipkin]. +Zipkin is an Open Source tracing system, which includes a UI and various +collectors, such as HTTP and messaging. + +Many Open Source and commercial products accept https://zipkin.io/zipkin-api/#/default/post_spans[Zipkin format]. +Some options are documented https://zipkin.io/pages/extensions_choices.html[here], +but many are not. If you cannot use Zipkin and your product isn't listed, clarify +with your support representative and have them update that page. In many cases, +products already support Zipkin format, they just don't document it. + +Traces connect from service to service using header propagation. The default +format is https://github.com/openzipkin/b3-propagation[B3]. Similar to data +formats, you can configure alternate header formats also, provided trace and +span IDs are compatible with B3. Most notably, this means the trace ID and span +IDs are lower-case hex, not UUIDs. Besides trace identifiers, other properties +(Baggage) can also be passed along with the request. Remote Baggage must be +predefined, but is flexible otherwise. + +Sleuth configures everything you need to get started with tracing. Sleuth configures where trace data (spans) are reported to, how many traces to keep (sampling), if remote fields (baggage) and which libraries are traced. Sleuth also adds annotation based tracing features and some instrumentation not -available otherwise, such as Reactor. +available otherwise, such as Reactor. If cannot find the configuration you are +looking for in the documentation, ask https://gitter.im/spring-cloud/spring-cloud-sleuth[Gitter] +before assuming something cannot be done. === Brave Basics