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

attempt to fix numbers

Browse Source
This commit is contained in:
Adrian Cole
2020-04-09 20:58:20 +08:00
parent d4472fb0f0
commit 3e809f0ba1
4 changed files with 25 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
README.adoc
View File

@@ -105,7 +105,7 @@ basic HTTP communication.
:sc-ext: java
:project-full-name: Spring Cloud Sleuth
=== Features
== Features
Sleuth sets up instrumentation not only to track timing, but also to catch
errors so that they can be analyzed or correlated with logs. This works the
same way regardless of if the error came from a common instrumented library,
@@ -116,7 +116,7 @@ Zipkin screenshots. However, most services accepting Zipkin's format[https://zip
have similar base features. Sleuth can also be configured to send data in other
formats, something detailed later.
==== Contextualizing errors
=== Contextualizing errors
Without distributed tracing, it can be difficult to understand the impact of a
an exception. For example, it can be hard to know if a specific request caused
the caller to fail or not.
@@ -135,7 +135,7 @@ image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/{branc
For example, the above error happened in the "backend" service, and caused the
"frontend" service to fail.
==== Log correlation
=== Log correlation
Sleuth configures the logging context with variables including the service name
(`%{spring.zipkin.service.name}`) and the trace ID (`%{traceId}`). These help
you connect logs with distributed traces and allow you choice in what tools you
@@ -188,7 +188,7 @@ filter {
}
}
===== JSON Logback with Logstash
==== 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 so, you have to do the following (for readability, we pass the dependencies in the `groupId:artifactId:version` notation).
@@ -292,7 +292,7 @@ That Logback configuration file:
NOTE: If you use a custom `logback-spring.xml`, you must pass the `spring.application.name` in the `bootstrap` rather than the `application` property file.
Otherwise, your custom logback file does not properly read the property.
==== Service Dependency Graph
=== Service Dependency Graph
When you consider distributed tracing tracks requests, it makes sense that
trace data can paint a picture of your architecture.
@@ -307,7 +307,7 @@ image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/{branc
need to run a separate service to aggregate the dependency graph. You can learn
more https://github.com/openzipkin/zipkin-dependencies/[here].
==== Request scoped properties (Baggage)
=== Request scoped properties (Baggage)
Distributed tracing works by propagating fields inside and across services that
connect the trace together: traceId and spanId notably. The context that holds
these fields can optionally push other fields that need to be consistent
@@ -332,7 +332,7 @@ RPC latency. In extreme cases, too much baggage can crash the application, due
to exceeding transport-level message or header capacity.
===== Baggage versus Tags
==== Baggage versus Tags
Like trace IDs, Baggage is attached to messages or requests, usually as
headers. Tags are key value pairs sent in a Span to Zipkin. Baggage values are

14
docs/src/main/asciidoc/features.adoc
View File

@@ -2,7 +2,7 @@
include::_attributes.adoc[]
=== Features
== Features
Sleuth sets up instrumentation not only to track timing, but also to catch
errors so that they can be analyzed or correlated with logs. This works the
same way regardless of if the error came from a common instrumented library,
@@ -13,7 +13,7 @@ Zipkin screenshots. However, most services accepting Zipkin's format[https://zip
have similar base features. Sleuth can also be configured to send data in other
formats, something detailed later.
==== Contextualizing errors
=== Contextualizing errors
Without distributed tracing, it can be difficult to understand the impact of a
an exception. For example, it can be hard to know if a specific request caused
the caller to fail or not.
@@ -32,7 +32,7 @@ image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/{branc
For example, the above error happened in the "backend" service, and caused the
"frontend" service to fail.
==== Log correlation
=== Log correlation
Sleuth configures the logging context with variables including the service name
(`%{spring.zipkin.service.name}`) and the trace ID (`%{traceId}`). These help
you connect logs with distributed traces and allow you choice in what tools you
@@ -85,7 +85,7 @@ filter {
}
}
===== JSON Logback with Logstash
==== 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 so, you have to do the following (for readability, we pass the dependencies in the `groupId:artifactId:version` notation).
@@ -113,7 +113,7 @@ That Logback configuration file:
NOTE: If you use a custom `logback-spring.xml`, you must pass the `spring.application.name` in the `bootstrap` rather than the `application` property file.
Otherwise, your custom logback file does not properly read the property.
==== Service Dependency Graph
=== Service Dependency Graph
When you consider distributed tracing tracks requests, it makes sense that
trace data can paint a picture of your architecture.
@@ -128,7 +128,7 @@ image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-sleuth/{branc
need to run a separate service to aggregate the dependency graph. You can learn
more https://github.com/openzipkin/zipkin-dependencies/[here].
==== Request scoped properties (Baggage)
=== Request scoped properties (Baggage)
Distributed tracing works by propagating fields inside and across services that
connect the trace together: traceId and spanId notably. The context that holds
these fields can optionally push other fields that need to be consistent
@@ -151,7 +151,7 @@ RPC latency. In extreme cases, too much baggage can crash the application, due
to exceeding transport-level message or header capacity.
===== Baggage versus Tags
==== Baggage versus Tags
Like trace IDs, Baggage is attached to messages or requests, usually as
headers. Tags are key value pairs sent in a Span to Zipkin. Baggage values are

6
docs/src/main/asciidoc/sagan-boot.adoc
View File

@@ -65,8 +65,10 @@ public class Application {
}
```
Run this app and then hit the home page. You will see traceId and spanId populated in the logs. If this app calls out to another one (e.g. with `RestTemplate`) it will send the trace data in headers and if the receiver is another Sleuth app you will see the trace continue there.
Run this app and then hit the home page. You will see traceId and spanId populated in the logs.
If this app calls out to another one (e.g. with `RestTemplate`) it will send the trace data in
headers and if the receiver is another Sleuth app you will see the trace continue there.
* Instead of logging the request in the handler explicitly, you could set `logging.level.org.springframework.web.servlet.DispatcherServlet=DEBUG`
* If you use Zipkin (up till 2.1.x), configure the probability of spans exported by setting `spring.sleuth.sampler.probability` (default: 0.1, which is 10 percent). Otherwise, you might think that Sleuth is not working because it omits some spans. Starting from 2.2.0, Sleuth will default to rate limited sampler. That means that it will sample up to 1000 transactions per second.
* Sleuth defaults to a rate limited sampler. That means that it will sample up to 1000 transactions per second.
* Set `spring.application.name=bar` (for instance) to see the service name as well as the trace and span ids.

12
docs/src/main/asciidoc/sagan-index.adoc
View File

@@ -1,12 +1,14 @@
Spring Cloud Sleuth implements a distributed tracing solution for Spring Cloud, borrowing heavily from https://research.google.com/pubs/pub36356.html[Dapper], https://github.com/openzipkin/zipkin[Zipkin] and HTrace. For most users Sleuth should be invisible, and all your interactions with external systems should be instrumented automatically. You can capture data simply in logs, or by sending it to a remote collector service.
Spring Cloud Sleuth provides Spring Boot auto-configuration for distributed
tracing.
## Features
A Span is 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, key-value annotations, 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. A set of spans forming a tree-like structure called a Trace. For example, if you are running a distributed big-data store, a trace might be formed by a put request.
Sleuth configures everything you need to get started. This includes where trace
data (spans) are reported to, how many traces to keep (sampling), if remote
fields (baggage) are sent, and which libraries are traced.
Spring Cloud Sleuth features:
Specifically, Spring Cloud Sleuth...
* 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.
* 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.
* Instruments common ingress and egress points from Spring applications (servlet filter, rest template, scheduled actions, message channels, feign client).
* If `spring-cloud-sleuth-zipkin` is available then the app will generate and collect Zipkin-compatible traces via HTTP. By default it sends them to a Zipkin collector service on localhost (port 9411). Configure the location of the service using `spring.zipkin.baseUrl`.
* If `spring-cloud-sleuth-zipkin` is available then the app will generate and report https://zipkin.io[Zipkin]-compatible traces via HTTP. By default it sends them to a Zipkin collector service on localhost (port 9411). Configure the location of the service using `spring.zipkin.baseUrl`.