Brave核心lib
Brave是一个lib用于捕获，以及上报关于分布式操作的性能的信息到Zipkin。大多数用户不会直接时候Brave，而是把应用Brave到对应的框架上；
这个模块包含tracer（可以用来创建，并加入span），当然也包含一个lib去在不同的网络边界传播trace context（上下文），比如说http headers。
Setup
第一步，我们要配置一下，如何发送到Zipkin上。
如下是一个如何通过HTTP发送trace数据到Zipkin的一个样例：
// Configure a reporter, which controls how often spans are sent
// (this dependency is io.zipkin.reporter2:zipkin-sender-okhttp3)
sender = OkHttpSender.create("http://127.0.0.1:9411/api/v2/spans");
// (this dependency is io.zipkin.reporter2:zipkin-reporter-brave)
zipkinSpanHandler = AsyncZipkinSpanHandler.create(sender);
// Create a tracing component with the service name you want to see in Zipkin.
// 可以想见，一个tracing对应一个服务
tracing = Tracing.newBuilder()
.localServiceName("my-service")
.addSpanHandler(zipkinSpanHandler)
.build();
// Tracing exposes objects you might need, most importantly the tracer
// Tracing 暴露提供你需要的对象，最终要的是Tracer，tracer存在ThreadLocal中？
tracer = tracing.tracer();
// Failing to close resources can result in dropped spans! When tracing is no
// longer needed, close the components you made in reverse order. This might be
// a shutdown hook for some users.
tracing.close();
// tracing 应该是一个链路结束是关闭，ZipkinSpanHandler 和 sender 应该是系统结束前关闭！
zipkinSpanHandler.close();
sender.close();
Tracing
tracer创建并加入span。tracer可以通过设置采样率来控制发送到Zipkin的数据量。
tracer完成发送数据到Zipkin后，会返回Span。当开启一个span，你可以这个span添加关心的event和tag；
span包含context，可以用来标识它在分布式操作中的位置
// Start a new trace or a span within an existing trace representing an operation
ScopedSpan span = tracer.startScopedSpan("encode");
try {
// The span is in "scope" meaning downstream code such as loggers can see trace IDs
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(); // always finish the span
}
// Start a new trace or a span within an existing trace representing an operation
Span span = tracer.nextSpan().name("encode").start();
// Put the span in "scope" so that downstream code such as loggers can see trace IDs
try (SpanInScope ws = tracer.withSpanInScope(span)) {
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(); // note the scope is independent of the span. Always finish a span.
}
如上两个示例，作用是完全相同的，生成的span要么是一个全新的root span，要么是一个已存在的trace的子span；
定制span
一旦你获取到了span，你可以给span添加tag，tag可以很好的提现span的特性。比如说你可以给你的span添加你的运行时版本；
span.tag("clnt/finagle.version", "6.36.0");
当你蛮对各种各样的Span时，Tag类会对你有帮助。对于通用的或者重量级的tag，尝试使用Tag来定义并使用；
SUMMARY_TAG = new Tag<Summarizer>("summary") {
@Override protected String parseValue(Summarizer input, TraceContext context) {
return input.computeSummary();
}
}
// This works for any variant of span
SUMMARY_TAG.tag(summarizer, span);
当期望暴露自定义span的能力给第三方时，brave.SpanCustomizer会是比brave.Span更好的选择。前者更易于理解和测试，并且不会诱导用户去操作span的lifecycle hooks。
interface MyTraceCallback {
void request(Request request, SpanCustomizer customizer);
}
for (MyTraceCallback callback : userCallbacks) {
callback.request(request, span);
}
// Some DI configuration wires up the current span customizer
@Bean SpanCustomizer currentSpanCustomizer(Tracing tracing) {
return CurrentSpanCustomizer.create(tracing);
}
// user code can then inject this without a chance of it being null.
@Inject SpanCustomizer span;
void userCode() {
span.annotate("tx.started");
...
}
#### Remote spans Remote spans是指，同一个trace涉及到不同进程（服务），需要在进程间传递上下文信息；作为调用方，你通常需要： 1. 启用一个span，并加trace信息添加到request中 2. 把新的span放进到新的scope中 3. 指定调用 4. 捕获任何异常 5. 完结span
requestWrapper = new ClientRequestWrapper(request);
span = tracer.nextSpan(sampler, requestWrapper); // 1.
tracing.propagation().injector(ClientRequestWrapper::addHeader)
.inject(span.context(), requestWrapper);
span.kind(request.spanKind());
span.name("Report");
span.start();
try (Scope ws = currentTraceContext.newScope(span.context())) { // 2.
return invoke(request); // 3.
} catch (Throwable e) {
span.error(error); // 4.
throw e;
} finally {
span.finish(); // 5.
}
Sampling
Sampling可以减少被采样的span数，不采样的span标记为no overhead（noop）；
是否采样是一个up-front决定，意味着，是否采样是在trace第一次操作的时候就被决定的，并且这个决定会一直向下传播到整个trace；也就是一个trace要么整个被采样，要么整个不被采样；
你可以象如下一样自定义自己的sample策略：
tracing = Tracing.newBuilder()
.sampler(RateLimitingSampler.create(10))
--snip--
.build();
--------------------------------------------------------------------
SamplerFunction<Request> requestBased = (request) -> {
if (request.url().startsWith("/experimental")) {
return true;
} else if (request.url().startsWith("/static")) {
return false;
}
return null;
};
Span nextSpan(final Request input) {
return tracer.nextSpan(requestBased, input);
}
有些人可能希望基于java方法上的注释来决定是否采样。
// derives a sample rate from an annotation on a java method
SamplerFunction<Traced> samplerFunction = DeclarativeSampler.createWithRate(Traced::sampleRate);
@Around("@annotation(traced)")
public Object traceThing(ProceedingJoinPoint pjp, Traced traced) throws Throwable {
// When there is no trace in progress, this overrides the decision based on the annotation
ScopedSpan span = tracer.startScopedSpan(spanName(pjp), samplerFunction, traced);
try {
return pjp.proceed();
} catch (RuntimeException | Error e) {
span.error(e);
throw e;
} finally {
span.finish();
}
}
Baggage
有时候，你需要传递额外的字段；比如说，你需要知道一个具体请求的countryCode，你能通过HTTP头来传递；
import brave.baggage.BaggagePropagationConfig.SingleBaggageField;
// Configure your baggage field
COUNTRY_CODE = BaggageField.create("country-code");
// When you initialize the builder, add the baggage you want to propagate
tracingBuilder.propagationFactory(
BaggagePropagation.newFactoryBuilder(B3Propagation.FACTORY)
.add(SingleBaggageField.remote(COUNTRY_CODE))
.build()
);
// Later, you can retrieve that country code in any of the services handling the trace
// and add it as a span tag or do any other processing you want with it.
countryCode = COUNTRY_CODE.getValue(context);
只要字段是通过BaggagePropagation配置的，就可以本地区读取或者更新；
COUNTRY_CODE.updateValue("FO");
String countryCode = COUNTRY_CODE.getValue();
//or
COUNTRY_CODE.updateValue(span.context(), "FO");
String countryCode = COUNTRY_CODE.get(span.context());
Tags.BAGGAGE_FIELD.tag(COUNTRY_CODE, span);