本节深入探讨春云侦探的细节。 在这里,您可以了解您可能想要使用和自定义的主要功能。 如果您还没有这样做,您可能需要阅读“入门.html”和“使用.html”部分,以便您在基础知识方面有良好的基础。
1. 上下文传播
跟踪使用标头传播从一个服务连接到另一个服务。 默认格式为B3。 与数据格式类似,您也可以配置备用标头格式,前提是跟踪和范围 ID 与 B3 兼容。最值得注意的是,这意味着跟踪 ID 和跨度 ID 是小写十六进制,而不是 UUID。 除了跟踪标识符之外,其他属性(行李)也可以随请求一起传递。 远程行李必须预先定义,但其他方面是灵活的。
要使用提供的默认值,您可以设置该属性。 该值可以是列表,在这种情况下,您将传播更多跟踪标头。spring.sleuth.propagation.type
对于勇敢,我们支持,传播类型。AWS
B3
W3C
您可以在此“操作方法部分”中阅读有关如何提供自定义上下文传播的更多信息。
2. 抽样
Spring Cloud Sleuth将采样决策下推到示踪器实现中。 但是,在某些情况下,您可以在运行时更改采样决策。
其中一种情况是跳过某些客户端跨度的报告。 为此,您可以设置要跳过的路径模式。 另一种选择是提供您自己的自定义实现,并定义何时不应对给定的进行采样。spring.sleuth.web.client.skip-pattern
org.springframework.cloud.sleuth.SamplerFunction<`org.springframework.cloud.sleuth.http.HttpRequest>
HttpRequest
3. 行李
分布式跟踪的工作原理是在服务内部和之间传播将跟踪连接在一起的字段:特别是 traceId 和 spanId。 保存这些字段的上下文可以选择推送需要保持一致的其他字段,而不管涉及许多服务。 这些额外字段的简单名称是“行李”。
侦探允许您定义允许在跟踪上下文中存在的行李,包括使用哪些标头名称。
以下示例显示了如何使用 Spring Cloud Sleuth 的 API 设置行李价值:
目前对行李物品的数量或尺寸没有限制。 请记住,过多可能会降低系统吞吐量或增加 RPC 延迟。 在极端情况下,过多的行李可能会使应用程序崩溃,因为超出了传输级别的消息或标头容量。 |
您可以使用属性来定义没有特殊配置(如名称映射)的字段:
-
spring.sleuth.baggage.remote-fields
是要接受并传播到远程服务的标头名称的列表。 -
spring.sleuth.baggage.local-fields
是要在本地传播的名称列表
这些键没有前缀。 您设置的内容实际上是使用的内容。
在这两个属性中设置的名称将导致相同的名称。Baggage
为了自动将行李值设置为 Slf4j 的 MDC,您必须使用允许的本地或远程密钥列表来设置属性。例如,将行李的价值设置为 MDC。spring.sleuth.baggage.correlation-fields
spring.sleuth.baggage.correlation-fields=country-code
country-code
请注意,额外的字段将从下一个下游跟踪上下文开始传播并添加到 MDC。 若要立即将额外字段添加到当前跟踪上下文中的 MDC,请将字段配置为在更新时刷新:
请记住,向 MDC 添加条目会大大降低应用程序的性能! |
如果要将行李条目添加为标签,以便能够通过行李条目搜索跨度,您可以设置允许的行李钥匙列表的值。 要禁用该功能,您必须传递属性。spring.sleuth.baggage.tag-fields
spring.sleuth.propagation.tag.enabled=false
3.1. 行李与标签
与跟踪 ID 一样,行李附加到消息或请求,通常作为标头。 标签是在跨度中发送到 Zipkin 的键值对。 默认情况下,行李价值不会添加跨度,这意味着除非您选择加入,否则您无法根据行李进行搜索。
要使行李也标签,请使用属性,如下所示:spring.sleuth.baggage.tag-fields
4. 开放齐普金勇敢的示踪剂集成
Spring Cloud Sleuth通过模块中可用的桥与OpenZipkin Brave跟踪器集成。 在本节中,您可以阅读有关特定 Brave 集成的信息。spring-cloud-sleuth-brave
您可以选择直接在代码中使用 Sleuth 的 API 或 Brave API(例如 Sleuth 或 Brave)。 如果您想直接使用此跟踪器实现的 API,请阅读他们的文档以了解更多信息。Tracer
Tracer
4.1. 勇敢的基础
以下是您可能使用的最核心类型:
-
brave.SpanCustomizer
- 更改当前正在进行的跨度 -
brave.Tracer
- 开始新的跨度临时
以下是OpenZipkin Brave项目中最相关的链接:
- 勇敢者的核心库
- 行李(繁殖字段)
- HTTP 跟踪
4.2. 勇敢采样
采样仅适用于跟踪后端,例如 Zipkin。 无论采样率如何,跟踪 ID 都会显示在日志中。 采样是一种防止系统过载的方法,方法是始终跟踪某些请求,但不是所有请求。
每秒 10 条跟踪的默认速率由属性控制,当我们知道侦探用于日志记录以外的原因时适用。 使用每秒 100 条以上的跟踪速率时要格外小心,因为它会使跟踪系统过载。spring.sleuth.sampler.rate
采样器也可以由 Java Config 设置,如以下示例所示:
您可以将 HTTP 标头设置为,或者在执行消息传递时,可以将标头设置为 。 这样做会强制对当前请求进行采样,而不考虑配置。 |
默认情况下,采样器将使用刷新范围机制。 这意味着您可以在运行时更改采样属性,刷新应用程序,更改将得到反映。 但是,有时围绕采样器创建代理并从过早调用它(fromannotated方法)的事实可能会导致死锁。 在这种情况下,请显式创建采样器 Bean,或将属性设置为 禁用刷新范围支持。@PostConstruct
spring.sleuth.sampler.refresh.enabled
false
4.3. 勇敢的行李 Java 配置
如果您需要执行比上述更高级的操作,请不要定义属性,而是对使用的行李字段使用 aconfig。@Bean
-
BaggagePropagationCustomizer
设置行李字段 - 为 a 添加 ato 控件标头名称。
SingleBaggageField
Baggage
-
CorrelationScopeCustomizer
设置 MDC 字段 - 添加 aa 以在更新刷新时更改 aor 的 MDC 名称。
SingleCorrelationField
Baggage
4.4. 勇敢的自定义
该对象完全由侦探管理,因此您很少需要影响它。 也就是说,Sleuth支持多种类型,允许您使用自动配置或属性配置Sleuth尚未完成的任何操作。brave.Tracer
Customizer
如果您将以下之一定义为 a,Sleuth 将调用它来自定义行为:Bean
-
RpcTracingCustomizer
- 用于 RPC 标记和采样策略 -
HttpTracingCustomizer
- 用于 HTTP 标记和采样策略 -
MessagingTracingCustomizer
- 用于消息标记和采样策略 -
CurrentTraceContextCustomizer
- 集成相关等装饰器。 -
BaggagePropagationCustomizer
- 用于在处理中和标题上传播行李字段 -
CorrelationScopeDecoratorCustomizer
- 用于范围修饰,例如 MDC(日志记录)字段关联
4.4.1. 勇敢的采样自定义
如果需要客户端/服务器采样,只需注册一个类型的 bean,并将 beanfor 客户端采样器和 for 服务器采样器命名为。brave.sampler.SamplerFunction<HttpRequest>
sleuthHttpClientSampler
sleuthHttpServerSampler
为了您的方便,可以使用 theandannotation 来注入正确的 bean 或通过其静态字符串字段引用 bean 名称。@HttpClientSampler
@HttpServerSampler
NAME
查看 Brave 的代码,了解如何制作基于路径的采样器github.com/openzipkin/brave/tree/master/instrumentation/http#sampling-policy
如果你想完全重写 bean,你可以使用接口来检索不应该采样的 URL。 下面您可以看到服务器端内部的使用示例。HttpTracing
SkipPatternProvider
Pattern
SkipPatternProvider
Sampler<HttpRequest>
4.5. 勇敢的消息传递
Sleuth 自动配置 thebean,作为 Kafka 或 JMS 等消息传递工具的基础。MessagingTracing
如果需要自定义消息跟踪的生产者/使用者采样,只需注册一个类型的 bean,并将 bean命名为生产者采样器和使用者采样器。brave.sampler.SamplerFunction<MessagingRequest>
sleuthProducerSampler
sleuthConsumerSampler
为了您的方便,可以使用 theandannotation 来注入正确的 bean 或通过其静态字符串字段引用 bean 名称。@ProducerSampler
@ConsumerSampler
NAME
前任。 下面是一个每秒跟踪 100 个使用者请求的采样器,“警报”通道除外。 其他请求将使用组件提供的全局速率。Tracing
有关详细信息,请参阅github.com/openzipkin/brave/tree/master/instrumentation/messaging#sampling-policy
4.6. 勇敢的公开追踪
您可以通过thebridge与Brave和OpenTracing集成。 只需将其添加到类路径中,OpenTracing将自动设置。io.opentracing.brave:brave-opentracingTracer
5. 将跨度发送到齐普金
Spring Cloud Sleuth提供了与OpenZipkin分布式跟踪系统的各种集成。 无论选择哪种跟踪器实现,添加到类路径以开始向 Zipkin 发送跨度就足够了。 您可以选择是通过 HTTP 还是消息传递来执行此操作。 您可以在“如何部分”中阅读有关如何执行此操作的更多信息。spring-cloud-sleuth-zipkin
当跨度关闭时,它通过HTTP发送到Zipkin。通信是异步的。 您可以通过设置属性来配置 URL,如下所示:spring.zipkin.baseUrl
如果要通过服务发现查找 Zipkin,可以在 URL 中传递 Zipkin 的服务 ID,如以下示例所示:zipkinserver
要禁用此功能,只需设置为。spring.zipkin.discovery-client-enabled
false
启用发现客户端功能后,侦探用于查找 Zipkin 服务器的 URL。 这意味着您可以设置负载平衡配置。LoadBalancerClient
如果你在类路径上有,,或一起,你可能需要选择你想将span发送到zipkin的方法。 为此,设置,,或属性。 以下示例演示如何设置发件人类型:web
rabbit
activemq
kafka
web
rabbit
activemq
kafka
spring.zipkin.sender.type
web
如果您正在运行非反应式应用程序,我们将使用基于跨度的发送器。否则,将选择基于范围发送器。RestTemplate
WebClient
要自定义通过HTTP将跨度发送到Zipkin,您可以在注释的Spring配置类中注册bean。RestTemplate
ZipkinRestTemplateCustomizer
@Configuration
但是,如果您想控制创建对象的整个过程,则必须创建一个 bean oftype。RestTemplate
ZipkinRestTemplateProvider
默认情况下,将根据编码器版本设置 api 路径。如果要使用自定义 api 路径,可以使用以下属性(空大小写,设置 “”)对其进行配置:api/v2/spans
api/v1/spans
对于反应式应用程序,我们将创建一个简单实例。如果要提供自己的实例或重用现有的实例,则需要创建 abean 的实例。WebClient.Builder
ZipkinWebClientBuilderProvider
5.1. 自定义服务名称
默认情况下,Sleuth 假定,当您将跨度发送到 Zipkin 时,您希望跨度的服务名称等于属性的值。 然而,情况并非总是如此。 在某些情况下,您希望为来自应用程序的所有跨度显式提供不同的服务名称。 若要实现此目的,可以将以下属性传递给应用程序以重写该值(该示例适用于名为的服务):spring.application.name
myService
5.2. 主机定位器
本节介绍如何从服务发现定义主机。 这不是通过服务发现找到Zipkin。 |
要定义与特定跨度对应的主机,我们需要解析主机名和端口。 默认方法是从服务器属性中获取这些值。 如果未设置这些,我们将尝试从网络接口检索主机名。
如果启用了发现客户端,并且希望从服务注册表中的注册实例中检索主机地址,则必须设置属性(它适用于基于 HTTP 和基于流的跨度报告),如下所示:spring.zipkin.locator.discovery.enabled
5.3. 自定义报告跨度
在侦探中,我们生成具有固定名称的跨度。 某些用户希望根据标签的值修改名称。
侦探注册的 abean 可以自动跳过给定名称模式的报告范围。 该属性包含范围名称的默认跳过模式。 该属性会将提供的跨度名称模式追加到现有模式。 为了禁用此功能,只需设置。SpanFilter
spring.sleuth.span-filter.span-name-patterns-to-skip
spring.sleuth.span-filter.additional-span-name-patterns-to-skip
spring.sleuth.span-filter.enabled
false
5.3.1. 勇敢地自定义报告范围
本节仅适用于勇敢的示踪剂。 |
在报告跨度(例如,向 Zipkin 报告)之前,您可能希望以某种方式修改该跨度。 您可以通过实现 a 来实现。SpanHandler
下面的示例演示如何注册两个实现的 Bean:SpanHandler
前面的示例导致将报告的跨度的名称更改为,就在报告之前(例如,更改为 Zipkin)。foo bar
5.4. 覆盖 Zipkin 的自动配置
Spring Cloud Sleuth 从 2.1.0 版本开始支持向多个跟踪系统发送跟踪。为了使它工作,每个跟踪系统都需要有aand。 如果要覆盖提供的 bean,则需要为它们指定一个特定名称。 为此,您可以分别使用和。Reporter<Span>
Sender
ZipkinAutoConfiguration.REPORTER_BEAN_NAME
ZipkinAutoConfiguration.SENDER_BEAN_NAME
6. 日志集成
Sleuth 使用变量配置日志记录上下文,包括服务名称(或者如果未设置前一个)、跨度 ID () 和跟踪 ID ()。 这些可帮助您将日志与分布式跟踪连接起来,并允许您选择用于对服务进行故障排除的工具。%{spring.zipkin.service.name}
%{spring.application.name}
%{spanId}
%{traceId}
找到任何有错误的日志后,可以在消息中查找跟踪 ID。 将其粘贴到分布式跟踪系统中,以可视化整个跟踪,无论第一个请求最终命中了多少服务。
例如,您会注意到跟踪 ID 是。 此日志配置由侦探自动设置。 您可以通过禁用侦探 viaproperty 或放置您自己的属性来禁用它。5e8eeec48b08e26882aba313eb08f0a4
spring.sleuth.enabled=false
logging.pattern.level
如果您使用日志聚合工具(例如Kibana、Splunk 等),则可以对发生的事件进行排序。 Kibana 中的示例类似于下图:
如果要使用Logstash,下面的清单显示了 Logstash 的 Grok 模式:
如果要将 Grok 与 Cloud Foundry 中的日志一起使用,则必须使用以下模式: |
6.1. 带有日志存储的 JSON 登录
通常,您不希望将日志存储在文本文件中,而是存储在 Logstash 可以立即选择的 JSON 文件中。 为此,您必须执行以下操作(为了可读性,我们在符号中传递依赖项)。groupId:artifactId:version
依赖项设置
- 确保回日志位于类路径 () 上。
ch.qos.logback:logback-core
- 添加日志存储日志回点编码。 例如,要使用版本,请添加。
4.6
net.logstash.logback:logstash-logback-encoder:4.6
登录设置
请考虑以下 Logback 配置文件 (logback-spring.xml) 示例。
该回日志配置文件:
- 以 JSON 格式将应用程序中的信息记录到 afile。
build/${spring.application.name}.json
- 注释掉了两个附加器:控制台和标准日志文件。
- 具有与上一节中介绍的日志记录模式相同的日志记录模式。
如果使用自定义,则必须传递 in 而不是属性文件。 否则,您的自定义登录文件无法正确读取该属性。 |
7. 自我记录跨度
通过抽象引入了表示跨度配置的声明性格式。通过分析Sleuth的源代码,可以创建包含所有跨度特征的附录(包括允许的标签键和事件名称)。您可以查看侦探跨度附录以获取更多信息。DocumentedSpan
8. 跟踪执行器端点
Spring Cloud Sleuth带有一个执行器端点,可以存储完成的跨度。可以通过 HTTP Get 方法查询终结点以仅检索存储范围的列表,也可以通过 HTTP Post 方法查询该列表并清除它。traces
存储跨度的队列的大小可以通过属性进行配置。management.endpoint.traces.queue-size
请阅读文档的Spring 引导执行器:生产就绪功能部分,以了解有关执行器端点配置选项的更多信息。
9. 接下来要读什么
如果要了解有关本节中讨论的任何类的详细信息,可以直接浏览源代码。 如果您有具体问题,请参阅操作方法部分。
如果您对Spring Cloud Sleuth的核心功能感到满意,则可以继续阅读SpringCloud Sleuth的集成。