Spring Cloud Sleuth 集成
1. 异步通信
在本节中，我们将介绍如何自定义 Spring Cloud Sleuth 的异步通信。
1.1.@Async带注释的方法
此功能适用于所有 Tracer 实现。
在 Spring Cloud Sleuth 中，我们检测与异步相关的组件，以便在线程之间传递跟踪信息。
您可以通过设置spring.sleuth.async.enabled自false.
如果你用@Async，我们会自动修改现有的 Span，如下所示：
-
如果方法带有
@SpanName，则注释的值是 Span 的名称。 -
如果方法没有使用
@SpanName中，Span name 是带注释的方法名称。 -
span 使用方法的类名和方法名进行标记。
由于我们正在修改现有 span，如果您想保持其原始名称（例如，通过接收 HTTP 请求创建的 span）
您应该将@Async带有@NewSpan注释或手动创建新 Span。
1.2.@Scheduled带注释的方法
此功能适用于所有 Tracer 实现。
在 Spring Cloud Sleuth 中，我们检测计划的方法执行，以便在线程之间传递跟踪信息。
您可以通过设置spring.sleuth.scheduled.enabled自false.
如果你用@Scheduled，我们会自动创建一个具有以下特征的新 Span：
-
span name 是带注释的方法名称。
-
span 使用方法的类名和方法名进行标记。
如果您想为某些@Scheduled注解类，您可以设置spring.sleuth.scheduled.skipPattern替换为与@Scheduledannotated 类。
1.3. Executor、ExecutorService 和 ScheduledExecutorService
此功能适用于所有 Tracer 实现。
我们提供LazyTraceExecutor,TraceableExecutorService和TraceableScheduledExecutorService.
这些实施在每次提交、调用或计划新任务时都会创建 span。
以下示例显示了如何使用TraceableExecutorService使用CompletableFuture:
CompletableFuture<Long> completableFuture = CompletableFuture.supplyAsync(() -> {
// perform some logic
return 1_000_000L;
}, new TraceableExecutorService(beanFactory, executorService,
// 'calculateTax' explicitly names the span - this param is optional
"calculateTax"));Sleuth 不适用于parallelStream()开箱即用。
如果要通过流传播跟踪信息，则必须将该方法与supplyAsync(…)，如前所述。 |
如果存在实现Executor要从 SPAN 创建中排除的接口，可以使用spring.sleuth.async.ignored-beans属性，您可以在其中提供 Bean 名称列表。
您可以通过设置spring.sleuth.async.enabled自false.
1.3.1. Executor 的自定义
有时，您需要设置AsyncExecutor.
以下示例显示了如何设置此类自定义Executor:
@Configuration(proxyBeanMethods = false)
@EnableAutoConfiguration
@EnableAsync
// add the infrastructure role to ensure that the bean gets auto-proxied
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
public static class CustomExecutorConfig extends AsyncConfigurerSupport {
@Autowired
BeanFactory beanFactory;
@Override
public Executor getAsyncExecutor() {
ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
// CUSTOMIZE HERE
executor.setCorePoolSize(7);
executor.setMaxPoolSize(42);
executor.setQueueCapacity(11);
executor.setThreadNamePrefix("MyExecutor-");
// DON'T FORGET TO INITIALIZE
executor.initialize();
return new LazyTraceExecutor(this.beanFactory, executor);
}
}要确保您的配置得到后处理，请记住添加@Role(BeanDefinition.ROLE_INFRASTRUCTURE)在您的@Configuration类 |
2. HTTP 客户端集成
可以通过设置spring.sleuth.web.client.enabled值等于false.
2.1. 同步 REST 模板
此功能适用于所有 Tracer 实现。
我们注入一个RestTemplateinterceptor 来确保所有跟踪信息都传递给请求。
每次进行调用时，都会创建一个新的 Span。
收到响应后，它将关闭。
要阻止同步RestTemplate功能， 集spring.sleuth.web.client.enabled自false.
您必须注册RestTemplate作为 bean，以便注入拦截器。
如果您创建一个RestTemplate实例具有new关键字，则插桩不起作用。 |
2.2. 异步 REST 模板
此功能适用于所有 Tracer 实现。
从 Sleuth 开始2.0.0，我们不再注册AsyncRestTemplate类型。
创建这样的 bean 取决于您。
然后我们对其进行检测。 |
要阻止AsyncRestTemplate功能， 集spring.sleuth.web.async.client.enabled自false.
要禁用创建默认TraceAsyncClientHttpRequestFactoryWrapper设置spring.sleuth.web.async.client.factory.enabled自false.
如果您不想创建AsyncRestClient，将spring.sleuth.web.async.client.template.enabled自false.
2.2.1. 多个异步 Rest 模板
有时，您需要使用 Asynchronous Rest Template 的多个实现。
在以下代码段中，您可以看到如何设置此类自定义的示例AsyncRestTemplate:
@Configuration(proxyBeanMethods = false)
public static class TestConfig {
@Bean(name = "customAsyncRestTemplate")
public AsyncRestTemplate traceAsyncRestTemplate() {
return new AsyncRestTemplate(asyncClientFactory(), clientHttpRequestFactory());
}
private ClientHttpRequestFactory clientHttpRequestFactory() {
ClientHttpRequestFactory clientHttpRequestFactory = new CustomClientHttpRequestFactory();
// CUSTOMIZE HERE
return clientHttpRequestFactory;
}
private AsyncClientHttpRequestFactory asyncClientFactory() {
AsyncClientHttpRequestFactory factory = new CustomAsyncClientHttpRequestFactory();
// CUSTOMIZE HERE
return factory;
}
}2.2.2.WebClient
此功能适用于所有 Tracer 实现。
我们注入一个ExchangeFilterFunction创建 Span 并通过 on-success 和 on-error 回调来关闭客户端 Span。
要阻止此功能，请将spring.sleuth.web.client.enabled自false.
您必须注册WebClient作为 Bean，以便应用跟踪插桩。
如果您创建一个WebClient实例具有new关键字，则插桩不起作用。 |
2.2.3. 遍历
此功能适用于所有 Tracer 实现。
如果您使用 Traverson 库，则可以注入RestTemplate作为 bean 放入 Traverson 对象中。
因为RestTemplate已被拦截，则您可以在客户端中获得对跟踪的全面支持。
以下伪代码显示了如何执行此作：
@Autowired RestTemplate restTemplate;
Traverson traverson = new Traverson(URI.create("https://some/address"),
MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate);
// use Traverson2.2.4. 阿帕奇HttpClientBuilder和HttpAsyncClientBuilder
此功能可用于 Brave 跟踪器实施。
我们检测HttpClientBuilder和HttpAsyncClientBuilder以便将跟踪上下文注入到发送的请求中。
要阻止这些功能，请将spring.sleuth.web.client.enabled自false.
2.2.5. 净HttpClient
此功能适用于所有 Tracer 实现。
我们检测 Netty 的HttpClient.
要阻止此功能，请将spring.sleuth.web.client.enabled自false.
您必须注册HttpClient作为 Bean 进行，以便进行检测。
如果您创建一个HttpClient实例具有new关键字，则插桩不起作用。 |
2.2.6.UserInfoRestTemplateCustomizer
此功能适用于所有 Tracer 实现。
我们检测 Spring Security 的UserInfoRestTemplateCustomizer.
要阻止此功能，请将spring.sleuth.web.client.enabled自false.
3. HTTP 服务器集成
可以通过设置spring.sleuth.web.enabled值等于false.
3.1. HTTP 过滤器
此功能适用于所有 Tracer 实现。
通过TracingFilter，则所有采样的传入请求都会导致创建 Span。
您可以通过设置spring.sleuth.web.skipPattern财产。
如果你有ManagementServerProperties在 Classpath 上，其值为contextPath附加到提供的 skip 模式。
如果你想重用 Sleuth 的默认跳过模式并只附加你自己的模式，请使用spring.sleuth.web.additionalSkipPattern.
默认情况下，所有 Spring Boot Actuator 端点都会自动添加到跳过模式中。
如果要禁用此行为，请将spring.sleuth.web.ignore-auto-configured-skip-patterns自true.
要更改跟踪过滤器注册的顺序，请将spring.sleuth.web.filter-order财产。
要禁用记录未捕获异常的过滤器，您可以禁用spring.sleuth.web.exception-throwing-filter-enabled财产。
3.2. HandlerInterceptor
此功能适用于所有 Tracer 实现。
由于我们希望 span 名称精确，因此我们使用TraceHandlerInterceptor，或者将现有的HandlerInterceptor或直接添加到现有HandlerInterceptors.
这TraceHandlerInterceptor将特殊请求属性添加到给定的HttpServletRequest.
如果TracingFilter看不到此属性，它会创建一个“fallback”范围，这是在服务器端创建的附加范围，以便跟踪在 UI 中正确显示。
如果发生这种情况，则可能缺少 instrumentation。
在这种情况下，请在 Spring Cloud Sleuth 中提交问题。
3.3. 异步 Servlet 支持
此功能适用于所有 Tracer 实现。
如果您的控制器返回Callable或WebAsyncTask，Spring Cloud Sleuth 会继续现有 span，而不是创建一个新的 span。
3.4. WebFlux 支持
此功能适用于所有 Tracer 实现。
通过TraceWebFilter，则所有采样的传入请求都会导致创建 Span。
该 Span 的名称是http:+ 请求发送到的路径。
例如，如果请求被发送到/this/that，则名称为http:/this/that.
您可以使用spring.sleuth.web.skipPattern财产。
如果你有ManagementServerProperties在 Classpath 上，其值为contextPath附加到提供的 skip 模式。
如果你想重用 Sleuth 的默认跳过模式并附加你自己的 Skip，请使用spring.sleuth.web.additionalSkipPattern.
为了在性能和上下文传播方面获得最佳结果，我们建议您将spring.sleuth.reactor.instrumentation-type自MANUAL.
为了执行范围内具有 span 的代码，您可以调用WebFluxSleuthOperators.withSpanInScope.
例：
@GetMapping("/simpleManual")
public Mono<String> simpleManual() {
return Mono.just("hello").map(String::toUpperCase).doOnEach(WebFluxSleuthOperators
.withSpanInScope(SignalType.ON_NEXT, signal -> log.info("Hello from simple [{}]", signal.get())));
}要更改跟踪过滤器注册的顺序，请将spring.sleuth.web.filter-order财产。
4. 消息
可以通过设置spring.sleuth.messaging.enabled值等于false.
4.1. Spring 集成
此功能适用于所有 Tracer 实现。
Spring Cloud Sleuth 与 Spring 集成。
它为 publish 和 subscribe 事件创建 span。
要禁用 Spring 集成插桩，请将spring.sleuth.integration.enabled自false.
您可以提供spring.sleuth.integration.patternspattern 显式提供要包含以进行跟踪的通道的名称。
默认情况下，除hystrixStreamOutput频道。
使用Executor构建 Spring 集成IntegrationFlow，则必须使用Executor.
用 Spring Integration Executor Channel 装饰TraceableExecutorService导致 Span 闭合不当。 |
如果要自定义从消息 Headers 读取和写入 tracing 上下文的方式，则注册 Bean 类型就足够了：
-
Propagator.Setter<MessageHeaderAccessor>- 用于将标头写入消息 -
Propagator.Getter<MessageHeaderAccessor>- 用于从消息中读取标头
4.1.2. 自定义消息传递 span
为了更改默认的 span 名称和标签，只需注册一个 bean 类型的MessageSpanCustomizer.您还可以
覆盖现有的DefaultMessageSpanCustomizer来扩展现有行为。
@Component
class MyMessageSpanCustomizer extends DefaultMessageSpanCustomizer {
@Override
public Span customizeHandle(Span spanCustomizer,
Message<?> message, MessageChannel messageChannel) {
return super.customizeHandle(spanCustomizer, message, messageChannel)
.name("changedHandle")
.tag("handleKey", "handleValue")
.tag("channelName", channelName(messageChannel));
}
@Override
public Span.Builder customizeSend(Span.Builder builder,
Message<?> message, MessageChannel messageChannel) {
return super.customizeSend(builder, message, messageChannel)
.name("changedSend")
.tag("sendKey", "sendValue")
.tag("channelName", channelName(messageChannel));
}
}4.2. Spring Cloud 函数和 Spring Cloud Stream
此功能适用于所有 Tracer 实现。
Spring Cloud Sleuth 可以检测 Spring Cloud Function。
实现它的方法是提供Function或Consumer或Supplier它接收一个Message作为参数，例如Function<Message<String>, Message<Integer>>.
如果类型不是Message，则不会进行插桩。
在处理基于 Reactor 的流时，不会进行开箱即用的 instrumentation——例如Function<Flux<Message<String>>, Flux<Message<Integer>>>.
由于 Spring Cloud Stream 重用了 Spring Cloud Function，因此您将立即获得 instrumentation。
您可以通过设置spring.sleuth.function.enabled自false.
为了使用响应式 Stream 函数，您可以利用MessagingSleuthOperators实用程序类，该类允许您处理输入和输出消息，以便继续跟踪上下文并在跟踪上下文中执行自定义代码。
class SimpleReactiveManualFunction implements Function<Flux<Message<String>>, Flux<Message<String>>> {
private static final Logger log = LoggerFactory.getLogger(SimpleReactiveFunction.class);
private final BeanFactory beanFactory;
SimpleReactiveManualFunction(BeanFactory beanFactory) {
this.beanFactory = beanFactory;
}
@Override
public Flux<Message<String>> apply(Flux<Message<String>> input) {
return input.map(message -> (MessagingSleuthOperators.asFunction(this.beanFactory, message))
.andThen(msg -> MessagingSleuthOperators.withSpanInScope(this.beanFactory, msg, stringMessage -> {
log.info("Hello from simple manual [{}]", stringMessage.getPayload());
return stringMessage;
})).andThen(msg -> MessagingSleuthOperators.afterMessageHandled(this.beanFactory, msg, null))
.andThen(msg -> MessageBuilder.createMessage(msg.getPayload().toUpperCase(), msg.getHeaders()))
.andThen(msg -> MessagingSleuthOperators.handleOutputMessage(this.beanFactory, msg)).apply(message));
}
}4.3. Spring RabbitMq
此功能可用于 Brave 跟踪器实施。
我们检测RabbitTemplate以便将跟踪标头注入到消息中。
要阻止此功能，请将spring.sleuth.messaging.rabbit.enabled自false.
4.4. Spring Kafka
此功能可用于 Brave 跟踪器实施。
我们为 Spring Kafka 的ProducerFactory和ConsumerFactory以便将跟踪标头注入到创建的 Spring Kafka 的Producer和Consumer.
要阻止此功能，请将spring.sleuth.messaging.kafka.enabled自false.
4.5. Spring Kafka 流
此功能可用于 Brave 跟踪器实施。
我们检测KafkaStreams KafkaClientSupplier以便将跟踪标头注入到Producer和Consumer`s. A `KafkaStreamsTracingBean 允许通过额外的TransformerSupplier和ProcessorSupplier方法。
要阻止此功能，请将spring.sleuth.messaging.kafka.streams.enabled自false.
4.6. Spring JMS
此功能可用于 Brave 跟踪器实施。
我们检测JmsTemplate以便将跟踪标头注入到消息中。
我们还支持@JmsListener在消费者端的 annotated 方法。
要阻止此功能，请将spring.sleuth.messaging.jms.enabled自false.
| 我们不支持 JMS 的行李传播 |
5. 开放假
此功能适用于所有 Tracer 实现。
默认情况下，Spring Cloud Sleuth 通过以下方式提供与 Feign 的集成TraceFeignClientAutoConfiguration.
您可以通过设置spring.sleuth.feign.enabled自false.
如果这样做，则不会发生与 Feign 相关的插桩。
Feign 插桩的一部分是通过FeignBeanPostProcessor.
您可以通过设置spring.sleuth.feign.processor.enabled自false.
如果将其设置为false，Spring Cloud Sleuth 不会检测任何自定义 Feign 组件。
但是，所有默认插桩仍然存在。
6. 开放追踪
此功能适用于所有 Tracer 实现。
Spring Cloud Sleuth 与 OpenTracing 兼容。
如果您在 Classpath 上有 OpenTracing，我们会自动注册 OpenTracingTracer豆。
如果要禁用此功能，请将spring.sleuth.opentracing.enabled自false
7. Quartz
此功能适用于所有 Tracer 实现。
我们通过向 Quartz Scheduler 添加 Job/Trigger 侦听器来检测 quartz 作业。
要关闭此功能，请将spring.sleuth.quartz.enabledproperty 设置为false.
8. 反应器
此功能适用于所有 Tracer 实现。
我们有以下基于反应器的仪表应用程序模式，可以通过spring.sleuth.reactor.instrumentation-type财产：
-
DECORATE_QUEUES- 使用新的 Reactor 队列包装机制 （Reactor 3.4.3），我们正在检测 Reactor 切换线程的方式。这应该会导致功能与ON_EACH对性能的影响很小。 -
DECORATE_ON_EACH- 将每个 Reactor 运算符包装在跟踪表示中。 在大多数情况下传递跟踪上下文。 此模式可能会导致性能急剧下降。 -
DECORATE_ON_LAST- 将最后一个 Reactor 运算符包装在跟踪表示中。 在某些情况下传递跟踪上下文，因此访问 MDC 上下文可能不起作用。 此模式可能会导致中等性能下降。 -
MANUAL- 以侵入性最小的方式包装每个 Reactor，而不传递跟踪上下文。 这取决于用户来做。
当前默认值为ON_EACH但是，出于向后兼容性的原因，我们鼓励用户迁移到MANUAL仪表和利润WebFluxSleuthOperators和MessagingSleuthOperators.
性能改进可能是显著的。
例：
@GetMapping("/simpleManual")
public Mono<String> simpleManual() {
return Mono.just("hello").map(String::toUpperCase).doOnEach(WebFluxSleuthOperators
.withSpanInScope(SignalType.ON_NEXT, signal -> log.info("Hello from simple [{}]", signal.get())));
}9. Redis
此功能可用于 Brave 跟踪器实施。
我们设置tracingProperty to LettuceClientResources实例来启用在 Lettuce 中构建的 Brave 跟踪。
Spring Cloud Sleuth 将提供ClientResources豆。如果您有该 bean 的 Present 实现，请记住自定义ClientResources.Builder替换为 'ClientResourcesBuilderCustomizer' 流，如下所示：
@Bean(destroyMethod = "shutdown")
DefaultClientResources myLettuceClientResources(ObjectProvider<ClientResourcesBuilderCustomizer> customizer) {
DefaultClientResources.Builder builder = DefaultClientResources.builder();
// setting up the builder manually
customizer.stream().forEach(c -> c.customize(builder));
return builder.build();
}要禁用 Redis 支持，请将spring.sleuth.redis.enabledproperty 设置为false.
10. Runnable 和 Callable
此功能适用于所有 Tracer 实现。
如果你将你的逻辑包装在Runnable或Callable中，您可以将这些类包装在其 Sleuth 代表中，如以下示例所示Runnable:
Runnable runnable = new Runnable() {
@Override
public void run() {
// do some work
}
@Override
public String toString() {
return "spanNameFromToStringMethod";
}
};
// Manual `TraceRunnable` creation with explicit "calculateTax" Span name
Runnable traceRunnable = new TraceRunnable(this.tracer, spanNamer, runnable, "calculateTax");以下示例显示了如何对Callable:
Callable<String> callable = new Callable<String>() {
@Override
public String call() throws Exception {
return someLogic();
}
@Override
public String toString() {
return "spanNameFromToStringMethod";
}
};
// Manual `TraceCallable` creation with explicit "calculateTax" Span name
Callable<String> traceCallable = new TraceCallable<>(tracer, spanNamer, callable, "calculateTax");这样，您可以确保为每次执行创建并关闭一个新的 span。
11. RPC
此功能可用于 Brave 跟踪器实施。
Sleuth 会自动配置RpcTracingbean 作为 gRPC 或 Dubbo 等 RPC 插桩的基础。
如果需要自定义 RPC 跟踪的 Client 端/服务器采样，只需注册一个 bean 类型的brave.sampler.SamplerFunction<RpcRequest>并命名 BeansleuthRpcClientSamplerfor client sampler 和sleuthRpcServerSampler对于 Server Sampler。
为了您的方便，@RpcClientSampler和@RpcServerSampler注释可用于注入正确的 bean 或通过其静态 String 引用 bean 名称NAME领域。
前任。 下面是一个每秒跟踪 100 个“GetUserToken”服务器请求的采样器。 这不会为运行状况检查服务的请求启动新的跟踪。 其他请求将使用全局采样配置。
@Configuration(proxyBeanMethods = false)
class Config {
@Bean(name = RpcServerSampler.NAME)
SamplerFunction<RpcRequest> myRpcSampler() {
Matcher<RpcRequest> userAuth = and(serviceEquals("users.UserService"), methodEquals("GetUserToken"));
return RpcRuleSampler.newBuilder().putRule(serviceEquals("grpc.health.v1.Health"), Sampler.NEVER_SAMPLE)
.putRule(userAuth, RateLimitingSampler.create(100)).build();
}
}11.1. Dubbo RPC 支持
通过与 Brave 的集成，Spring Cloud Sleuth 支持 Dubbo。
只需添加brave-instrumentation-dubboDependency：
<dependency>
<groupId>io.zipkin.brave</groupId>
<artifactId>brave-instrumentation-dubbo</artifactId>
</dependency>您还需要设置dubbo.properties文件，其中包含以下内容：
dubbo.provider.filter=tracing
dubbo.consumer.filter=tracing11.2. gRPC
Spring Cloud Sleuth 通过 Brave 跟踪器为 gRPC 提供检测。
您可以通过设置spring.sleuth.grpc.enabled自false.
11.2.1. 变体 1
依赖
| gRPC 集成依赖于两个外部库来检测客户端和服务器，并且这两个库都必须位于类路径上才能启用检测。 |
Maven 的：
<dependency>
<groupId>io.github.lognet</groupId>
<artifactId>grpc-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>io.zipkin.brave</groupId>
<artifactId>brave-instrumentation-grpc</artifactId>
</dependency>Gradle：
compile("io.github.lognet:grpc-spring-boot-starter")
compile("io.zipkin.brave:brave-instrumentation-grpc")服务器检测
Spring Cloud Sleuth 利用 grpc-spring-boot-starter 向所有带有 Comments 的服务注册 Brave 的 gRPC 服务器拦截器@GRpcService.
客户端检测
gRPC 客户端利用ManagedChannelBuilder构造一个ManagedChannel用于与 gRPC 服务器通信。
原生ManagedChannelBuilder提供静态方法作为构造ManagedChannel实例，但是，此机制不受 Spring 应用程序上下文的影响。
Spring Cloud Sleuth 提供了一个SpringAwareManagedChannelBuilder可以通过 Spring 应用程序上下文进行自定义，并由 gRPC 客户端注入。创建ManagedChannel实例。
|
Sleuth 会创建一个TracingManagedChannelBuilderCustomizer它将 Brave 的客户端拦截器注入SpringAwareManagedChannelBuilder.
11.2.2. 变体 2
Grpc Spring Boot Starter 会自动检测是否存在 Spring Cloud Sleuth 和 Brave 的 gRPC 检测，并注册必要的客户端和/或服务器工具。
12. RxJava
此功能适用于所有 Tracer 实现。
我们注册了一个自定义RxJavaSchedulersHook那包了所有Action0实例在他们的 Sleuth 代表中，称为TraceAction.
钩子可以启动或继续 span，具体取决于在调度 Action 之前是否已经在进行跟踪。
要禁用自定义RxJavaSchedulersHook中，将spring.sleuth.rxjava.schedulers.hook.enabled自false.
您可以为不希望为其创建 span 的线程名称定义正则表达式列表。
为此，请在spring.sleuth.rxjava.schedulers.ignoredthreads财产。
| 反应式编程和 Sleuth 的建议方法是使用 Reactor 支持。 |
13. Spring Cloud 断路器
此功能适用于所有 Tracer 实现。
如果你在 Classpath 上有 Spring Cloud CircuitBreaker，我们将包装传递的命令Supplier和回退Function在其跟踪表示形式中。
要禁用此插桩集spring.sleuth.circuitbreaker.enabled自false.