OpenTracing的使用实例（Java）-阿里云开发者社区

构件组织

OpenTracing API的Java构件如下：

opentracing-api：主要的API，无其他依赖。
opentracing-noop：为主要API提供无意义实现（NoopTracer），依赖于opentracing-api。
opentracing-util：工具类，例如GlobalTracer和默认的基于ThreadLocal存储的ScopeManager实现，依赖于上面所有的构件。
opentracing-mock：用于测试的mock层。包含MockTracer，简单的将Span存储在内存中，依赖于opentracing-api和opentracing-noop。

安装（Maven）

<dependency>
    <groupId>io.opentracing</groupId>
    <artifactId>opentracing-api</artifactId>
    <version>VERSION</version>
</dependency>

也可以使用opentracing-noop，opentracing-mock，opentracing-util来安装其他的构件，如果安装多个构件，需要提供一致的VERSION。

主要API

主要的OpenTracing API将所有主要组件声明为接口以及辅助类，例如Tracer，Span，SpanContext，Scope，ScopeManager，Format（用映射定义通用的SpanContext注入和提取格式）。

OpenTracing 社区贡献

除了官方的API，也有一些苦在opentracing-contribe，保管通用的辅助类像TracerResolver和框架工具库，例如 Java Web Servlet Filter and Spring Cloud，可以用于在使用这些框架工具的项目中方便的集成OpenTracing。

Quick Start

下面使用opentracing-mock中的MockTracer来进行示例：

import java.util.Map;
import io.opentracing.mock.MockTracer;
import io.opentracing.mock.MockSpan;
import io.opentracing.tags.Tags;

// Initialize MockTracer with the default values.
MockTracer tracer = new MockTracer();

// Create a new Span, representing an operation.
MockSpan span = tracer.buildSpan("foo").start();

// Add a tag to the Span.
span.setTag(Tags.COMPONENT, "my-own-application");

// do something for business logic

// Finish the Span.
span.finish();

// Analyze the saved Span.
System.out.println("Operation name = " + span.operationName());
System.out.println("Start = " + span.startMicros());
System.out.println("Finish = " + span.finishMicros());

// Inspect the Span's tags.
Map<String, Object> tags = span.tags();

使用Span

在任何时间点，OpenTracing Java API仅允许同一个线程中只存在一个活跃的Span。但是在同一个线程中允许同时存在符合下述条件的Span：

Started，新建的Span，但是没有在任何作用域（Scope）中激活
Not Finished，调用finish方法之前均处于该状态
Not Active，未被激活

同一个线程上可能有多个Span，如果它们：

正在等待I/O操作完成
被子Span阻塞
或被溢出关键路径

人工地将活跃的Span从一个函数传递到另一个函数是极为不便的，所以OpenTracing要求每个Tracer包含一个作用域管理器（ScopeManager）。ScopeManager可以通过Scope来方法激活的Span，Scope来管理Span的激活与失活。ScopeManager API运行将Span传到到另一个线程或回调，而不是传递Scope。

开发这在创建新的Span时，如果当前线程的Scope中已经存在活跃的Span，则该活跃Span则会成为新创建Span的父亲，除非开发者在buildSpan()时调用ignoreActiveSpan()或者明确指定父上下文（parent context）。

访问活跃的Span

开发者可以通Scope对象访问活跃的Span

io.opentracing.Tracer tracer = ...;
...
Scope scope = tracer.scopeManager().active();
if (scope != null) {
    scope.span().log("...");
}

在线程间移动Span

使用OpenTracing API，开发者可以在多个不同的线程间传输Span。一个Span的生命周期可以在一个线程中开始在另一个线程中结束。不支持传递Scope到另一个线程或回调。Span的内部时序细节看来如下：

[ ServiceHandlerSpan                                 ]
 | FunctionA |     waiting on an RPC      | FunctionB |

---------------------------------------------------------> time

当执行FunctionA和FunctionB时ServiceHandlerSpan是活跃的，但是在等待RPC调用的过程中是失活的。RPC可能有自己的Span，但我们现在只关注ServerHandlerSpan如何从FunctionA传播到FunctionB。使用ScopeManager API可以在FunctionA中获取Span，RPC结束后在FunctionB中重新获取Span。步骤如下：

通过startManager或startActive(false)方法创建一个Span以阻止Scope失活时令Span终止。
在回调代码（闭包/Runnable/Future）中调用tracer.scopeManager().active(span,false)来重新激活Span获取一个新的Scope，当Span不再活跃时关闭Scope（或者使用try-with-resources以简化代码）
在回调代码末尾，调用tracer.scopeManager().active(span,true)来重新激活Span并得到一个自动关闭的Scope。

代码如下：

io.opentracing.Tracer tracer = ...;//通过具体的实现来创建tracer对象
...
// STEP 1 ABOVE: 开启新的Span和Scope
try (Scope scope = tracer.buildSpan("ServiceHandlerSpan").startActive(false)) {
    // Span在Scope中被激活
    final Span span = scope.span();
    doAsyncWork(new Runnable() {
        @Override
        public void run() {

            // STEP 2 ABOVE: 重新激活Span
            // 如果需要自动终止激活的Span，传递true给active方法
            try (Scope scope = tracer.scopeManager().activate(span, true)) {
                ...
            }
        }
    });
}

通过框架的拦截器能力实现HTTP请求追踪

通过上文中的代码，我们知道了如何使用Tracer对象构建Span，如何在线程中激活Span，以及如何在异步环境的不同线程间传递Span。

在实际的业务开发中，我们很难使用这种侵入的方式来实现追踪，更多的是利用各种框架提供的拦截器机制，来对各种业务调用进行自动追踪，比如Spring AOP，Servlet Filter，等等。下面一段代码展示了如何通过Servlet Filter来进行服务端的HTTP请求追踪。

@Override
public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain chain)
        throws IOException, ServletException {

    HttpServletRequest httpRequest = (HttpServletRequest) servletRequest;
    HttpServletResponse httpResponse = (HttpServletResponse) servletResponse;

        // 从Http Headers中提取上下文
    SpanContext extractedContext = tracer.extract(Format.Builtin.HTTP_HEADERS,
            new HttpServletRequestExtractAdapter(httpRequest));

      // 创建并激活一个新的Span，如果前面提取到的上下文不为null，则作为父SpanContext
    final Scope scope = tracer.buildSpan(httpRequest.getMethod())
            .asChildOf(extractedContext)
            .withTag(Tags.SPAN_KIND.getKey(), Tags.SPAN_KIND_SERVER)
            .startActive(false);
        final Span span = scope.span();
    
    // 追踪请求的地址
    span.setTag(Tags.HTTP_URL, httpRequest.getRequestURI());
    try {
        // 实际执行过滤器链处理请求
        chain.doFilter(servletRequest, servletResponse);
    } finally {
         if (httpRequest.isAsyncStarted()) {
             // 如果请求是异步的，那么需要将Span对象传递到异步回调中
             httpRequest.getAsyncContext()
                     .addListener(new AsyncListener() {
                 @Override
                 public void onComplete(AsyncEvent event) throws IOException {
                     // 回调是在异步线程中执行的
                     // 需要使用Scope在异步先线程中激活Span
                     try(Scope sc = tracer.scopeManager().activite(span, true)){
                         HttpServletResponse httpResponse = (HttpServletResponse) event.getSuppliedResponse();
                         // 追踪响应状态 
                         sc.span().setTag(Tags.HTTP_STATUS, httpResponse.getStatus());
                     }
                 }

                 @Override
                 public void onTimeout(AsyncEvent event) throws IOException {
                     try(Scope sc = tracer.scopeManager().activite(span, true)){
                         // 记录错误
                         sc.span().setTag(Tags.ERROR, true)
                         sc.span().log(Maps.of(Fields.EVENT, event，
                                      Fields.ERROR_KIND, "TIMEOUT"))
                     }
                 }

                 @Override
                 public void onError(AsyncEvent event) throws IOException {
                     try(Scope sc = tracer.scopeManager().activite(span, true)){
                         // 记录错误
                         sc.span().setTag(Tags.ERROR, true)
                         sc.span().log(
                             Maps.of(Fields.EVENT, event，
                                     Fields.ERROR_KIND, event.getThrowable().getClass()))
                     }
                 }

                 @Override
                 public void onStartAsync(AsyncEvent event) throws IOException {
                 }
             });
         } else {
             // 如果是同步请求，直接终止Span
             scope.span().finish();
         }
         // 释放当前线程中的Span
         scope.close();
    }
}

利用这个过滤器，在Servlet应用中，用于追踪请求代码与业务代码解耦，并且仅需要一次编写，下面来看客户端如何追踪请求并向处理请求的服务端传递上下文，以Spring RestTemplate为例：

可以通过RestTemplate.setInterceptors注册拦截器。

@Override
public ClientHttpResponse intercept(HttpRequest httpRequest, byte[] body,
                                    ClientHttpRequestExecution execution) throws IOException {
    
    // 创建新的Span，以当前线程中的SpanContext为父，如没有则自己成为根Span
    try (Scope scope = tracer.buildSpan(httpRequest.getMethod().toString())
            .withTag(Tags.SPAN_KIND.getKey(), Tags.SPAN_KIND_CLIENT).startActive(true)) {
        // 追踪请求地址
        scope.span().setTag(Tags.HTTP_URL, httpRequest.getURI().toString())
        // 将SpanContext注入到请求头中
        // 看前文中的代码可以知道，服务端通过Tracer.extract可以从请求头中提取出SpanContext
        tracer.inject(scope.span().context(), Format.Builtin.HTTP_HEADERS,
                new HttpHeadersCarrier(httpRequest.getHeaders()));
        
        // 实际执行请求
        return execution.execute(httpRequest, body);
    }

}

使用opentracing-spring-cloud

上文中通过代码示例了，如何通过框架工具提供的拦截器能力来实现请求追踪，由于Spring MVC，RestTemplate，Servlet……这些开源工具是的用户相当广泛，所以在opentracing-contrib项目中提供了非常多针对这些被广泛使用的开源工具的集成支持包。

其中java-spring-cloud子项目，为spring-cloud项目提供了opentracing-spring-cloud-starter，这个starter通过依赖了很多其他的opentrcing集成支持库，来为基于spring-cloud架构的应用提供一站式opentracing集成方案，其中包括如下组件：

利用SpringBoot的AutoConfiguration机制为用户提供了几乎无须手动配置的集成方案。

Spring Web (RestControllers, RestTemplates, WebAsyncTask, WebClient, WebFlux)
@Async, @Scheduled, Executors
WebSocket STOMP
Feign, HystrixFeign
Hystrix
JMS
JDBC
Mongo
Zuul
Reactor
RxJava
Redis
Standard logging - logs are added to active span
Spring Messaging - trace messages being sent through [Messaging Channels]
RabbitMQ

使用SpringCloud的开发者，可以简单的将opentracing-spring-cloud-starter添加到自己项目的依赖中，来体验它带来的opentracing集成。

如果不使用SpringCloud也可以其为起点，按自己的需求从其依赖中挑选自己需要的部分，或者浏览opentracing-contrib项目来寻找自己需要的支持库。

使用Jaeger

前文中描述的API以及中间件集成方案，都是对OpenTracing API的集成，仔细看代码中缺少一个必要的构建Tracer对象的步骤。在实际场景中，我们需要一种具体的OpenTracing实现，来创建Tracer对象。

Jaeger是由Uber开源的OpenTracing实现项目，它提供了追踪数据上报服务以及数据的视图，来帮助开发者解决分布式系统中的如下问题：

分布式事务监控
性能和延迟优化
分析故障源头
服务以来分析
分布式上下文传播

以来jaeger-client-java可以利用如下代码创建一个Tracer对象：

Configuration config = new io.jaegertracing.Configuration("服务名称");
// 设置数据发送方式
Configuration.SenderConfiguration sender = new Configuration.SenderConfiguration();
sender.withEndpoint("<endpoint>"); // endpoint可以是在阿里云上购买的链路追踪服务或者自己使用Jaeger搭建的服务
// 设置采样方式
config.withSampler(new Configuration.SamplerConfiguration().withType("const").withParam(1));
// 设置数据上报方式
config.withReporter(new Configuration.ReporterConfiguration().withSender(sender).withMaxQueueSize(10000));
Tracer tracer = config.getTracer();

Configuration类提供了非常多的配置功能，有兴趣的开发者可以阅读其API文档来了解更多的自定义选项，甚至扩展Jaeger的功能。

OpenTracing的使用实例（Java）

构件组织

安装（Maven）

主要API

OpenTracing 社区贡献

Quick Start

使用Span

访问活跃的Span

在线程间移动Span

通过框架的拦截器能力实现HTTP请求追踪

使用opentracing-spring-cloud

使用Jaeger

热门文章

最新文章

相关课程

相关电子书

相关实验场景