View on GitHub

opentracing-specification-zh

OpenTracing标准（中文版） `zh` (Chinese) translation of the opentracing/specification

OpenTracing语义标准

版本号: 1.1

综述

这是正式的OpenTracing语义标准。OpenTracing是一个跨编程语言的标准，此文档会避免具有语言特性的概念。比如，我们在文档中使用”interface”，因为所有的语言都包含”interface”这种概念。

版本命名策略

OpenTracing标准使用Major.Minor版本命名策略（即：大版本.小版本），但不包含.Patch版本（即：补丁版本）。如果标准做出不向前兼容的改变，则使用“主版本”号提升。如果是向前兼容的改进，则进行小版本号提升，例如加入新的标准tag, log和SpanContext引用类型。（如果你想知道更多关于制定此版本政策的原因，可参考specification#2）

OpenTracing数据模型

OpenTracing中的Trace（调用链）通过归属于此调用链的Span来隐性的定义。 特别说明，一条Trace（调用链）可以被认为是一个由多个Span组成的有向无环图（DAG图）， Span与Span的关系被命名为References。

译者注: Span，可以被翻译为跨度，可以被理解为一次方法调用, 一个程序块的调用, 或者一次RPC/数据库访问.只要是一个具有完整时间周期的程序访问，都可以被认为是一个span.在此译本中，为了便于理解，Span和其他标准内声明的词汇，全部不做名词翻译。

例如：下面的示例Trace就是由8个Span组成：

单个Trace中，span间的因果关系


        [Span A]  ←←←(the root span)
            |
     +------+------+
     |             |
 [Span B]      [Span C] ←←←(Span C 是 Span A 的孩子节点, ChildOf)
     |             |
 [Span D]      +---+-------+
               |           |
           [Span E]    [Span F] >>> [Span G] >>> [Span H]
                                       ↑
                                       ↑
                                       ↑
                         (Span G 在 Span F 后被调用, FollowsFrom)

有些时候，使用下面这种，基于时间轴的时序图可以更好的展现Trace（调用链）：

单个Trace中，span间的时间关系


––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–––––––|–> time

 [Span A···················································]
   [Span B··············································]
      [Span D··········································]
    [Span C········································]
         [Span E·······]        [Span F··] [Span G··] [Span H··]

每个Span包含以下的状态:（译者注：由于这些状态会反映在OpenTracing API中，所以会保留部分英文说明）

每一个SpanContext包含以下状态：

Span间关系

一个Span可以与一个或者多个SpanContexts存在因果关系。OpenTracing目前定义了两种关系：ChildOf（父子） 和 FollowsFrom（跟随）。这两种关系明确的给出了两个父子关系的Span的因果模型。 将来，OpenTracing可能提供非因果关系的span间关系。（例如：span被批量处理，span被阻塞在同一个队列中，等等）。

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

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

    [-Parent Span---------]
         [-Child Span----]

    [-Parent Span--------------]
         [-Child Span A----]
          [-Child Span B----]
        [-Child Span C----]
         [-Child Span D---------------]
         [-Child Span E----]

FollowsFrom 引用: 一些父级节点不以任何方式依赖他们子节点的执行结果，这种情况下，我们说这些子span和父span之间是”FollowsFrom”的因果关系。”FollowsFrom”关系可以被分为很多不同的子类型，未来版本的OpenTracing中将正式的区分这些类型

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

    [-Parent Span-]  [-Child Span-]


    [-Parent Span--]
     [-Child Span-]


    [-Parent Span-]
                [-Child Span-]

OpenTracing API

OpenTracing标准中有三个重要的相互关联的类型，分别是Tracer, Span 和 SpanContext。下面，我们分别描述每种类型的行为，一般来说，每个行为都会在各语言实现层面上，会演变成一个方法，而实际上由于方法重载，很可能演变成一系列相似的方法。

当我们讨论“可选”参数时，需要强调的是，不同的语言针对可选参数有不同理解，概念和实现方式 。例如，在Go中，我们习惯使用”functional Options”，而在Java中，我们可能使用builder模式。

Tracer

Tracer接口用来创建Span，以及处理如何处理Inject(serialize) 和 Extract (deserialize)，用于跨进程边界传递。它具有如下官方能力：

创建一个新Span

必填参数

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

操作名 指导意见
get 太抽象
get_account/792 太明确
get_account 正确的操作名，关于account_id=792的信息应该使用Tag操作

可选参数

返回值，返回一个已经启动Span实例（已启动，但未结束。译者注：英语上started和finished理解容易混淆）

将SpanContext上下文Inject（注入）到carrier

必填参数

将SpanContext上下文从carrier中Extract（提取）

必填参数

返回值，返回一个SpanContext实例，可以使用这个SpanContext实例，通过Tracer创建新的Span。

注意，对于Inject（注入）和Extract（提取），format是必须的。

Inject（注入）和Extract（提取）依赖于可扩展的format参数。format参数规定了另一个参数”carrier”的类型，同时约束了”carrier”中SpanContext是如何编码的。所有的Tracer实现，都必须支持下面的format。

Span

当Span结束后(span.finish())，除了通过Span获取SpanContext外，下列其他所有方法都不允许被调用。

获取Span的SpanContext

不需要任何参数。

返回值，Span构建时传入的SpanContext。这个返回值在Span结束后(span.finish())，依然可以使用。

复写操作名（operation name）

必填参数

结束Span

可选参数

为Span设置tag

必填参数

注意，OpenTracing标准包含“standard tags，标准Tag”，此文档中定义了Tag的标准含义。

Log结构化数据

必填参数

可选参数

注意，OpenTracing标准包含“standard log keys，标准log的键”，此文档中定义了这些键的标准含义。

设置一个baggage（随行数据）元素

Baggage元素是一个键值对集合，将这些值设置给给定的Span，Span的SpanContext，以及所有和此Span有直接或者间接关系的本地Span。 也就是说，baggage元素随trace一起保持在带内传递。（译者注：带内传递，在这里指，随应用程序调用过程一起传递）

Baggage元素具有强大的功能，使得OpenTracing能够实现全栈集成（例如：任意的应用程序数据，可以在移动端创建它，显然的，它会一直传递了系统最底层的存储系统），同时他也会产生巨大的开销，请小心使用此特性。

再次强调，请谨慎使用此特性。每一个键值都会被拷贝到每一个本地和远程的下级相关的span中，因此，总体上，他会有明显的网络和CPU开销。

必填参数

获取一个baggage元素

必填参数

返回值，相应的baggage value,或者可以标识元素值不存在的返回值（译者注：如Null）。

SpanContext

相对于OpenTracing中其他的功能，SpanContext更多的是一个“概念”。也就是说，OpenTracing实现中，需要重点考虑，并提供一套自己的API。 OpenTracing的使用者仅仅需要，在创建span、向传输协议Inject（注入）和从传输协议中Extract（提取）时，使用SpanContext和references，

OpenTracing要求，SpanContext是不可变的，目的是防止由于Span的结束和相互关系，造成的复杂生命周期问题。

遍历所有的baggage元素

遍历模型依赖于语言，实现方式可能不一致。在语义上，要求调用者可以通过给定的SpanContext实例，高效的遍历所有的baggage元素

NoopTracer

所有的OpenTracing API实现，必须提供某种方式的NoopTracer实现。NoopTracer可以被用作控制或者测试时，进行无害的inject注入（等等）。例如，在 OpenTracing-Java实现中，NoopTracer在他自己的模块中。

可选 API 元素

有些语言的OpenTracing实现，为了在串行处理中，传递活跃的Span或SpanContext，提供了一些工具类。例如，opentracing-go中，通过context.Context机制，可以设置和获取活跃的Span。