Skywalking-Agent-Tracer-API设计文档

一、前景提要

SkyWalking Java是一个强大的、实现完善的agent，其通过改变需要监控软件的字节码，在其中插桩来收集metric、trace、log以及event这四种监控数据的代码，并支持发送到各种各样的oap，比如skywalking原生的oap。对于skywalking-agent，一开始人们常常选择使用其支持的各种各样的自动插桩（比如对于spring、dubbo、rocketmq等等），但是随着其被越来越多的人使用，很多用户想要使用其来进行手动的插桩，即通过调用api的方式在其想要的问题收集数据。在过去我们支持使用opentracing的api，但是考虑到opentracing现在已经合并到了OpenTelemetry中去了，我们考虑构建属于skywalking自己的trace api。对于skywalking的trace指标，主要涉及到下面几种功能：

创建span
对于rpc tracing上下文信息的注入和提取
捕捉和提取跨线程tracing的上下文
为当前的span输入tag和log信息（tag是一个键值对，log是日志信息）
跨线程span的异步准备和完成（类似于操作系统中wait和notify）

二、设计方案

2.1 遗弃的设计方案（基于注解的）

对于span的创建，使用注解@LocalSpan, @EntrySpan, @ExitSpan来进行标注
对于rpc tracing上下文信息的注入和提取，基于注解，使用某些方式去传递contextCarrier（也就是上下文信息）
对于捕捉和提取跨线程tracing的上下文，定义capture() and continued()这两个api
对于tag和log的功能，为span定义log()和tag()这两个api
对于异步准备/完成，使用prepareForAsync()和asyncFinish()

遗弃原因：不希望基于注解，基于注解实现过于困难

2.2 实行的设计方案（之后略有改动）

Span creating

public class TracerManager{
    public static void createEntrySpan(String operationName, Object message){}
    public static void createLocalSpan(String operationName){}
    public static void createExitSpan(String operationName, Object message, String remotePeer){}
    public static void createExitSpan(String operationName, String remotePeer){}
    public static void stopSpan(){}
}

Inject/extract for RPC tracing

// Question: how to pass the ContextCarrier
// Answer: use message to encapsulate the ContextCarrier
public class TracerManager{
    ...
    public static void inject(Object message){}
    public static void extract(Object message){}
}

Capture/continue for continue tracing context in the x-thread tracing

public class TracerManager{
    ...
    public static ContextSnapshot capture(){}
    public static void continued(ContextSnapshot snapshot){}
}

Tag and log for the current span

public class CurrentSpan{
    public static void log(Throwable t){}
    public static void log(Map<String, ?> event){}
    public static void tag(String key, String value){}
    public static void tag(AbstractTag<?> tag, String value){}
}

Async prepare/finish for span crossing threads

public class newAsyncSpan{
    ...
    public newAsyncSpan prepareForAsync(); 
    public newAsyncSpan asyncFinish();
}

2.3 方案的主要改进点

使用一个指向span的引用来代替CurrentSpan这个类，这样就不用每次都调用activeSpan这个方法了。

三、API介绍

官方文档就是我写的，这里也就简单做个分类然后直接引用了。

引入Tracer API的依赖
使用Tracer API，这里包含了上面提到的五种功能
Tracing APIs目录下剩余的文档都是老的api介绍