本文主要基于 SkyWalking 3.2.6 正式版1. 概述2. Trace2.1 ID2.2 AbstractSpan2.3 TraceSegmentRef2.4 TraceSegment3. Context3.1 ContextManager3.2 AbstractTracerContext3.3 SamplingService
1. 概述
分布式链路追踪系统，链路的追踪大体流程如下：
Agent 收集 Trace 数据。Agent 发送 Trace 数据给 Collector 。Collector 接收 Trace 数据。Collector 存储 Trace 数据到存储器，例如，数据库。
本文主要分享【第一部分】SkyWalking Agent 收集 Trace 数据。文章的内容顺序如下：Trace 的数据结构Context 收集 Trace 的方法
不包括插件对 Context 收集的方法的调用，后续单独文章专门分享，胖友也可以阅读完本文后，自己去看 apm-sdk-plugin 的实现代码。
本文涉及到的代码如下图：
红框部分：Trace 的数据结构，在 「2. Trace」 分享。黄框部分：Context 收集 Trace 的方法，在 「3. Context」 分享。
2. Trace
友情提示：胖友，请先行阅读 《OpenTracing语义标准》 。
本小节，笔者认为胖友已经对 OpenTracing 有一定的理解。
org.skywalking.apm.agent.core.context.trace.TraceSegment ，是一次分布式链路追踪( Distributed Trace ) 的一段。一条TraceSegment ，用于记录所在线程( Thread )的链路。一次分布式链路追踪，可以包含多条TraceSegment ，因为存在跨进程( 例如，RPC 、MQ 等等)，或者垮线程( 例如，并发执行、异步回调等等 )。
TraceSegment 属性，如下：traceSegmentId 属性，TraceSegment 的编号，全局唯一。在 「2.1 ID」 详细解析。refs 属性，TraceSegmentRef数组，指向的父TraceSegment 数组。为什么会有多个爸爸？下面统一讲。TraceSegmentRef ，在 「2.3 TraceSegmentRef」 详细解析。relatedGlobalTraces 属性，关联的 DistributedTraceId数组。为什么会有多个爸爸？下面统一讲。DistributedTraceId ，在 「2.1.2 DistributedTraceId」 详细解析。spans 属性，包含的 Span数组。在 「2.2 AbstractSpan」 详细解析。这是 TraceSegment 的主体，总的来说，TraceSegment 是 Span 数组的封装。ignore 属性，是否忽略该条 TraceSegment 。在一些情况下，我们会忽略 TraceSegment ，即不收集链路追踪，在下面 「3. Context」 部分内容，我们将会看到这些情况。isSizeLimited 属性，Span 是否超过上限( `Config.Agent.SPAN_LIMIT_PER_SEGMENT` )。超过上限，不在记录 Span 。
为什么会有多个爸爸？我们先来看看一个爸爸的情况，常见于 RPC 调用。例如，【服务 A】调用【服务 B】时，【服务 B】新建一个 TraceSegment 对象：将自己的 `refs` 指向【服务 A】的 TraceSegment 。将自己的 `relatedGlobalTraces` 设置为 【服务 A】的 DistributedTraceId 对象。我们再来看看多个爸爸的情况，常见于 MQ / Batch 调用。例如，MQ 批量消费消息时，消息来自【多个服务】。每次批量消费时，【消费者】新建一个 TraceSegment 对象：将自己的 `refs` 指向【多个服务】的多个TraceSegment 。将自己的 `relatedGlobalTraces` 设置为【多个服务】的多个DistributedTraceId 。(((1)))
下面，我们来具体看看 TraceSegment 的每个元素，最后，我们会回过头，在 「2.4 TraceSegment」 详细解析它。
2.1 ID
org.skywalking.apm.agent.core.context.ids.ID ，编号。从类的定义上，这是一个通用的编号，由三段整数组成。
目前使用 GlobalIdGenerator 生成，作为全局唯一编号。属性如下：part1 属性，应用实例编号。part2 属性，线程编号。part3 属性，时间戳串，生成方式为 ${时间戳} * 10000 + 线程自增序列([0, 9999]) 。例如：15127007074950012 。具体生成方法的代码，在 GlobalIdGenerator 中详细解析。encoding 属性，编码后的字符串。格式为 "${part1}.${part2}.${part3}" 。例如，"12.35.15127007074950000" 。使用 `#encode()` 方法，编码编号。isValid 属性，编号是否合法。使用 `ID(encodingString)` 构造方法，解析字符串，生成 ID 。
2.1.1 GlobalIdGenerator
org.skywalking.apm.agent.core.context.ids.GlobalIdGenerator ，全局编号生成器。
#generate() 方法，生成 ID 对象。代码如下：第 67 行：获得线程对应的 IDContext 对象。第 69 至 73 行：生成 ID 对象。第 70 行：`ID.part1` 属性，应用编号实例。第 71 行：`ID.part2` 属性，线程编号。第 72 行：`ID.part3` 属性，调用 `IDContext#nextSeq()` 方法，生成带有时间戳的序列号。ps ：代码比较易懂，已经添加完成注释。
2.1.2 DistributedTraceId
org.skywalking.apm.agent.core.context.ids.DistributedTraceId ，分布式链路追踪编号抽象类。id 属性，全局编号。
DistributedTraceId 有两个实现类：org.skywalking.apm.agent.core.context.ids.NewDistributedTraceId ，新建的分布式链路追踪编号。当全局链路追踪开始，创建 TraceSegment 对象的过程中，会调用 `DistributedTraceId()` 构造方法，创建 DistributedTraceId 对象。该构造方法内部会调用 GlobalIdGenerator#generate() 方法，创建 ID 对象。org.skywalking.apm.agent.core.context.ids.PropagatedTraceId ，传播的分布式链路追踪编号。例如，A 服务调用 B 服务时，A 服务会将 DistributedTraceId 对象带给 B 服务，B 服务会调用 `PropagatedTraceId(String id)` 构造方法 ，创建 PropagatedTraceId 对象。该构造方法内部会解析 id ，生成 ID 对象。
2.1.3 DistributedTraceIds
org.skywalking.apm.agent.core.context.ids.DistributedTraceIds ，DistributedTraceId 数组的封装。relatedGlobalTraces 属性，关联的 DistributedTraceId链式数组。
#append(DistributedTraceId) 方法，添加分布式链路追踪编号( DistributedTraceId )。代码如下：第 51 至 54 行：移除首个NewDistributedTraceId 对象。为什么呢？在 「2.4 TraceSegment」 的构造方法中，会默认创建 NewDistributedTraceId 对象。在跨线程、或者跨进程的情况下时，创建的 TraceSegment 对象，需要指向父 Segment 的 DistributedTraceId ，所以需要移除默认创建的。第 56 至 58 行：添加 DistributedTraceId 对象到数组。
2.2 AbstractSpan
org.skywalking.apm.agent.core.context.trace.AbstractSpan ，Span接口( 不是抽象类 )，定义了 Span 通用属性的接口方法：#getSpanId() 方法，获得 Span 编号。一个整数，在 TraceSegment 内唯一，从 0 开始自增，在创建 Span 对象时生成。#setOperationName(operationName) 方法，设置操作名。操作名，定义如下：
#setOperationId(operationId) 方法，设置操作编号。考虑到操作名是字符串，Agent 发送给 Collector 占用流量较大。因此，Agent 会将操作注册到 Collector ，生成操作编号。在 《SkyWalking 源码分析 —— Agent DictionaryManager 字典管理》 有详细解析。#setComponent(Component) 方法，设置 org.ponent ，例如：MongoDB / SpringMVC / Tomcat 等等。目前，官方在 org.ponentsDefine 定义了目前已经支持的 Component 。#setComponent(componentName) 方法，直接设置 Component 名字。大多数情况下，我们不使用该方法。(((1))) #setLayer(SpanLayer) 方法，设置 org.skywalking.apm.agent.core.context.trace.SpanLayer 。目前有，DB 、RPC_FRAMEWORK 、HTTP 、MQ ，未来会增加 CACHE 。#tag(key, value) 方法，设置键值对的标签。可以调用多次，构成 Span 的标签集合。在 「2.2.1 Tag」 详细解析。日志相关#log(timestampMicroseconds, fields) 方法，记录一条通用日志，包含 fields 键值对集合。#log(Throwable) 方法，记录一条异常日志，包含异常信息。#errorOccurred() 方法，标记发生异常。大多数情况下，配置 #log(Throwable) 方法一起使用。#start() 方法，开始 Span 。一般情况的实现，设置开始时间。#isEntry() 方法，是否是入口 Span ，在 「2.2.2.1 EntrySpan」 详细解析。#isExit() 方法，是否是出口 Span ，在 「2.2.2.2 ExitSpan」 详细解析。
2.2.1 Tag
2.2.1.1 AbstractTag
org.skywalking.apm.agent.core.context.tag.AbstractTag<T> ，标签抽象类。注意，这个类的用途是将标签属性设置到 Span 上，或者说，它是设置 Span 的标签的工具类。代码如下：key 属性，标签的键。#set(AbstractSpan span, T tagValue)抽象方法，设置 Span 的标签键 key 的值为 tagValue。
2.2.1.2 StringTag
org.skywalking.apm.agent.core.context.tag.StringTag ，值类型为 String 的标签实现类。#set(AbstractSpan span, String tagValue)实现方法，设置 Span 的标签键 key 的值为 tagValue 。
2.2.1.3 Tags
org.skywalking.apm.agent.core.context.tag.Tags ，常用Tag枚举类，内部定义了多个HTTP 、DB 相关的 StringTag 的静态变量。
在 《opentracing-specification-zh —— 语义惯例》 里，定义了标准的 Span Tag 。
2.2.2 AbstractSpan 实现类
AbstractSpan 实现类如下图：
左半边的 Span 实现类：有具体操作的 Span 。右半边的 Span 实现类：无具体操作的 Span ，和左半边的 Span 实现类相对，用于不需要收集 Span 的场景。
抛开右半边的 Span 实现类的特殊处理，Span 只有三种实现类：EntrySpan ：入口 SpanLocalSpan ：本地 SpanExitSpan ：出口 Span
下面，我们分小节逐步分享。
2.2.2.1 AbstractTracingSpan
org.skywalking.apm.agent.core.context.trace.AbstractTracingSpan ，实现 AbstractSpan 接口，链路追踪 Span抽象类。
在创建 AbstractTracingSpan 时，会传入 spanId , parentSpanId , operationName / operationId 参数。参见构造方法：#AbstractTracingSpan(spanId, parentSpanId, operationName)#AbstractTracingSpan(spanId, parentSpanId, operationId)
大部分是 setting / getting 方法，或者类似方法，已经添加注释，胖友自己阅读。
#finish(TraceSegment) 方法，完成( 结束 ) Span ，将当前 Span ( 自己 )添加到 TraceSegment 。为什么会调用该方法，在 「3. Context」 详细解析。
`ContextCarrier#serialize()``ContextCarrier#deserialize(text)`
3.2.4 ContextSnapshot
org.skywalking.apm.agent.core.context.ContextSnapshot ，跨线程Context 传递快照。和 ContextCarrier 基本一致，由于不需要跨进程传输，可以少传递一些属性：parentApplicationInstanceIdpeerHost
ContextSnapshot 和 ContextCarrier 比较类似，笔者就列举一些方法：`#TraceSegmentRef(ContextSnapshot)``TracingContext#capture()``TracingContext#continued(ContextSnapshot)`
3.3 SamplingService
org.skywalking.apm.agent.core.sampling.SamplingService ，实现 Service 接口，Agent 抽样服务。该服务的作用是，如何对 TraceSegment 抽样收集。考虑到如果每条 TraceSegment 都进行追踪，会带来一定的 CPU ( 用于序列化与反序列化 ) 和网络的开销。通过配置 Config.Agent.SAMPLE_N_PER_3_SECS 属性，设置每三秒，收集 TraceSegment 的条数。默认情况下，不开启抽样服务，即全部收集。
代码如下：on 属性，是否开启抽样服务。samplingFactorHolder 属性，抽样计数器。通过定时任务，每三秒重置一次。scheduledFuture 属性，定时任务。#boot()实现方法，若开启抽样服务( Config.Agent.SAMPLE_N_PER_3_SECS > 0 ) 时，创建定时任务，每三秒，调用一次 #resetSamplingFactor() 方法，重置计数器。#trySampling() 方法，若开启抽样服务，判断是否超过每三秒的抽样上限。若不是，返回 true ，并增加计数器。否则，返回 false 。#forceSampled() 方法，强制增加计数器加一。一般情况下，该方法用于链路追踪上下文传播时，被调用服务必须记录链路，参见调用处的代码。#resetSamplingFactor() 方法，重置计数器。
2.2.2.2 StackBasedTracingSpan
org.skywalking.apm.agent.core.context.trace.StackBasedTracingSpan ，实现 AbstractTracingSpan 抽象类，基于栈的链路追踪 Span 抽象类。这种 Span 能够被多次调用 #start(...) 和 #finish(...) 方法，在类似堆栈的调用中。在 「2.2.2.2.1 EntrySpan」 中详细举例子。代码如下：stackDepth 属，栈深度。`#finish(TraceSegment)`实现方法，完成( 结束 ) Span ，将当前 Span ( 自己 )添加到 TraceSegment 。当且仅当 `stackDepth == 0` 时，添加成功。代码如下：第 55 至 72 行：当操作编号为空时，尝试使用操作名获得操作编号并设置。用于减少Agent 发送 Collector 数据的网络流量。第 53 至 73 行：栈深度为零，出栈成功。调用 `super#finish(TraceSegment)` 方法，完成( 结束 ) Span ，将当前 Span ( 自己 )添加到 TraceSegment 。第 74 至 76 行：栈深度非零，出栈失败。
2.2.2.2.1 EntrySpan
重点
org.skywalking.apm.agent.core.context.trace.EntrySpan ，实现 StackBasedTracingSpan 抽象类，入口Span ，用于服务提供者( Service Provider ) ，例如 Tomcat 。
EntrySpan 是 TraceSegment 的第一个 Span ，这也是为什么称为"入口" Span 的原因。
那么为什么 EntrySpan 继承 StackBasedTracingSpan？
例如，我们常用的 SprintBoot 场景下，Agent 会在 SkyWalking 插件在 Tomcat 定义的方法切面，创建 EntrySpan 对象，也会在 SkyWalking 插件在 SpringMVC 定义的方法切面，创建 EntrySpan 对象。那岂不是出现两个EntrySpan ，一个 TraceSegment 出现了两个入口 Span ？
答案是当然不会！Agent 只会在第一个方法切面，生成 EntrySpan 对象，第二个方法切面，栈深度+ 1。这也是上面我们看到的 #finish(TraceSegment) 方法，只在栈深度为零时，出栈成功。通过这样的方式，保持一个 TraceSegment 有且仅有一个 EntrySpan 对象。
当然，多个 TraceSegment 会有多个 EntrySpan 对象 ，例如【服务 A】远程调用【服务 B】。
另外，虽然 EntrySpan 在第一个服务提供者创建，EntrySpan 代表的是最后一个服务提供者，例如，上面的例子，EntrySpan 代表的是 Spring MVC 的方法切面。所以，startTime 和 endTime 以第一个为准，componentId 、componentName 、layer 、logs 、tags 、operationName 、operationId 等等以最后一个为准。并且，一般情况下，最后一个服务提供者的信息也会更加详细。
ps：如上内容信息量较大，胖友可以对照着实现方法，在理解理解。HOHO ，良心笔者当然也是加了注释的。
如下是一个 EntrySpan 在 SkyWalking 展示的例子：
2.2.2.2.2 ExitSpan
重点
org.skywalking.apm.agent.core.context.trace.ExitSpan ，继承 StackBasedTracingSpan 抽象类，出口Span ，用于服务消费者( Service Consumer ) ，例如 HttpClient 、MongoDBClient 。
ExitSpan 实现 org.skywalking.apm.agent.core.context.trace.WithPeerInfo 接口，代码如下：peer 属性，节点地址。peerId 属性，节点编号。
如下是一个 ExitSpan 在 SkyWalking 展示的例子：
那么为什么 ExitSpan 继承 StackBasedTracingSpan？
例如，我们可能在使用的 Dubbox 场景下，【Dubbox 服务 A】使用 HTTP 调用【Dubbox 服务 B】时，实际过程是，【Dubbox 服务 A】=》【HttpClient】=》【Dubbox 服务 B】。Agent 会在【Dubbox 服务 A】创建 ExitSpan 对象，也会在 【HttpClient】创建 ExitSpan 对象。那岂不是一次出口，出现两个ExitSpan ？
答案是当然不会！Agent 只会在【Dubbox 服务 A】，生成 EntrySpan 对象，第二个方法切面，栈深度+ 1。这也是上面我们看到的 #finish(TraceSegment) 方法，只在栈深度为零时，出栈成功。通过这样的方式，保持一次出口有且仅有一个 ExitSpan 对象。
当然，一个 TraceSegment 会有多个 ExitSpan 对象 ，例如【服务 A】远程调用【服务 B】，然后【服务 A】再次远程调用【服务 B】，或者然后【服务 A】远程调用【服务 C】。
另外，虽然 ExitSpan 在第一个消费者创建，ExitSpan 代表的也是第一个服务提消费者，例如，上面的例子，ExitSpan 代表的是【Dubbox 服务 A】。
ps：如上内容信息量较大，胖友可以对照着实现方法，在理解理解。HOHO ，良心笔者当然也是加了注释的。
2.2.2.3 LocalSpan
org.skywalking.apm.agent.core.context.trace.LocalSpan ，继承 AbstractTracingSpan 抽象类，本地 Span ，用于一个普通方法的链路追踪，例如本地方法。
如下是一个 EntrySpan 在 SkyWalking 展示的例子：
2.2.2.4 NoopSpan
org.skywalking.apm.agent.core.context.trace.NoopSpan ，实现 AbstractSpan 接口，无操作的 Span 。配置 IgnoredTracerContext 一起使用，在 IgnoredTracerContext 声明单例 ，以减少不收集 Span 时的对象创建，达到减少内存使用和 GC 时间。
2.2.2.3.1 NoopExitSpan
org.skywalking.apm.agent.core.context.trace.NoopExitSpan ，实现 org.skywalking.apm.agent.core.context.trace.WithPeerInfo 接口，继承 StackBasedTracingSpan 抽象类，出口Span ，无操作的出口Span 。和 ExitSpan相对，不记录服务消费者的出口 Span 。
2.3 TraceSegmentRef
org.skywalking.apm.agent.core.context.trace.TraceSegmentRef ，TraceSegment 指向，通过 traceSegmentId 和 spanId 属性，指向父级 TraceSegment 的指定 Span 。type 属性，指向类型( SegmentRefType ) 。不同的指向类型，使用不同的构造方法。CROSS_PROCESS ，跨进程，例如远程调用，对应构造方法 #TraceSegmentRef(ContextCarrier)。CROSS_THREAD ，跨线程，例如异步线程任务，对应构造方法 #TraceSegmentRef(ContextSnapshot) 。构造方法的代码，在 「3. Context」 中，伴随着调用过程，一起解析。traceSegmentId 属性，父TraceSegment 编号。重要spanId 属性，父Span 编号。重要peerId 属性，节点编号。注意，此处的节点编号就是应用( Application )编号。peerHost 属性，节点地址。entryApplicationInstanceId 属性，入口应用实例编号。例如，在一个分布式链路 A->B->C 中，此字段为 A 应用的实例编号。parentApplicationInstanceId 属性，父应用实例编号。entryOperationName 属性，入口操作名。entryOperationId 属性，入口操作编号。parentOperationName 属性，父操作名。parentOperationId 属性，父操作编号。
2.4 TraceSegment
在看完了 TraceSegment 的各个元素，我们来看看 TraceSegment 内部实现的方法。
TraceSegment 构造方法，代码如下：第 80 行：调用 GlobalIdGenerator#generate() 方法，生成 ID 对象，赋值给 traceSegmentId。第 81 行：创建 spans 数组。`#archive(AbstractTracingSpan)` 方法，被 `AbstractSpan#finish(TraceSegment)` 方法调用，添加到 `spans` 数组。第 83 至 84 行：创建 DistributedTraceIds 对象，并添加 NewDistributedTraceId 到它。注意，当 TraceSegment 是一次分布式链路追踪的首条记录，创建的 NewDistributedTraceId 对象，即为分布式链路追踪的全局编号。`#relatedGlobalTraces(DistributedTraceId)` 方法，添加 DistributedTraceId 对象。被 `TracingContext#continued(ContextSnapshot)` 或者 `TracingContext#extract(ContextCarrier)` 方法调用，在 「3. Context」 详细解析。
#ref(TraceSegmentRef) 方法，添加 TraceSegmentRef 对象，到 refs 属性，即指向父 Segment 。
3. Context
在 「2. Trace」 中，我们看了 Trace 的数据结构，本小节，我们一起来看看 Context 是怎么收集 Trace 数据的。
3.1 ContextManager
org.skywalking.apm.agent.core.context.ContextManager ，实现了 BootService 、TracingContextListener 、IgnoreTracerContextListener 接口，链路追踪上下文管理器。
CONTEXT静态属性，线程变量，存储 AbstractTracerContext 对象。为什么是线程变量呢？
一个TraceSegment 对象，关联到一个线程，负责收集该线程的链路追踪数据，因此使用线程变量。
而一个AbstractTracerContext 会关联一个TraceSegment 对象，ContextManager 负责获取、创建、销毁 AbstractTracerContext 对象。
在 ContextManager#createEntrySpan(operationName, carrier) 方法中，当存在ContextCarrier 传递时，创建 Context 后，会将 ContextCarrier解压到 Context 中，以达到跨进程传播。TracingContext#extract(ContextCarrier) 方法，代码如下：第 148 行：将 ContextCarrier 转换成 TraceSegmentRef 对象，调用 TraceSegment#ref(TraceSegmentRef) 方法，进行指向父 TraceSegment。第 149 行：调用 TraceSegment#relatedGlobalTraces(DistributedTraceId) 方法，将传播的分布式链路追踪全局编号，添加到 TraceSegment 中，进行指向全局编号。
另外，ContextManager单独提供 #extract(ContextCarrier) 方法，将多个ContextCarrier 注入到一个Context 中，从而解决"多个爸爸"的场景，例如 RocketMQ 插件的 AbstractMessageConsumeInterceptor#beforeMethod(...) 方法。
3.2.3.2 注入
在 ContextManager#createExitSpan(operationName, carrier, remotePeer) 方法中，当需要Context跨进程传递时，将 Context注入到 ContextCarrier 中，为 「3.2.3.3 传输」 做准备。TracingContext#inject(ContextCarrier) 方法，代码比较易懂，胖友自己阅读理解。
3.2.3.3 传输
友情提示：胖友，请先阅读 《Skywalking Cross Process Propagation Headers Protocol》 。
org.skywalking.apm.agent.core.context.CarrierItem ，传输载体项。代码如：headKey 属性，Header 键。headValue 属性，Header 值。next 属性，下一个项。
CarrierItem 有两个子类：CarrierItemHead ：Carrier 项的头( Head )，即首个元素。SW3CarrierItem ：header = sw3 ，用于传输 ContextCarrier 。
如下是 Dubbo 插件，使用 CarrierItem 的代码例子：
如果觉得《分布式链路追踪 SkyWalking 源码分析——Agent 收集Trace数据》对你有帮助，请点赞、收藏，并留下你的观点哦！
