zipkin-client：brave核心代码思路整理

Zipkin是分布式跟踪系统。

简单地理解，可以将Zipkin分为两部分。

一部分为Zipkin Server，其负责接受存储应用程序处理耗时数据，以及UI展示。

另一部分为Zipkin Client，负责在应用程序中收集数据，发送给Zipkin Server，针对Java，其插件为brave。

Zipkin是基于论文“Dapper, a Large-Scale Distributed Systems Tracing Infrastructure”进行设计，没有基于Opentracing API进行开发，但使用了Opentracing规范。在原理上，有许多地方都和基于Opentracing API的Jaeger相似。

brave作为Zipkin Client Java的插件，对于跟踪的系统类型做了很丰富的集成，例如：对MySQL、Servlet、RabbitMQ等都有跟踪的实现。详细情况请参考brave-instrumentation。

本文主要是阅读brave core代码之后，进行的理解记录，即brave-instrumentation实现的原理。运用brave-instrumentation进行跟踪，都会涉及到span的构建、管理和发送。于是我们按照以下的顺序，说一说brave core中Trace的实现。

• Tracing和Tracer构建
• Span构建与管理
• Span发送与关闭

Tracing和Tracer构建

在应用程序中，建议使用一个Tracing来管理Trace，它提供了一个已实例化的Tracer对象。

在Zipkin中，采用Builder模式构建Tracing，简单的构建结构如下：

Tracing tracing = Tracing.newBuilder().build();

这样构建出的Tracing，其中的参数都是默认的。

包括如下属性：

String localServiceName; // 设置跟踪数据服务所在应用程序的名称，属于Endpoint的属性（即serviceName）。默认值：unknown。
Endpoint endpoint; // 端口信息，属于Recorder的属性。
Reporter<zipkin2.Span> reporter; // 记录Span的方式。默认以日志的方式记录（LoggingReporter）
Clock clock; // 记录Span起始和结束时间，以及Span的Annotation的时间，属于Recorder的属性
Sampler sampler = Sampler.ALWAYS_SAMPLE; // 采样
CurrentTraceContext currentTraceContext = CurrentTraceContext.Default.inheritable(); // 当前跟踪上下文. 默认使用一个静态的InheritableThreadLocal自动继承这个context
boolean traceId128Bit = false; // traceId是否设置为128位。默认值为64位
boolean supportsJoin = true; // 
Propagation.Factory propagationFactory = B3Propagation.FACTORY; // 对Span内容进行序列化和反序列化
ErrorParser errorParser = new ErrorParser(); // 这是用于解析错误的简化类型。作用于SpanCustomizer和ScopedSpan

 build() 方法完成对Tracing的构造，并且将Tracer对象进行实例化。

Tracing类中有三个静态方法，newBuilder()，currentTracer()，current()。newBuilder() 上文说过，为Tracing实例提供了构造实例。current() 获取当前已实例化的Tracing对象，currentTracer() 获取已实例化的Tracer对象。

在Tracing创建之后，可以通过tracing.tracer()或者Tracing.currentTracer()获取Tracer对象。

Tracer包含如下属性：

final Clock clock;
final Propagation.Factory propagationFactory;
final Reporter<zipkin2.Span> reporter;
final Recorder recorder;final Sampler sampler;
final ErrorParser errorParser;
final CurrentTraceContext currentTraceContext;
final boolean traceId128Bit, supportsJoin;
final AtomicBoolean noop;

Reporter

其中Reporter接口在 io.zipkin.reporter2:zipkin-reporter 中实现。实现类如下：

• NOOP：对Span的信息不做任何操作
• CONSOLE：在控制台输出Span信息
• LoggingReporter：在日志中输出Span信息
• AsyncReporter：异步处理Span的信息。将Span添加到一个等待的队列中。当跟踪的那个线程调用flush()方法是，则会发送Span。

在brave官方的实例中，通过http的方式，将Span发送到Zipkin server。代码如下：

// Configure a reporter, which controls how often spans are sent
//   (the dependency is io.zipkin.reporter2:zipkin-sender-okhttp3)
sender = OkHttpSender.create("http://127.0.0.1:9411/api/v2/spans");
spanReporter = AsyncReporter.create(sender);

Tracing.newBuilder().spanReporter(spanReporter);

Sampler 

在Zipkin中，Sampler是一个抽象类。在该类中定义了两个最简单的Sampler。ALWAYS_SAMPLE：所有的trace都会被记录。NEVER_SAMPLE：相反，所有trace都不会被记录。

Sampler还有4种类型的Sampler

BoundarySampler：适用于高流量的采样器。当rate为0时，采用NEVER_SAMPLE；当rate为1.0时，采用ALWAYS_SAMPLE；0.0001 <= rate < 1时，采用BoundarySampler。

CountingSampler：适用于低流量的采样器。同上，只有当0.01 <= rate < 1时，采用此采样器。

DeclarativeSampler：适用于注解的采样器。

ParameterizedSampler：适用于自定义采样规则的采样器。例如在http请求的跟踪中，可以建立只对特定请求进行拦截，或者不拦截等规则。

小结

以上，是对Tracing以及Tracer的初始化相关内容进行了介绍。Tracing控制了完整的服务追踪链，包括Tracing中属性说明，采样（Sampler），记录Span（Reporter）。在brave中。Tracing管理着Tracer，Tracer负责创建Spans，可以控制一个Span是否被采样，同时控制着Span的创建。

Span构建与管理

Span通过Tracer进行创建和管理。首先我们先看看Tracer类图，如下：

在Zipkin中，一个Trace中的Span是以树形的结构进行展示。Span与Span关系有两种，一种是“ChildOf”，即一个Span是一个父级Span的孩子；另一种是“FollowsFrom”，即一个Span与父级Span是平级，但是在这个父级Span的下面。

首先，我们先看看 Tracer 中创建Span的方法：

• 创建一个“ChildOf”关系的Span方法有：newChild(TraceContext)；
• 创建一个“FollowsFrom”关系的Span方法有：nextSpan(TraceContextOrSamplingFlags)、nextSpan()；
• 创建一个新的Span方法有：newTrace()；
• 根绝CurrentTraceContext获取Span的方法：currentSpan()；
• 根据TracContext创建一个Span方法：toSpan(TraceContext)；

以上创建一个Span的方法都是比较好理解的，还有一个方法 joinSpan(TraceContext)，它可以创建一个“ChildOf”关系的Span，也可以创建一个与父级Span相同且共享的Span，方法源码如下：

public final Span joinSpan(TraceContext context) {
        if (context == null) {
            throw new NullPointerException("context == null");
        }
        if (!supportsJoin) {
            return newChild(context);
        }
        // If we are joining a trace, we are sharing IDs with the caller
        // If the sampled flag was left unset, we need to make the decision here
        if (context.sampled() == null) { // then the caller didn't contribute data
            context = context.toBuilder().sampled(sampler.isSampled(context.traceId())).build();
        } else if (context.sampled()) { // we are recording and contributing to the same span ID
            recorder.setShared(context);
        }
        return toSpan(context);
    }

从Tracer源码来看，若 supportsJoin 参数为False，那么创建的为一个“ChildOf”关系的Span；反之，这个Span会与父级Span共用tracingId、spanId和parentId。

当 context.sampled() 为true时，这个Span就会在内存中设置为shared。（shared为true，不知道在什么情况下会使用。这个还有待在学习o(*￣︶￣*)o brave官方解释：Indicates we are contributing to a span started by another tracer (ex on a different host)）。

注意一点：如果在初始化Tracing，使用默认的Propagation.Factory，即B3Propagation.FACTORY，那么supportsJoin将永远为True；而Propagation.Factory#supportsJoin()返回的是false，那么joinSpan(TraceContext)返回的都是“ChildOf”关系的Span。

通过Tracer类的源码（这里就不将这个类完整的代码贴出），可知以上创建一个新的Span都是调用 toSpan(TraceContext) 方法生成。

Span管理

这里我们知道，可以通过父级的TraceContext构建一个“ChildOf”或者“FollowsFrom”关系的Span。但如果我们在不知道父级Span的情况下，如何可以构建一个与父级Span有正确关系的新Span呢？

例如，在一个应用程序系统中，要求跟踪Servlet拦截的请求以及对数据库的操作。如何管理好跟踪数据库操作的Span和拦截的请求的Span关系呢？

最差的方法是将拦截的请求的Span一层一层的传到访问数据库的方法中，但这样耦合度太高，不可取。我们知道一般处理这个请求的业务逻辑会在一个线程中进行，因此，Servlet拦截这个请求以及相应的数据库操作都会在一个线程中进行。这时就好办了，可以将Servlet的Span数据存入当前线程，在数据库操作记录Span时，我们就可以获取到这个父级的Span了。

下面从brave代码的角度来分析一下这个过程：

在父级Span的跟踪方法中，通过 Tracer#withSpanInScope(Span) 生成一个SpanInScope对象，或者通过Tracer#startScopedSpan(String) 或 Tracer#startScopedSpanWithParent(String, TraceConextext)生成一个ScopedSpan对象。这时，父级Span的TraceContext已植入Thread Local中，以供当前线程中其他跟踪方法获取父级Span的TraceContext（调用方法：ThreadLocalSpan.CURRENT_TRACER.next()或者ThreadLocalSpan.CURRENT_TRACER.next(TraceContextOrSamplingFlags)）。由SpanInScope或ScopedSpan管理父级Span的TraceContext是否由ThreadLocal中移除。

• TraceContext管理

Span的TraceContext通过CurrentTraceContext#newScope(TraceContext)方法置入ThreadLocal。我们先来看看CurrentTraceContext对象，以下是其类图。

在Brave core中，CurrentTraceContext.Default 和 StrictCurrentTraceContext 继承了CurrentTraceContext。在实例化时，它们都会有一个final类型的thread local。在Tracing类中，CurrentTraceContext的默认值为：CurrentTraceContext.Default.inheritable()，在CurrentTraceContext中会有一个final类型的inheritable thread local。以下是CurrentTraceContext.Default中newScope(TraceContext)实现。

public Scope newScope(@Nullable TraceContext currentSpan) {
    final TraceContext previous = local.get();
    local.set(currentSpan);
    class DefaultCurrentTraceContextScope implements Scope {
        @Override
        public void close() {
            local.set(previous);
        }
    }
    return new DefaultCurrentTraceContextScope();
}

再来看看Tracer中是如何调用的。

• startScopeSpanWithParent(String, TraceContext)

public ScopedSpan startScopedSpanWithParent(String name, @Nullable TraceContext parent) {
    if (name == null) {
        throw new NullPointerException("name == null");
    }
    TraceContext context = propagationFactory.decorate(newContextBuilder(parent, sampler).build());
    CurrentTraceContext.Scope scope = currentTraceContext.newScope(context);
    ScopedSpan result;
    if (!noop.get() && Boolean.TRUE.equals(context.sampled())) {
        result = new RealScopedSpan(context, scope, recorder, errorParser);
        recorder.name(context, name);
        recorder.start(context);
    } else {
        result = new NoopScopedSpan(context, scope);
    }
    return result;
}

由此得知，startScopeSpanWithParent(String, TraceContext)会生成一个新的TraceContext，这个TraceContext由当前线程的ThreadLocal管理，然后会生成一个ScopedSpan对象对Span进行管理。

以下是brave生成ScopedSpan，以及对当前TraceContext管理的完整实例。

// Note span methods chain. Explicitly start the span when ready.
ScopedSpan span = tracer.startScopedSpan("encode");
try {
    return encoder.encode();
} catch (RuntimeException | Error e) {
    span.error(e); // Unless you handle exceptions, you might not know the operation failed!
    throw e;
} finally {
    span.finish(); // finish - start = the duration of the operation in microseconds
}

ScopedSpan / SpanInScope控制着当前的TraceContext是否从ThreadLocal中移除。

先说说ScopedSpan。ScopedSpan是一个抽象类。它子类为NoopScopedSpan 和 RealScopedSpan。在没有数据进行记录时，使用NoopScopedSpan；反之，则使用RealScopedSpan。当Span完成跟踪，需要记录时，则调用finish()方法。在finish()方法中，则会调用Scope#close()将当前TraceContext从ThreadLocal中移除，恢复ThreadLocal的状态。

RealScopedSpan#finish()源码如下：

public void finish() {
    scope.close();
    recorder.finish(context);
}

• startScopedSpan(String)

startScopedSpan(String)同理，其调用startScopeSpanWithParent(String, TraceContext)实现。

• withSpanInScope(Span)

withSpanInScope(Span)创建了一个SpanInScope对象，传入的Span的TraceContext由ThreadLocal管理，与startScopeSpanWithParent(String, TraceContext)作用一样。

以下是ScopedSpan和SpanInScope的类图

               

ScopedSpan 和 SpanInScope 不同的地方在于：

ScopedSpan 对Span进行管理，通过finish()方法调用scope.close()和recorder.finish(TraceContext)，对ThreadLocal中的TraceContext进行恢复，以及记录Span的数据。

SpanInScope 对Span的TraceContext进行管理。当对象flush时，自动调用SpanInScope#close()，然后调用scope.close()。而recorder.finish(TraceContextt)调用，则是需要通过Span#finish()进行触发，完成Span的数据记录。

Tracing和Tracer的构建，以及Span构建和管理已说完。这里只是说了它们主要的流程，关于Propagation以及Sampler并没有提及太多。

P.S 如果有任何问题或者用词不当的地方，请指出，非常感谢o(*￣︶￣*)o