While some overview is important, the direct implementation details of tracing
not only drifted since Sleuth 1.x, but also caused a complaint #1466
This deletes most documentation that applies to an abstraction lower than sleuth
and reworks existing docs to focus on features it enables. By doing so, we have
less to maintain and users will have a clearer idea about the relationship
between Sleuth, Zipkin and Brave. Also important is this uses updated screen
shots and is in general less cluttered than before.
Note: the relationship between Sleuth and Brave was already redone in #1603
Note: this also removes the pws app which is usually broken or out of date.
Fixes#1466
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();
}
```
The `spring.sleuth.baggage-keys` property assigned two headers for each
baggage. This causes unnecessary overhead and can be accomplished in another
way now:
```java
public class MyCode {
static final BaggageField USER_ID = BaggageField.create("userId");
@Autowired CurrentTraceContext currentTraceContext;
@Nullable
public String currentUserId() {
return USER_ID.getValue(currentTraceContext.get());
}
}
// In your @Configuration type, if you want to map multiple prefixes...
@Bean
BaggagePropagationConfig userIdBaggageConfig() {
return SingleBaggageField.newBuilder(MyBaggage.USER_ID)
.addKeyName("baggage-userId")
.addKeyName("baggage_userId")
.build();
}
```
