15. 集成 (15. Integrations) _ Spring Cloud Sleuth2.2.9.BUILD-SNAPSHOT中文文档(官方文档中文翻译)|Spring 教程 —

15. 集成

15.1. OpenTracing

Spring Cloud Sleuth 与 OpenTracing 兼容。如果你在 Classpath 上有 OpenTracing，我们会自动注册 OpenTracing bean。如果要禁用此功能，请设置为Tracerspring.sleuth.opentracing.enabledfalsespring-doc.cn

15.2. Runnable 和 Callable

如果将逻辑包装在或中，则可以将这些类包装在其 Sleuth 代表中，如以下示例所示：RunnableCallableRunnablespring-doc.cn

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.tracing, spanNamer, runnable,
        "calculateTax");
// Wrapping `Runnable` with `Tracing`. That way the current span will be available
// in the thread of `Runnable`
Runnable traceRunnableFromTracer = this.tracing.currentTraceContext()
        .wrap(runnable);

以下示例显示如何对：Callablespring-doc.cn

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<>(this.tracing, spanNamer,
        callable, "calculateTax");
// Wrapping `Callable` with `Tracing`. That way the current span will be available
// in the thread of `Callable`
Callable<String> traceCallableFromTracer = this.tracing.currentTraceContext()
        .wrap(callable);

这样，您可以确保为每次执行创建并关闭一个新的 span。spring-doc.cn

15.3. Spring Cloud 断路器

如果你在 Classpath 上有 Spring Cloud CircuitBreaker，我们将把传递的命令和回退包装在其跟踪表示中。要禁用此检测，请将 .SupplierFunctionspring.sleuth.circuitbreaker.enabledfalsespring-doc.cn

我们注册了一个自定义的 HystrixConcurrencyStrategy，该策略将所有实例包装在其 Sleuth 代表中。该策略可以启动或继续 span，具体取决于在调用 Hystrix 命令之前是否已经在进行跟踪。或者，如果您不想启动新的 span，则可以设置为 to 仅将跟踪上下文传播到 Hystrix 执行线程。要禁用自定义 Hystrix 并发策略，请将设置为。TraceCallableCallablespring.sleuth.hystrix.strategy.passthroughtruespring.sleuth.hystrix.strategy.enabledfalsespring-doc.cn

15.4.2. 手动命令设置

假设您有以下内容：HystrixCommandspring-doc.cn

HystrixCommand<String> hystrixCommand = new HystrixCommand<String>(setter) {
    @Override
    protected String run() throws Exception {
        return someLogic();
    }
};

要传递跟踪信息，您必须将相同的逻辑包装在的 Sleuth 版本中，该版本称为，如以下示例所示：HystrixCommandTraceCommandspring-doc.cn

TraceCommand<String> traceCommand = new TraceCommand<String>(tracer, setter) {
    @Override
    public String doRun() throws Exception {
        return someLogic();
    }
};

15.5. RxJava

我们注册了一个自定义的 RxJavaSchedulersHook，它将所有实例包装在其 Sleuth 代表中，称为 . 钩子可以启动或继续 span，具体取决于在调度 Action 之前是否已经在进行跟踪。要禁用自定义，请将设置为。Action0TraceActionRxJavaSchedulersHookspring.sleuth.rxjava.schedulers.hook.enabledfalsespring-doc.cn

您可以为不希望为其创建 span 的线程名称定义正则表达式列表。为此，请在属性中提供以逗号分隔的正则表达式列表。spring.sleuth.rxjava.schedulers.ignoredthreadsspring-doc.cn

反应式编程和 Sleuth 的建议方法是使用 Reactor 支持。

15.6. HTTP 集成

可以通过将值等于的属性设置为来禁用此部分中的功能。spring.sleuth.web.enabledfalsespring-doc.cn

15.6.1. HTTP 过滤器

通过，所有采样的传入请求都会导致创建一个 Span。该 Span 的名称是 + 请求发送到的路径。例如，如果请求已发送到，则名称将为。您可以通过设置属性来配置要跳过的 URI。如果你有 onclasspath，则其值 of 将附加到提供的 skip 模式中。如果您想重用 Sleuth 的默认跳过模式并仅附加您自己的模式，请使用 .TracingFilterhttp:/this/thathttp:/this/thatspring.sleuth.web.skipPatternManagementServerPropertiescontextPathspring.sleuth.web.additionalSkipPatternspring-doc.cn

默认情况下，所有 Spring Boot Actuator 端点都会自动添加到跳过模式中。如果要禁用此行为，请将 .spring.sleuth.web.ignore-auto-configured-skip-patternstruespring-doc.cn

要更改跟踪过滤器的注册顺序，请设置属性。spring.sleuth.web.filter-orderspring-doc.cn

要禁用记录未捕获异常的过滤器，您可以禁用该属性。spring.sleuth.web.exception-throwing-filter-enabledspring-doc.cn

15.6.2. HandlerInterceptor

由于我们希望 span 名称精确，因此我们使用 a 来包装 existing 或直接添加到 existing . 这会向给定的 . 如果未看到此属性，则会创建一个 “” 范围，这是在服务器端创建的附加范围，以便跟踪在 UI 中正确显示。如果发生这种情况，则可能缺少 instrumentation。在这种情况下，请在 Spring Cloud Sleuth 中提交问题。TraceHandlerInterceptorHandlerInterceptorHandlerInterceptorsTraceHandlerInterceptorHttpServletRequestTracingFilterfallbackspring-doc.cn

15.6.3. 异步 Servlet 支持

如果您的控制器返回 a 或 a ，Spring Cloud Sleuth 将继续现有 span，而不是创建一个新的 span。CallableWebAsyncTaskspring-doc.cn

15.6.4. WebFlux 支持

通过，所有采样的传入请求都会导致创建一个 Span。该 Span 的名称是 + 请求发送到的路径。例如，如果请求被发送到，则名称为。您可以使用该属性配置要跳过的 URI。如果你在 Classpath 上，它的值 of 将附加到提供的 skip 模式中。如果要重用 Sleuth 的默认跳过模式并附加您自己的 skip，请使用 .TraceWebFilterhttp:/this/thathttp:/this/thatspring.sleuth.web.skipPatternManagementServerPropertiescontextPathspring.sleuth.web.additionalSkipPatternspring-doc.cn

要更改跟踪过滤器的注册顺序，请设置属性。spring.sleuth.web.filter-orderspring-doc.cn

15.6.5. Dubbo RPC 支持

通过与 Brave 的集成，Spring Cloud Sleuth 支持 Dubbo。添加依赖项就足够了：brave-instrumentation-dubbospring-doc.cn

<dependency>
    <groupId>io.zipkin.brave</groupId>
    <artifactId>brave-instrumentation-dubbo</artifactId>
</dependency>

您还需要设置包含以下内容的文件：dubbo.propertiesspring-doc.cn

dubbo.provider.filter=tracing
dubbo.consumer.filter=tracing

您可以在此处阅读有关 Brave - Dubbo 集成的更多信息。 Spring Cloud Sleuth 和 Dubbo 的示例可以在这里找到。spring-doc.cn

15.7. HTTP 客户端集成

15.7.1. 同步 REST 模板

我们注入一个拦截器，以确保所有跟踪信息都传递给请求。每次进行调用时，都会创建一个新的 Span。收到响应后，它将关闭。要阻止同步功能，请设置为。RestTemplateRestTemplatespring.sleuth.web.client.enabledfalsespring-doc.cn

您必须注册为 bean，以便注入拦截器。如果使用关键字创建实例，则插桩不起作用。RestTemplateRestTemplatenew

15.7.2. 异步 REST 模板

从 Sleuth 开始，我们不再注册 type 的 bean。创建这样的 bean 取决于您。然后我们对其进行检测。2.0.0AsyncRestTemplate

要阻止要素，请设置为。要禁用创建默认，请设置为。如果您根本不想创建，请设置为。AsyncRestTemplatespring.sleuth.web.async.client.enabledfalseTraceAsyncClientHttpRequestFactoryWrapperspring.sleuth.web.async.client.factory.enabledfalseAsyncRestClientspring.sleuth.web.async.client.template.enabledfalsespring-doc.cn

多个异步 REST 模板

有时，您需要使用 Asynchronous Rest Template 的多个实现。在以下代码段中，您可以看到如何设置此类自定义的示例：AsyncRestTemplatespring-doc.cn

@Configuration
@EnableAutoConfiguration
static class Config {

    @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;
    }

}

15.7.3. `Web客户端`

我们注入一个 implementation 来创建一个 span，并通过 on-success 和 on-error 回调来关闭客户端 span。ExchangeFilterFunctionspring-doc.cn

要阻止此功能，请设置为。spring.sleuth.web.client.enabledfalsespring-doc.cn

您必须将 a 或注册为 bean，以便应用跟踪检测。如果手动创建或，则插桩不起作用。WebClientWebClient.BuilderWebClientWebClient.Builder

15.7.4. 遍历

如果使用 Traverson 库，则可以将 as 注入到 Traverson 对象中。由于已被拦截，因此您可以在客户端中获得对跟踪的完全支持。以下伪代码演示如何执行此操作：RestTemplateRestTemplatespring-doc.cn

@Autowired RestTemplate restTemplate;

Traverson traverson = new Traverson(URI.create("https://some/address"),
    MediaType.APPLICATION_JSON, MediaType.APPLICATION_JSON_UTF8).setRestOperations(restTemplate);
// use Traverson

15.7.5. Apache `HttpClientBuilder` 和 `HttpAsyncClientBuilder`

我们检测和以便跟踪上下文被注入到发送的请求中。HttpClientBuilderHttpAsyncClientBuilderspring-doc.cn

要阻止这些功能，请设置为。spring.sleuth.web.client.enabledfalsespring-doc.cn

15.7.6. Netty `HttpClient` 客户端

我们检测 Netty 的 .HttpClientspring-doc.cn

要阻止此功能，请设置为。spring.sleuth.web.client.enabledfalsespring-doc.cn

您必须注册为 Bean，以便进行检测。如果使用关键字创建实例，则插桩不起作用。HttpClientHttpClientnew

15.7.7. `UserInfoRestTemplateCustomizer`

我们检测 Spring Security 的 .UserInfoRestTemplateCustomizerspring-doc.cn

要阻止此功能，请设置为。spring.sleuth.web.client.enabledfalsespring-doc.cn

15.8. 假动作

默认情况下，Spring Cloud Sleuth 通过 . 您可以通过设置为来完全禁用它。如果这样做，则不会发生与 Feign 相关的插桩。TraceFeignClientAutoConfigurationspring.sleuth.feign.enabledfalsespring-doc.cn

Feign 插桩的一部分是通过 . 您可以通过设置为来禁用它。如果将其设置为 Spring Cloud Sleuth ，则不会检测任何自定义 Feign 组件。但是，所有默认插桩仍然存在。FeignBeanPostProcessorspring.sleuth.feign.processor.enabledfalsefalsespring-doc.cn

15.9. gRPC

Spring Cloud Sleuth 通过为 gRPC 提供检测。您可以通过设置为来完全禁用它。TraceGrpcAutoConfigurationspring.sleuth.grpc.enabledfalsespring-doc.cn

15.9.1. 变体 1

依赖

gRPC 集成依赖于两个外部库来检测客户端和服务器，并且这两个库都必须位于类路径上才能启用检测。

Maven 的：spring-doc.cn

        <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：spring-doc.cn

    compile("io.github.lognet:grpc-spring-boot-starter")
    compile("io.zipkin.brave:brave-instrumentation-grpc")

服务器检测

Spring Cloud Sleuth 利用 grpc-spring-boot-starter 向所有带有 .@GRpcServicespring-doc.cn

客户端检测

gRPC 客户端利用 a 来构建用于与 gRPC 服务器通信的 a。本机提供静态方法作为构建实例的入口点，但是，这种机制不受 Spring 应用程序上下文的影响。ManagedChannelBuilderManagedChannelManagedChannelBuilderManagedChannelspring-doc.cn

Spring Cloud Sleuth 提供了一个可以通过 Spring 应用程序上下文自定义并由 gRPC 客户端注入的 s。在创建 ManagedChannel 实例时，必须使用此构建器。SpringAwareManagedChannelBuilder

Sleuth 创建了一个将 Brave 的客户端拦截器注入 .TracingManagedChannelBuilderCustomizerSpringAwareManagedChannelBuilderspring-doc.cn

15.9.2. 变体 2

Grpc Spring Boot Starter 会自动检测是否存在 Spring Cloud Sleuth 和 brave 的 gRPC 检测，并注册必要的客户端和/或服务器工具。spring-doc.cn

15.10. 异步通信

15.10.1. `@Async` 带注解的方法

在 Spring Cloud Sleuth 中，我们检测与异步相关的组件，以便在线程之间传递跟踪信息。您可以通过将的值设置为来禁用此行为。spring.sleuth.async.enabledfalsespring-doc.cn

如果您使用注释方法，我们会自动修改现有的 Span，如下所示：@Asyncspring-doc.cn

如果方法带有注释，则注释的值是 Span 的名称。@SpanNamespring-doc.cn
如果方法未使用进行批注，则 Span 名称是带批注的方法名称。@SpanNamespring-doc.cn
span 使用方法的类名和方法名进行标记。spring-doc.cn

由于我们正在修改现有 span，如果您想保持其原始名称（例如，通过接收 HTTP 请求创建的 span）您应该使用 Annotation 包装带 Comments 的方法，或者手动创建新的 Span。@Async@NewSpanspring-doc.cn

15.10.2. `@Scheduled` 带注解的方法

在 Spring Cloud Sleuth 中，我们检测计划的方法执行，以便在线程之间传递跟踪信息。您可以通过将的值设置为来禁用此行为。spring.sleuth.scheduled.enabledfalsespring-doc.cn

如果您使用来注释您的方法，我们会自动创建一个具有以下特征的新 span：@Scheduledspring-doc.cn

span name 是带注释的方法名称。spring-doc.cn
span 使用方法的类名和方法名进行标记。spring-doc.cn

如果要跳过某些带注释类的 span 创建，可以使用与带注释类的完全限定名称匹配的正则表达式进行设置。如果一起使用 and，则会为每个 Hystrix 指标创建一个 span 并发送到 Zipkin。此行为可能很烦人。这就是为什么默认情况下为 .@Scheduledspring.sleuth.scheduled.skipPattern@Scheduledspring-cloud-sleuth-streamspring-cloud-netflix-hystrix-streamspring.sleuth.scheduled.skipPattern=org.springframework.cloud.netflix.hystrix.stream.HystrixStreamTaskspring-doc.cn

15.10.3. Executor、ExecutorService 和 ScheduledExecutorService

我们提供、和。这些实施在每次提交、调用或计划新任务时都会创建 span。LazyTraceExecutorTraceableExecutorServiceTraceableScheduledExecutorServicespring-doc.cn

以下示例显示了在使用时如何传递跟踪信息：TraceableExecutorServiceCompletableFuturespring-doc.cn

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(...)

如果有 bean 实现了您想要的接口要从 SPAN 创建中排除，可以使用可提供 Bean 名称列表的属性。Executorspring.sleuth.async.ignored-beansspring-doc.cn

Executor 的自定义

有时，您需要设置 . 以下示例显示如何设置此类自定义：AsyncExecutorExecutorspring-doc.cn

@Configuration
@EnableAutoConfiguration
@EnableAsync
// add the infrastructure role to ensure that the bean gets auto-proxied
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
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

15.11. 消息传递

可以通过将值等于的属性设置为来禁用此部分中的功能。spring.sleuth.messaging.enabledfalsespring-doc.cn

15.11.1. Spring 集成和 Spring Cloud Stream

Spring Cloud Sleuth 与 Spring 集成。它为 publish 和 subscribe 事件创建 span。要禁用 Spring 集成插桩，请设置为。spring.sleuth.integration.enabledfalsespring-doc.cn

您可以提供模式以显式提供要包含以进行跟踪的通道的名称。默认情况下，包括除 channel 之外的所有通道。spring.sleuth.integration.patternshystrixStreamOutputspring-doc.cn

使用构建 Spring Integration 时，必须使用的未跟踪版本 . 装饰 Spring Integration Executor Channel 会导致 span 被不正确地关闭。ExecutorIntegrationFlowExecutorTraceableExecutorService

如果要自定义从消息标头读取和写入跟踪上下文的方式，注册 Bean 类型就足够了：spring-doc.cn

Propagation.Setter<MessageHeaderAccessor, String>- 用于将标头写入消息spring-doc.cn
Propagation.Getter<MessageHeaderAccessor, String>- 用于从消息中读取标头spring-doc.cn

15.11.2. Spring RabbitMq

我们检测，以便注入跟踪标头放入消息中。RabbitTemplatespring-doc.cn

要阻止此功能，请设置为。spring.sleuth.messaging.rabbit.enabledfalsespring-doc.cn

15.11.3. Spring Kafka

我们对 Spring Kafka 进行检测，以便将跟踪标头注入到创建的 Spring Kafka 和 .ProducerFactoryConsumerFactoryProducerConsumerspring-doc.cn

要阻止此功能，请设置为。spring.sleuth.messaging.kafka.enabledfalsespring-doc.cn

15.11.4. Spring Kafka 流

我们检测以便跟踪标头注入到 AND bean 中允许通过其他 AND 方法进行进一步的检测。KafkaStreamsKafkaClientSupplierProducerConsumer`s. A `KafkaStreamsTracingTransformerSupplierProcessorSupplierspring-doc.cn

要阻止此功能，请设置为。spring.sleuth.messaging.kafka.streams.enabledfalsespring-doc.cn

15.11.5. Spring JMS

我们检测，以便注入跟踪标头放入消息中。我们还在消费者端支持带注释的方法。JmsTemplate@JmsListenerspring-doc.cn

要阻止此功能，请设置为。spring.sleuth.messaging.jms.enabledfalsespring-doc.cn

我们不支持 JMS 的行李传播

15.11.6. Spring Cloud AWS 消息收发 SQS

我们检测它是由提供的，以便从消息中提取跟踪标头，并将跟踪放入上下文中。@SqsListenerorg.springframework.cloud:spring-cloud-aws-messagingspring-doc.cn

要阻止此功能，请设置为。spring.sleuth.messaging.sqs.enabledfalsespring-doc.cn

15.12. 祖尔

我们通过使用跟踪信息丰富 Ribbon 请求来检测 Zuul Ribbon 集成。要禁用 Zuul 支持，请将属性设置为。spring.sleuth.zuul.enabledfalsespring-doc.cn

15.13. Redis

我们将属性设置为 Lettcue 实例，以启用在 Lettuce 中构建的 Brave 跟踪。要禁用 Redis 支持，请将属性设置为。tracingClientResourcesspring.sleuth.redis.enabledfalsespring-doc.cn

15.14. Quartz

我们通过向 Quartz Scheduler 添加 Job/Trigger 侦听器来检测 quartz 作业。spring-doc.cn

要关闭此功能，请将该属性设置为。spring.sleuth.quartz.enabledfalsespring-doc.cn

15.15. Project Reactor （项目 Reactor）

15.15.1. 来自 Spring Cloud Sleuth 2.2.8（含）

使用新的 Reactor 队列包装机制（Reactor 3.3.14），我们正在检测 Reactor 切换线程的方式。您应该观察到性能的显著改进。要启用此功能，您必须将选项设置为。spring.sleuth.reactor.decorate-queuestruespring-doc.cn

15.15.2. 到 Spring Cloud Sleuth 2.2.8（独占）

对于依赖于 Project Reactor 的项目（例如 Spring Cloud Gateway），我们建议将选项设为 .这样，与标准插桩机制相比，应该观察到性能提升的增加。这个选项的作用是它将包装 decorate 运算符，而不是这将导致创建更少的对象。这样做的缺点是，当 Project Reactor 更改线程时，跟踪传播将继续而不会出现问题，但是任何依赖于的内容（例如 MDC 条目）都可能有问题。spring.sleuth.reactor.decorate-on-eachfalseonLastonEachThreadLocalspring-doc.cn