摘要：介紹從版本開始，使用作為追蹤庫，為方便起見，在此處嵌入了的部分文檔。具有一個上下文，其中包含標識符，該標識符將放置在表示分布式操作的樹中的正確位置。追蹤通常由攔截器自動完成，在幕后，他們添加與他們在操作中的角色相關的標簽和事件。

將trace和span ID添加到Slf4J MDC，因此你可以在日志聚合器中從給定的trace或span提取所有日志，如以下示例日志中所示：

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] ...

請注意MDC中的[appname,traceId,spanId,exportable]條目：

spanId：發生的特定操作的ID。

appname：記錄span的應用程序的名稱。

traceId：包含span的延遲圖的ID。

exportable：是否應將日志導出到Zipkin，你希望什么時候span不能導出？如果要在Span中包裝某些操作并將其寫入日志中。

提供對常見分布式追蹤數據模型的抽象：trace、span（形成DAG）、annotation和鍵值annotation，Spring Cloud Sleuth基于HTrace，但與Zipkin（Dapper）兼容。

Sleuth記錄時間信息以幫助進行延遲分析，通過使用sleuth，你可以查明應用程序中的延遲原因。

Sleuth不進行過多的日志記錄，并且不會導致生產應用程序崩潰，為此，Sleuth：

在帶內傳播有關你的調用圖的結構數據，在帶外休息。

包括層的自定義插裝，比如HTTP。

包括用于管理卷的采樣策略。

可以向Zipkin系統報告用于查詢和可視化。

儀器從Spring應用程序中常見的入口和出口點（servlet過濾器、異步端點、rest模板，調度操作，消息通道，Zuul過濾器和Feign客戶端）。

Sleuth包含默認邏輯，用于跨HTTP或消息傳遞邊界連接trace，例如，HTTP傳播適用于與Zipkin兼容的請求headers。

Sleuth可以在進程之間傳播上下文（也稱為baggage），因此，如果你在Span上設置baggage元素，則會通過HTTP或消息傳遞向下發送到其他進程。

提供創建或繼續span以及通過annotations添加標記和日志的方法。

如果spring-cloud-sleuth-zipkin位于類路徑上，則應用程序會生成并收集與Zipkin兼容的trace，默認情況下，它通過HTTP將它們發送到localhost上的Zipkin服務器（端口9411），你可以通過設置spring.zipkin.baseUrl來配置服務的位置。

如果你依賴spring-rabbit，你的應用程序會將trace發送到RabbitMQ代理而不是HTTP。

如果你依賴spring-kafka，并設置spring.zipkin.sender.type:kafka，你的應用程序會將trace發送到Kafka代理而不是HTTP。

spring-cloud-sleuth-stream已棄用，不應再使用。

Spring Cloud Sleuth兼容OpenTracing。

如果使用Zipkin，請通過設置spring.sleuth.sampler.probability來配置導出的span概率（默認值：0.1，即10％），否則，你可能會認為Sleuth沒有工作，因為它忽略了一些span。
始終設置SLF4J MDC，并且logback用戶可以根據前面顯示的示例立即在日志中看到trace和span ID，其他日志記錄系統必須配置自己的格式化程序才能獲得相同的結果，默認值如下：logging.pattern.level設置為%5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{X-B3-TraceId:-},%X{X-B3-SpanId:-},%X{X-Span-Export:-}](這是Logback用戶的Spring Boot特性)，如果你不使用SLF4J，則不會自動應用此模式。

從版本2.0.0開始，Spring Cloud Sleuth使用Brave作為追蹤庫，為方便起見，在此處嵌入了Brave的部分文檔。

在絕大多數情況下，你只需使用Sleuth提供的Brave中的Tracer或SpanCustomizer bean，下面的文檔概述了Brave是什么以及它是如何工作的。

Brave是一個用于捕獲和報告關于分布式操作的延遲信息到Zipkin的庫，大多數用戶不直接使用Brave，他們使用庫或框架，而不是代表他們使用Brave。

此模塊包含一個追蹤器，用于創建和連接span，對潛在分布式工作的延遲進行建模，它還包括通過網絡邊界傳播trace上下文的庫（例如，使用HTTP頭）。

最重要的是，你需要一個brave.Tracer，配置為向Zipkin報告。

以下示例設置通過HTTP（而不是Kafka）將trace數據（spans）發送到Zipkin：

class MyClass {

    private final Tracer tracer;

    // Tracer will be autowired
    MyClass(Tracer tracer) {
        this.tracer = tracer;
    }

    void doSth() {
        Span span = tracer.newTrace().name("encode").start();
        // ...
    }
}

如果你的span包含一個名稱長度超過50個字符，則該名稱將被截斷為50個字符，你的名稱必須明確而具體，大名稱會導致延遲問題，有時甚至會引發異常。

追蹤器創建并連接span，對潛在分布式工作的延遲進行建模，它可以采用抽樣來減少進程中的開銷，減少發送到Zipkin的數據量，或兩者兼而有之。

追蹤器返回的span在完成后向Zipkin報告數據，如果未采樣則不執行任何操作，啟動span后，你可以批注感興趣的事件或添加包含詳細信息或查找鍵的標記。

Spans具有一個上下文，其中包含trace標識符，該標識符將span放置在表示分布式操作的樹中的正確位置。

當追蹤代碼不離開你的進程，在范圍span內運行它。

@Autowired Tracer tracer;

// Start a new trace or a span within an existing trace representing an operation
ScopedSpan span = tracer.startScopedSpan("encode");
try {
  // The span is in "scope" meaning downstream code such as loggers can see trace IDs
  return encoder.encode();
} catch (RuntimeException | Error e) {
  span.error(e); // Unless you handle exceptions, you might not know the operation failed!
  throw e;
} finally {
  span.finish(); // always finish the span
}

當你需要更多功能或更精細的控制時，請使用Span類型：

@Autowired Tracer tracer;

// Start a new trace or a span within an existing trace representing an operation
Span span = tracer.nextSpan().name("encode").start();
// Put the span in "scope" so that downstream code such as loggers can see trace IDs
try (SpanInScope ws = tracer.withSpanInScope(span)) {
  return encoder.encode();
} catch (RuntimeException | Error e) {
  span.error(e); // Unless you handle exceptions, you might not know the operation failed!
  throw e;
} finally {
  span.finish(); // note the scope is independent of the span. Always finish a span.
}

上面的兩個例子在完成時報告的span完全相同！

在上面的示例中，span將是新的根span或現有trace中的下一個子span。

擁有span后，你可以為其添加標記，標簽可用作查找鍵或詳細信息，例如，你可以使用運行時版本添加標記，如以下示例所示：

span.tag("clnt/finagle.version", "6.36.0");

當暴露自定義span到第三方的能力時，使用brave.SpanCustomizer而不是brave.Span，前者更易于理解和測試，并且不會使用span生命周期鉤子誘惑用戶。

interface MyTraceCallback {
  void request(Request request, SpanCustomizer customizer);
}

由于brave.Span實現了brave.SpanCustomizer，你可以將其傳遞給用戶，如以下示例所示：

for (MyTraceCallback callback : userCallbacks) {
  callback.request(request, span);
}

有時，你不知道trace是否正在進行，并且您不希望用戶執行null檢查，brave.CurrentSpanCustomizer通過向正在進行或丟棄的任何span添加數據來處理此問題，如以下示例所示：

// The user code can then inject this without a chance of it being null.
@Autowired SpanCustomizer span;

void userCode() {
  span.annotate("tx.started");
  ...
}

在滾動自己的RPC儀器之前，請檢查此處編寫的儀器和Zipkin的列表。

RPC追蹤通常由攔截器自動完成，在幕后，他們添加與他們在RPC操作中的角色相關的標簽和事件。

以下示例顯示如何添加客戶端span：

@Autowired Tracing tracing;
@Autowired Tracer tracer;

// before you send a request, add metadata that describes the operation
span = tracer.nextSpan().name(service + "/" + method).kind(CLIENT);
span.tag("myrpc.version", "1.0.0");
span.remoteServiceName("backend");
span.remoteIpAndPort("172.3.4.1", 8108);

// Add the trace context to the request, so it can be propagated in-band
tracing.propagation().injector(Request::addHeader)
                     .inject(span.context(), request);

// when the request is scheduled, start the span
span.start();

// if there is an error, tag the span
span.tag("error", error.getCode());
// or if there is an exception
span.error(exception);

// when the response is complete, finish the span
span.finish();

有時，你需要在有請求但沒有響應的情況下建模異步操作，在正常的RPC追蹤中，你使用span.finish()來指示已收到響應，在單向追蹤中，你使用span.flush()代替，因為不不期望響應。

以下示例顯示了客戶端如何為單向操作建模：

@Autowired Tracing tracing;
@Autowired Tracer tracer;

// start a new span representing a client request
oneWaySend = tracer.nextSpan().name(service + "/" + method).kind(CLIENT);

// Add the trace context to the request, so it can be propagated in-band
tracing.propagation().injector(Request::addHeader)
                     .inject(oneWaySend.context(), request);

// fire off the request asynchronously, totally dropping any response
request.execute();

// start the client side and flush instead of finish
oneWaySend.start().flush();

以下示例顯示了服務器如何處理單向操作：

@Autowired Tracing tracing;
@Autowired Tracer tracer;

// pull the context out of the incoming request
extractor = tracing.propagation().extractor(Request::getHeader);

// convert that context to a span which you can name and add tags to
oneWayReceive = nextSpan(tracer, extractor.extract(request))
    .name("process-request")
    .kind(SERVER)
    ... add tags etc.

// start the server side and flush instead of finish
oneWayReceive.start().flush();

// you should not modify this span anymore as it is complete. However,
// you can create children to represent follow-up work.
next = tracer.newSpan(oneWayReceive.context()).name("step2").start();