Reorganizes code under o.s.c.sleuth.baggage

This moves code and properties under org.springframework.cloud.sleuth.baggage
Properties are now under "spring.sleuth.baggage"

Those coming from 2.x should migrate with the following:
 * spring.sleuth.baggage-keys -> `BaggagePropagationCustomizer`
 * spring.sleuth.local-keys -> spring.sleuth.baggage.local-fields
 * spring.sleuth.propagation-keys -> spring.sleuth.baggage.remote-fields
 * spring.sleuth.propagation.tag.whitelisted-keys -> spring.sleuth.baggage.tag-fields
 * spring.sleuth.log.slf4j.whitelisted-mdc-keys -> spring.sleuth.baggage.correlation-fields
 * spring.sleuth.log.slf4j.enabled -> spring.sleuth.baggage.correlation-enabled

Those using MDC should know that for performance reasons, we no longer
set the following fields: `parentId` `spanExportable`.

We also do not set fields to "dirty" by default. Doing this by default
raised the overhead substantially, especially in reactive applications.

Those who want sleuth to override manual `MDC.put` operations as
described in #1416, or with to add back `parentId` `spanExportable` need
to define their own bean:

Ex. this is the former setup:

```java
@Bean CorrelationScopeDecorator oldConfig(List<String> myFieldNames) {
	CorrelationScopeDecorator.Builder builder = MDCScopeDecorator.newBuilder().clear()
			.add(SingleCorrelationField.create(BaggageFields.TRACE_ID))
			.add(SingleCorrelationField.create(BaggageFields.PARENT_ID))
			.add(SingleCorrelationField.create(BaggageFields.SPAN_ID))
			.add(SingleCorrelationField.newBuilder(BaggageFields.SAMPLED)
					.name("spanExportable").build());

        // Set all fields dirty, so that any changes made by MDC directly are reverted.
	for (String name : myFieldNames) {
		builder.add(SingleCorrelationField.newBuilder(BaggageField.create(name))
				.dirty().build());
	}
	return builder.build();
}

```
This commit is contained in:
Adrian Cole
2020-04-06 23:06:10 +08:00
parent f01a65b035
commit 44a7f4b7ad
34 changed files with 592 additions and 798 deletions

View File

@@ -5,6 +5,11 @@
|spring.sleuth.async.configurer.enabled | true | Enable default AsyncConfigurer.
|spring.sleuth.async.enabled | true | Enable instrumenting async related components so that the tracing information is passed between threads.
|spring.sleuth.async.ignored-beans | | List of {@link java.util.concurrent.Executor} bean names that should be ignored and not wrapped in a trace representation.
|spring.sleuth.baggage.correlation-enabled | true | Enable a {@link Slf4jScopeDecorator} that prints tracing information in the logs.
|spring.sleuth.baggage.correlation-fields | | A list of keys to be put from baggage to MDC.
|spring.sleuth.baggage.local-fields | | Same as {@link #remoteKeys} except that this field is not propagated to remote services. @see brave.baggage.BaggagePropagationConfig.SingleBaggageField#local(BaggageField)
|spring.sleuth.baggage.remote-fields | | List of fields that are referenced the same in-process as it is on the wire. For example, the name "x-vcap-request-id" would be set as-is including the prefix. <p> Note: {@code fieldName} will be implicitly lower-cased. @see brave.baggage.BaggagePropagationConfig.SingleBaggageField#remote(BaggageField)
|spring.sleuth.baggage.tag-fields | | A list of baggage field names which are tagged when a span finishes.
|spring.sleuth.circuitbreaker.enabled | true | Enable Spring Cloud CircuitBreaker instrumentation.
|spring.sleuth.enabled | true |
|spring.sleuth.feign.enabled | true | Enable span information propagation when using Feign.
@@ -15,9 +20,6 @@
|spring.sleuth.integration.enabled | true | Enable Spring Integration sleuth instrumentation.
|spring.sleuth.integration.patterns | [!hystrixStreamOutput*, *, !channel*] | An array of patterns against which channel names will be matched. @see org.springframework.integration.config.GlobalChannelInterceptor#patterns() Defaults to any channel name not matching the Hystrix Stream and functional Stream channel names.
|spring.sleuth.integration.websockets.enabled | true | Enable tracing for WebSockets.
|spring.sleuth.local-keys | | Same as {@link #remoteKeys} except that this field is not propagated to remote services. @see brave.baggage.BaggagePropagationConfig.SingleBaggageField#local(BaggageField)
|spring.sleuth.log.slf4j.enabled | true | Enable a {@link Slf4jScopeDecorator} that prints tracing information in the logs.
|spring.sleuth.log.slf4j.whitelisted-mdc-keys | | A list of keys to be put from baggage to MDC.
|spring.sleuth.messaging.enabled | false | Should messaging be turned on.
|spring.sleuth.messaging.jms.enabled | true | Enable tracing of JMS.
|spring.sleuth.messaging.jms.remote-service-name | jms |
@@ -27,9 +29,6 @@
|spring.sleuth.messaging.rabbit.enabled | true | Enable tracing of RabbitMQ.
|spring.sleuth.messaging.rabbit.remote-service-name | rabbitmq |
|spring.sleuth.opentracing.enabled | true |
|spring.sleuth.remote-keys | | List of fields that are referenced the same in-process as it is on the wire. For example, the name "x-vcap-request-id" would be set as-is including the prefix. <p> Note: {@code fieldName} will be implicitly lower-cased. @see brave.baggage.BaggagePropagationConfig.SingleBaggageField#remote(BaggageField)
|spring.sleuth.propagation.tag.enabled | true | Enables a {@link TagPropagationFinishedSpanHandler} that adds extra propagated fields to span tags.
|spring.sleuth.propagation.tag.whitelisted-keys | | A list of keys to be put from extra propagation fields to span tags.
|spring.sleuth.reactor.decorate-on-each | true | When true decorates on each operator, will be less performing, but logging will always contain the tracing entries in each operator. When false decorates on last operator, will be more performing, but logging might not always contain the tracing entries.
|spring.sleuth.reactor.enabled | true | When true enables instrumentation for reactor.
|spring.sleuth.redis.enabled | true | Enable span information propagation when using Redis.

View File

@@ -5,19 +5,16 @@ include::_attributes.adoc[]
* 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, as shown in the following 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] ...
2016-02-02 15:30:57.902 INFO [bar,6bfd228dc00d216b,6bfd228dc00d216b] 23030 --- [nio-8081-exec-3] ...
2016-02-02 15:30:58.372 ERROR [bar,6bfd228dc00d216b,6bfd228dc00d216b] 23030 --- [nio-8081-exec-3] ...
2016-02-02 15:31:01.936 INFO [bar,46ab0d418373cbc9,46ab0d418373cbc9] 23030 --- [nio-8081-exec-4] ...
----
+
Notice the `[appname,traceId,spanId,exportable]` entries from the MDC:
Notice the `[appname,traceId,spanId]` 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.
When would you like the span not to be exportable?
When 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, and key-value annotations.
Spring Cloud Sleuth is loosely based on HTrace but is compatible with Zipkin (Dapper).
@@ -56,7 +53,7 @@ NOTE: The SLF4J MDC is always set and logback users immediately see the trace an
shown earlier.
Other logging systems have to configure their own formatter to get the same result.
The default is as follows:
`logging.pattern.level` set to `%5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{traceId:-},%X{spanId:-},%X{spanExportable:-}]`
`logging.pattern.level` set to `%5p [${spring.zipkin.service.name:${spring.application.name:-}},%X{traceId:-},%X{spanId:-}]`
(this is a Spring Boot feature for logback users).
If you do not use SLF4J, this pattern is NOT automatically applied.

View File

@@ -90,29 +90,31 @@ In order to use the rate-limited sampler set the `spring.sleuth.sampler.rate` pr
Baggage are fields that are propagated with the trace, optionally out of process. You can use
properties to define fields that have no special configuration such as name mapping:
* `spring.sleuth.remote-keys` is a list of header names to accept and propagate to remote services.
* `spring.sleuth.local-keys` is a list of names to propagate locally
* `spring.sleuth.remote-fields` is a list of header names to accept and propagate to remote services.
* `spring.sleuth.local-fields` is a list of names to propagate locally
No prefixing applies with these keys. What you set is literally what is used.
A name set in either of these properties will result in a `BaggageField` of the same name.
In order to automatically set the baggage values to Slf4j's MDC, you have to set
the `spring.sleuth.log.slf4j.whitelisted-mdc-keys` property with a list of whitelisted
local or remote keys. E.g. `spring.sleuth.log.slf4j.whitelisted-mdc-keys=country-code` will set the
the `spring.sleuth.baggage.correlation-fields` property with a list of whitelisted
local or remote keys. E.g. `spring.sleuth.baggage.correlation-fields=country-code` will set the
value of the `country-code` baggage into MDC.
IMPORTANT: Remember that adding entries to MDC can drastically decrease the performance of your application!
If you want to add the baggage entries as tags, to make it possible to search for spans via the baggage entries, you can set the value of
`spring.sleuth.propagation.tag.whitelisted-keys` with a list of whitelisted baggage keys. To disable the feature you have to pass the `spring.sleuth.propagation.tag.enabled=false` property.
`spring.sleuth.baggage.tag-fields` with a list of whitelisted baggage keys. To disable the feature you have to pass the `spring.sleuth.propagation.tag.enabled=false` property.
=== Java configuration
If you need to do anything more advanced than above, do not define properties and instead use a
`@Bean` config for the baggage fields you use.
* `SingleBaggageField` controls header names for one `BaggageField`.
* `SingleCorrelationField` controls the MDC name of one `BaggageField`, and whether updates flush.
* `BaggagePropagationCustomizer` sets up baggage fields
* Add a `SingleBaggageField` to control header names for a `BaggageField`.
* `CorrelationScopeCustomizer` sets up MDC fields
* Add a `SingleCorrelationField` to change the MDC name of a `BaggageField` or if updates flush.
== Instrumentation