在分布式追踪系统中使用 W3C Trace Context
https://dev.to/luizhlelis/using-w3c-trace-context-standard-in-distributed-tracing-3743
在软件开发中,当系统遭遇到运行时失效的时刻,开发人员会本能地尝试找到是哪里调用了失效的方法,以及哪里是原始的请求。这就是 stack trace
的作用,比如下面的示例所示。
Unhandled exception. System.InvalidOperationException: Stack trace example
at Program.CallChildActivity() in /Users/luizhlelis/Documents/projects/personal/trace-context-w3c/src/system-diagnostics-activity/Program.cs:line 22
at Program.Main() in /Users/luizhlelis/Documents/projects/personal/trace-context-w3c/src/system-diagnostics-activity/Program.cs:line 11
基于上面的信息,我们就可以直到失效发生在 CallChildActivity()
方法 ( 22 行 ),它是被 Main()
方法 ( 1 行 ) 所调用,它们都位于 Program.cs
类中。这就是运行时消息追踪对于软件的健康和可信赖如此重要的原因。像这样丰富的信息极大提高了解决问题的生产力。所以,用术语消息追踪来说,stack trace
对于目标是单进程的应用程序来说非常适合,比如单体应用系统。但是反过来说,对于处理分布式应用系统,例如微服务架构,stack trace
就不能足够用来展示整体的消息追踪了。这就是为什么分布式追踪工具和标准变得必要的原因。W3C 定义了这种追踪类型的标准,称为 Trace Context
。
W3C Trace Context 目标
想象一个使用微服务架构设计的系统,它提供 2 个使用同步方式通讯的 API,其中的第 2 个与 worker 通过消息代理通讯。
图 1 分布式追踪
与 stack trace
类似,每个 Activity
需要一个唯一标识,还需要知道是调用者的唯一标识。为了解决此类问题,许多厂商发布了不仅提供分布式追踪消息信息,还包括了应用程序性能,加载时间,应用程序响应时间,以及其它内容。此类 vendor
被称为 应用程序性能管理工具 ( Application Performance Management tools (APM tools) )
,或者追踪系统,下面是其中的一些:
- Dynatrace
- New Relic
- Application Insights
- Elastic APM
- Zipkin
注意:我选择术语
verdor
来描述所有的追踪系统,是因为这是标准的说明它们的方式。但是看起来 它会很快发生变化。
现在想象一个场景,这里有各种 vendor 使用各种语言并使用各种的诊断库,有一些使用 operation-id
来标识,有些使用 request-id
,可能还有一些使用 trace-id
。除此之外,基于不同 vendor 或者诊断库的标识格式也各不相同。有的是分层 ( hierarchical ) 格式,有的使用 UUID,有的是 24 字符的字符串格式等等。这就会导致这样的结果:使用不同追踪系统 vendor 导致不能关联起来,也不能将追踪传播,因为这里没有唯一标识可以传递。这就是 trace context 标准的作用。
trace context 标准
W3C Trace Context 规范定义了针对 HTTP 头的标准和格式,用来传播分布式追踪上下文信息。其中定义了 2 个字段用来在 HTTP 请求头中传播追踪流。先看一下标准定义中的这 2 个字段:
traceparent
: 用来描述在追踪图谱中到达请求的位置。它表示在追踪系统中到达请求的通用格式,被所有的 vendor 所理解。tracestate
: 使用 vendor 特定的数据表示形式来扩展traceparent
,使用 name/value 对形式。在 tracestate 中保存信息是可选的。
traceparent
字段
traceparent
字段的规范使用扩充巴科斯范式 (ABNF ) 形式定义,由 4 个部分组成
version - traceid - parentid/spanid - traceflags
注意:
sub-field
术语是非官方的。我使用该术语仅仅用于说明。
例如:
00-480e22a2781fe54d992d878662248d94-b4b37b64bb3f6141-00
version
: 8 位,系统适配的追踪上下文版本,当前位00
trace-id
: 16 字节,追踪整体的标识。用于在系统中标识一个分布式追踪整体。parent-id
/span-id
: 8 字节,用来表述在进入请求中,或者对外请求中,当前跨度的父级。trace-flags
: 8 位,调用者的建议标志,可以考虑为调用者的建议,限制为 3 个原因:信息或是滥用,调用方的错误,或者在调用方与被调用方的不同负载。
所有字段都使用 16 进制编码 ( hexadecimal )
进而,在图 1 中的应用程序中应用 trace context 的概念,将导致如下的结果:
图 2 传播字段
需要注意的是,trace-id
标识了整个追踪,而 parent-id
标识整个追踪中限定的范围。进而,traceparent
和 tracestate
一起在整个追踪流中传播。
为了更好地动态说明 traceparent
,让我们看下面的示例,它使用 C# 编写,这里生成了 2 个跨度,并且共享的上下文在其间传播。
using System;
using System.Diagnostics;
var upstreamActivity = new Activity("Upstream");
upstreamActivity.Start();
Console.WriteLine(upstreamActivity.OperationName);
Console.WriteLine("traceparent: {0}", upstreamActivity.Id);
CallChildActivity();
upstreamActivity.Stop();
Console.ReadKey();
void CallChildActivity()
{
var downstreamActivity = new Activity("Downstream Dependency");
downstreamActivity.Start();
Console.WriteLine(downstreamActivity.OperationName);
Console.WriteLine("traceparent: {0}", downstreamActivity.Id);
downstreamActivity.Stop();
}
注意:在 .NET 5 中,
System.Diagnostics.Activity
库已经被配置为使用 W3C 标准。
即使上面的示例是作为单进程应用程序,还是使用了 Trace Context 标准的模式。基本上,这个程序做这些事情:
- 首先,它开始一个上游的跨度,并输出其
traceparent
到控制台 - 然后,它调用一个下游的方法,开始另一个跨度,也输出它的
traceparent
到控制台,并关闭跨度 - 最后,上游的跨度被关闭
输出如下所示:
Upstream
traceparent: 00-3e425f2373d89640bde06e8285e7bf88-9a5fdefae3abb440-00
Downstream Dependency
traceparent: 00-3e425f2373d89640bde06e8285e7bf88-0767a6c6c1240f47-00
注意这个 trace-id
(3e425f2373d89640bde06e8285e7bf88) 在整个追踪中被维护,而 parent-id
基于不同的跨度是不同的,上游中是:9a5fdefae3abb440 而下游中是 0767a6c6c1240f47。
在有些场景下,parent-id
会由于其名称导致困惑。但是,该名称是相对于到达的请求来说的。因此,必须从端点的角度来看待,例如,考虑一个请求消息刚刚到达 API 的控制器,从请求头中接收到的 traceparent
还没有被更新到中间件跨度的 parent-id
中,所以,此刻 traceparent
中的 parent-id
就是上游标识,或者说,就是父级。
tracestate
字段
Trace Context:AMQP 协议
如图 2 所示,在微服务架构中,通常使用中间商来传播消息。对于此类操作,有另一个文档规范该模式 ( 这里使用 AMQP 协议 ),Trace Context: AMQP protocol
Trace Context: AMQP 协议
是另外一个 W3C 示例文档,该规范定义了与 HTTP 标准不同的 trace context 字段处理。
该标准建议 traceparent
和 tracestat
两者应该添加到消息发布者的消息的 application-properties
部分中,从消息读取者的角度来说,trace context 应该首先通过读取 message-annotations
来构建,如果这里不存在,再通过 application-properties
读取。参见如下的 AMQP 协议消息格式。
图 3 AMQP 消息格式
将 trace context 字段放置到消息发布者定义的消息内的 application-properties
部分的原因是中间商不能修改这些属性,因为这部分是不可变的。从另外的角度来说,message-annotations
被设计为由中间商使用,换句话说,该部分中的字段可以在消息处理过程中发生更改。因此,这意味着,如果需要在中间件内部对消息进行注释,则必须在消息注释部分中进行注释,并使用发布者在应用程序属性中发送的字段作为基础。
小结
W3C 标准规范了在分布式追踪系统中的模式。当前,只有用于 HTTP 的,其它还在工作中 ( AMQP, MQTT 和 baggate)。但这不意味着你应该在产品环境中忽视它,但是要注意到这些变化,更重要的是保持对最新发布的更新。