From 2f49b0c31d1ef1d80b091d789be5f8f51d906c11 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Tue, 12 Jun 2018 13:31:37 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- multi/multi__features.html | 6 ++++-- multi/multi__introduction.html | 2 +- multi/multi__propagation.html | 2 +- single/spring-cloud-sleuth.html | 10 ++++++---- spring-cloud-sleuth.xml | 12 ++++++++---- 5 files changed, 20 insertions(+), 12 deletions(-) diff --git a/multi/multi__features.html b/multi/multi__features.html index 0c16eb35e..f21c5840b 100644 --- a/multi/multi__features.html +++ b/multi/multi__features.html @@ -21,7 +21,9 @@ The default is as follows: (this is a Spring Boot feature for logback users). If you do not use SLF4J, this pattern is NOT automatically applied.

3.1 Introduction to Brave

[Important]Important

Starting with version 2.0.0, Spring Cloud Sleuth uses Brave as the tracing library. -For your convenience, we embed part of the Brave’s docs here.

Brave is a library used to capture and report latency information about distributed operations to Zipkin. +For your convenience, we embed part of the Brave’s docs here.

[Important]Important

In the vast majority of cases you need to just use the Tracer +or SpanCustomizer beans from Brave that Sleuth provides. The documentation below contains +a high overview of what Brave is and how it works.

Brave is a library used to capture and report latency information about distributed operations to Zipkin. Most users do not use Brave directly. They use libraries or frameworks rather than employ Brave on their behalf.

This module includes a tracer that creates and joins spans that model the latency of potentially distributed work. It also includes libraries to propagate the trace context over network boundaries (for example, with HTTP headers).

3.1.1 Tracing

Most importantly, you need a brave.Tracer, configured to report to Zipkin.

The following example setup sends trace data (spans) to Zipkin over HTTP (as opposed to Kafka):

class MyClass {
 
@@ -111,4 +113,4 @@ 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();
[Note]Note

The propagation logic shown in the preceding example is a simplified version of our [http handlers](https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server).

You can find a working example of a one-way span [here](src/test/java/sleuth/features/async/OneWaySpanTest.java).

Prev   Next
2. Additional Resources Home 4. Sampling
\ No newline at end of file +next = tracer.newSpan(oneWayReceive.context()).name("step2").start();
[Note]Note

The propagation logic shown in the preceding example is a simplified version of our http handlers.

Prev   Next
2. Additional Resources Home 4. Sampling
\ No newline at end of file diff --git a/multi/multi__introduction.html b/multi/multi__introduction.html index dfaedc9ad..7bfd00fb5 100644 --- a/multi/multi__introduction.html +++ b/multi/multi__introduction.html @@ -12,7 +12,7 @@ the request started, and where it ended. For learning purposes, however, we mark these events to highlight what kind of an action took place.

The following image shows how Span and Trace look in a system, together with the Zipkin annotations:

Trace Info propagation

Each color of a note signifies a span (there are seven spans - from A to G). Consider the following note:

Trace Id = X
diff --git a/multi/multi__propagation.html b/multi/multi__propagation.html
index f06ab3d51..8d40e24d1 100644
--- a/multi/multi__propagation.html
+++ b/multi/multi__propagation.html
@@ -47,7 +47,7 @@ String countryCode = ExtraFieldPropagation.get(span.context(), spring.sleuth.baggage-keys, you set keys that get prefixed with baggage- for HTTP calls and baggage_ for messaging.
 You can also use the spring.sleuth.propagation-keys property to pass a list of prefixed keys that are whitelisted without any prefix.
5.1.2 Extracting a Propagated Context
The TraceContext.Extractor<C> reads trace identifiers and sampling status from an incoming request or message.
-The carrier is usually a request object or headers.
This utility is used in standard instrumentation (such as [HttpServerHandler](../instrumentation/http/src/main/java/sleuth/http/HttpServerHandler.java)) but can also be used for custom RPC or messaging code.
TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are
+The carrier is usually a request object or headers.
This utility is used in standard instrumentation (such as HttpServerHandler`) but can also be used for custom RPC or messaging code.
TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are
 sharing span IDs between a client and a server.
5.1.3 Sharing span IDs between Client and Server
A normal instrumentation pattern is to create a span representing the server side of an RPC.
 Extractor.extract might return a complete trace context when applied to an incoming client request.
 Tracer.joinSpan attempts to continue this trace, using the same span ID if supported or creating a child span
diff --git a/single/spring-cloud-sleuth.html b/single/spring-cloud-sleuth.html
index cb1bbb703..c0da82f00 100644
--- a/single/spring-cloud-sleuth.html
+++ b/single/spring-cloud-sleuth.html
@@ -12,7 +12,7 @@ the request started, and where it ended. For learning purposes,
 however, we mark these events to highlight what kind
 of an action took place.
  • cs: Client Sent. The client has made a request. This annotation indicates the start of the span.
  • sr: Server Received: The server side got the request and started processing it.
 Subtracting the cs timestamp from this timestamp reveals the network latency.
  • ss: Server Sent. Annotated upon completion of request processing (when the response got sent back to the client).
-Subtracting the sr timestamp from this timestamp reveals the time needed by the server side to process the request.
  • cr> Client Received. Signifies the end of the span.
+Subtracting the sr timestamp from this timestamp reveals 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.
 Subtracting the cs timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server.
The following image shows how Span and Trace look in a system, together with the Zipkin annotations:
Trace Info propagation
Each color of a note signifies a span (there are seven spans - from A to G).
 Consider the following note:
Trace Id = X
@@ -253,7 +253,9 @@ The default is as follows:
 (this is a Spring Boot feature for logback users).
 If you do not use SLF4J, this pattern is NOT automatically applied.
3.1 Introduction to Brave
[Important]Important
Starting with version 2.0.0, Spring Cloud Sleuth uses
 Brave as the tracing library.
-For your convenience, we embed part of the Brave’s docs here.
Brave is a library used to capture and report latency information about distributed operations to Zipkin.
+For your convenience, we embed part of the Brave’s docs here.
[Important]Important
In the vast majority of cases you need to just use the Tracer
+or SpanCustomizer beans from Brave that Sleuth provides. The documentation below contains
+a high overview of what Brave is and how it works.
Brave is a library used to capture and report latency information about distributed operations to Zipkin.
 Most users do not use Brave directly. They use libraries or frameworks rather than employ Brave on their behalf.
This module includes a tracer that creates and joins spans that model the latency of potentially distributed work.
 It also includes libraries to propagate the trace context over network boundaries (for example, with HTTP headers).
3.1.1 Tracing
Most importantly, you need a brave.Tracer, configured to report to Zipkin.
The following example setup sends trace data (spans) to Zipkin over HTTP (as opposed to Kafka):
class MyClass {
 
@@ -343,7 +345,7 @@ 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();
[Note]Note
The propagation logic shown in the preceding example is a simplified version of our [http handlers](https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server).
You can find a working example of a one-way span [here](src/test/java/sleuth/features/async/OneWaySpanTest.java).
4. Sampling
Sampling may be employed to reduce the data collected and reported out of process.
+next = tracer.newSpan(oneWayReceive.context()).name("step2").start();
[Note]Note

The propagation logic shown in the preceding example is a simplified version of our http handlers.

4. Sampling

Sampling may be employed to reduce the data collected and reported out of process. When a span is not sampled, it adds no overhead (a noop).

Sampling is an up-front decision, meaning that the decision to report data is made at the first operation in a trace and that decision is propagated downstream.

By default, a global sampler applies a single rate to all traced operations. Tracer.Builder.sampler controls this setting, and it defaults to tracing every request.

4.1 Declarative sampling

Some applications need to sample based on the type or annotations of a java method.

Most users use a framework interceptor to automate this sort of policy. The following example shows how that might work internally:

// derives a sample rate from an annotation on a java method
@@ -423,7 +425,7 @@ String countryCode = ExtraFieldPropagation.get(span.context(), spring.sleuth.baggage-keys, you set keys that get prefixed with baggage- for HTTP calls and baggage_ for messaging.
 You can also use the spring.sleuth.propagation-keys property to pass a list of prefixed keys that are whitelisted without any prefix.

5.1.2 Extracting a Propagated Context

The TraceContext.Extractor<C> reads trace identifiers and sampling status from an incoming request or message. -The carrier is usually a request object or headers.

This utility is used in standard instrumentation (such as [HttpServerHandler](../instrumentation/http/src/main/java/sleuth/http/HttpServerHandler.java)) but can also be used for custom RPC or messaging code.

TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are +The carrier is usually a request object or headers.

This utility is used in standard instrumentation (such as HttpServerHandler`) but can also be used for custom RPC or messaging code.

TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are sharing span IDs between a client and a server.

5.1.3 Sharing span IDs between Client and Server

A normal instrumentation pattern is to create a span representing the server side of an RPC. Extractor.extract might return a complete trace context when applied to an incoming client request. Tracer.joinSpan attempts to continue this trace, using the same span ID if supported or creating a child span diff --git a/spring-cloud-sleuth.xml b/spring-cloud-sleuth.xml index 334751862..61687f25c 100644 --- a/spring-cloud-sleuth.xml +++ b/spring-cloud-sleuth.xml @@ -52,7 +52,7 @@ Subtracting the cs timestamp from this timestamp reveals the Subtracting the sr timestamp from this timestamp reveals the time needed by the server side to process the request. -cr> Client Received. Signifies the end of the span. +cr: Client Received. Signifies the end of the span. The client has successfully received the response from the server side. Subtracting the cs timestamp from this timestamp reveals the whole time needed by the client to receive the response from the server. @@ -693,6 +693,11 @@ If you do not use SLF4J, this pattern is NOT automatically applied. Brave as the tracing library. For your convenience, we embed part of the Brave’s docs here. + +In the vast majority of cases you need to just use the Tracer +or SpanCustomizer beans from Brave that Sleuth provides. The documentation below contains +a high overview of what Brave is and how it works. + Brave is a library used to capture and report latency information about distributed operations to Zipkin. Most users do not use Brave directly. They use libraries or frameworks rather than employ Brave on their behalf. This module includes a tracer that creates and joins spans that model the latency of potentially distributed work. @@ -835,9 +840,8 @@ oneWayReceive.start().flush(); // you can create children to represent follow-up work. next = tracer.newSpan(oneWayReceive.context()).name("step2").start(); -The propagation logic shown in the preceding example is a simplified version of our [http handlers](https://github.com/openzipkin/sleuth/tree/master/instrumentation/http#http-server). +The propagation logic shown in the preceding example is a simplified version of our http handlers. -You can find a working example of a one-way span [here](src/test/java/sleuth/features/async/OneWaySpanTest.java). @@ -987,7 +991,7 @@ You can also use the spring.sleuth.propagation-keys property Extracting a Propagated Context The TraceContext.Extractor<C> reads trace identifiers and sampling status from an incoming request or message. The carrier is usually a request object or headers. -This utility is used in standard instrumentation (such as [HttpServerHandler](../instrumentation/http/src/main/java/sleuth/http/HttpServerHandler.java)) but can also be used for custom RPC or messaging code. +This utility is used in standard instrumentation (such as HttpServerHandler`) but can also be used for custom RPC or messaging code. TraceContextOrSamplingFlags is usually used only with Tracer.nextSpan(extracted), unless you are sharing span IDs between a client and a server.