概念和术语

Spans

一个span代表系统中具有开始时间和执行时长的逻辑运行单元。span之间通过嵌套或者顺序排列建立逻辑因果关系。

每一个span都有一个操作名称，这个名称简单，并具有可读性高。（例如：一个RPC方法的名称，一个函数名，或者一个大型计算过程中的子任务或阶段）。span的操作名应该是一个抽象、通用的标识，能够明确的、具有统计意义的名称；更具体的子类型的描述，请使用Tags

例如，假设一个获取账户信息的span会有如下可能的名称：

Inter-Span References

一个span可以和一个或者多个span间存在因果关系。OpenTracing定义了两种关系：ChildOf 和 FollowsFrom。这两种引用类型代表了子节点和父节点间的直接因果关系。未来，OpenTracing将支持非因果关系的span引用关系。（例如：多个span被批量处理，span在同一个队列中，等等）

ChildOf 引用: 一个span可能是一个父级span的孩子，即”ChildOf”关系。在”ChildOf”引用关系下，父级span某种程度上取决于子span。下面这些情况会构成”ChildOf”关系：

  • 一个RPC调用的服务端的span，和RPC服务客户端的span构成ChildOf关系
  • 一个sql insert操作的span，和ORM的save方法的span构成ChildOf关系
  • 很多span可以并行工作（或者分布式工作）都可能是一个父级的span的子项，他会合并所有子span的执行结果，并在指定期限内返回

下面都是合理的表述一个”ChildOf”关系的父子节点关系的时序图。

下面都是合理的表述一个”FollowFrom”关系的父子节点关系的时序图。

每个span可以进行多次Logs操作，每一次Logs操作，都需要一个带时间戳的时间名称，以及可选的任意大小的存储结构。

标准中定义了一些日志（logging）操作的一些常见用例和相关的log事件的键值，可参考Data Conventions Guidelines 数据约定指南。

Tags

每个span可以有多个键值对（key:value）形式的Tags，Tags是没有时间戳的，支持简单的对span进行注解和补充。

和使用Logs的场景一样，对于应用程序特定场景已知的键值对Tags，tracer可以对他们特别关注一下。更多信息，可参考Data Conventions Guidelines 数据约定指南。

每个span必须提供方法访问SpanContext。SpanContext代表跨越进程边界，传递到下级span的状态。(例如，包含<trace_id, span_id, sampled>元组)，并用于封装Baggage (关于Baggage的解释，请参考下文)。SpanContext在跨越进程边界，和在追踪图中创建边界的时候会使用。(ChildOf关系或者其他关系，参考 )。

Baggage拥有强大功能，也会有很大的消耗。由于Baggage的全局传输，如果包含的数量量太大，或者元素太多，它将降低系统的吞吐量或增加RPC的延迟。

Baggage vs. Span Tags

  • Baggage在全局范围内，（伴随业务系统的调用）跨进程传输数据。Span的tag不会进行传输，因为他们不会被子级的span继承。

SpanContexts可以通过Injected操作向Carrier增加，或者通过Extracted从Carrier中获取，跨进程通讯数据（例如：HTTP头）。通过这种方式，SpanContexts可以跨越进程边界，并提供足够的信息来建立跨进程的span间关系（因此可以实现跨进程连续追踪）。

平台无关的API语义

OpenTracing支持了很多不同的平台，当然，每个平台的API试图保持各平台和语言的习惯和管理，尽量做到入乡随俗。也就是说，每个平台的API，都需要根据上述的核心tracing概念来建模实现。在这一章中，我们试图描述这些概念和语义，尽量减少语言和平台的影响。

The Span Interface

Span接口必须实现以下的功能：

  • Get the Span‘s ， 通过span获取SpanContext （即使span已经结束，或者即将结束）
  • Finish，完成已经开始的Span。处理获取SpanContext之外，Finish必须是span实例的最后一个被调用的方法。(py: finish, go: Finish)。 一些的语言实现方法会在Span结束之前记录相关信息，因为Finish方法可能不会被调用，因为主线程处理失败或者其他程序错误。在这种情况下，实现应该明确的记录Span，保证数据的持久化。
  • Set a key:value tag on the Span.，为设置tag。tag的key必须是string类型，value必须是string，boolean或数字类型。tag其他类型的value是没有定义的。如果多个value对应同一个key（例如被设置多次），实现方式是没有被定义的。(py: set_tag, go: SetTag)
  • Add a new log event，为Span增加一个log事件。事件名称是string类型，参数值可以是任何类型，任何大小。tracer的实现者不一定保存所有的参数值（设置可以所有参数值都不保存）。其中的时间戳参数，可以设置当前时间之前的时间戳。(py: log, go: Log)
  • Set a Baggage item, 设置一个string:string类型的键值对。注意，新设置的Baggage元素，只保证传递到未来的子级的Span。参考下图所示。(py: set_baggage_item, go: SetBaggageItem)
  • Get a Baggage item， 通过key获取Baggage中的元素。(py: get_baggage_item, go: BaggageItem)

SpanContext接口必须实现以下功能。用户可以通过Span实例或者Tracer的Extract能力获取SpanContext接口实例。

  • Iterate over all Baggage items 是一个只读特性。(py: baggage, go: ForeachBaggageItem)
  • 虽然以前SpanContext是Tracer接口的一部分，但是对于Inject and Extract是必不可少的。

The Tracer Interface

Tracer接口必须实现以下功能：

  • Start a new Span, 创建一个新的Span。调用者可以指定一个或多个SpanContext 关系(例如 FollowsFrom 或 ChildOf关系)，显示声明一个开始的时间戳（除”now”之外），并设置处理化的Span的tags数据集。(py: start_span, go: StartSpan)
  • Extract a SpanContext ，通过”carrier”跨进程获取SpanContext信息。Extract会检查carrier，尝试获取先前通过Inject放入的数据，并重建SpanContext实例。除非有错误发生，Extract返回一个包含SpanContext实例，此实例可以用来创建一个新的子级Span。（注意：一些OpenTracing实现方式，认为Span在RPC的两端应该具有相同的ID，而另一些考虑客户端是父级span，服务端是子级span）。”carrier”类型需要反射或者明确指定的方式来确定。查看获取更多消息。

Global and No-op Tracers

每一个平台的OpenTracing API库 可能 支持配置(Go: InitGlobalTracer(), py: opentracing.tracer = myTracer)和获取单例的全局Tracer实例(Go: , py: opentracing.tracer)。如果支持全局的Tracer，默认返回的必须是no-op Tracer。