操作指南

API 文档

调用链快速入门

最近更新时间:2020-08-03 17:02:26

为了节约用户的开发成本和提升使用效率,TSF 提供了 Spring Cloud 全链路跟踪的组件。用户只需要在代码中配置组件依赖,即可直接使用 TSF 的全链路跟踪功能,无需关心日志采集、分析、存储等过程。 用户仅需要安装了对应的依赖包及添加依赖项即可,无须其他配置。

准备工作

开始实践调用链功能前,请确保已完成 SDK 下载

依赖项

向工程中添加 spring-cloud-tsf-starter 依赖并开启 @EnableTsf 注解,详情请参考 快速入门 文档。

注意:

如果您使用的是 1.15.0-Edgware-RELEASE/1.15.0-Finchley-RELEASE 及之前的版本,使用方法参考 Spring Cloud SDK 历史版本使用方法

微服务对下游组件访问的链路支持

微服务对 Redis、MySQL、MongoDB、消息队列 CMQ 的访问操作会产生跟踪日志, TSF 会对该日志进行采集、分析、统计,这些组件的调用会展现在 TSF 平台的链路追踪中。具体使用说明如下:

说明:

非微服务组件的链路支持功能依赖于1.14.0版本及以上版本的 SDK,详情请参考 SDK 更新日志

标签与自定义元数据

调用链支持用户在代码中设置标签(Tag) 和自定义元数据(CustomMetada),分别用于调用链的筛选和附带业务信息。

接口定义:

public class TsfContext {
    /**
     * 设置多个 Tag。如果有某个 Tag 之前已经被设置过,那么它的值会被覆盖。
     */
    public static void putTags(Map<String, String> tagMap, TagControlFlag... flags) {}

    /**
     * 设置 Tag。如果该 key 之前已经被设置过,那么它的值会被覆盖。
     */
    public static void putTag(String key, String value, TagControlFlag... flags) {}

    /**
     * 设置 CustomMetadata。
     */
    public static void putCustomMetadata(Object customMetadata)
}

注入和获取 trace 信息

TSF SDK1.23 及之后版本,支持注入和获取 traceId、spanId、tag 信息。

说明:

  • traceId、spanId 格式不建议自定义,可能有未知错误。
  • TSF 不保证注入后调用链的正确性。

E 版本 SDK 使用方式

 private static final Logger LOG = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass()); 
 @Autowired
 private Tracer tracer;

 public void addSpan() throw Exception{
     //获取 traceId、spanId、tag
        Span oldSpan = tracer.getCurrentSpan();
        String traceId = oldSpan.getTraceId();
        String spanId = oldSpan.getSpanId();
        Map<String, String> tags = oldSpan.tags();
        LOG.info("traceId: {}, spanId: {}", traceId, spanId);
        for (String key : tags.keySet()) {
            LOG.info("key: {}, value: {}", key, tags.get(key));
        }

        //设置 tag
        tracer.addTag("http.method","get");
        Map<String, String> tags1 = tracer.getCurrentSpan().tags();
        for (String key : tags1.keySet()) {
            LOG.info("key: {}, value: {}", key, tags1.get(key));
        }

        //设置 traceId、spanId(必须先新建 span)
        Span.SpanBuilder spanBuilder = Span.builder();
        Span span = spanBuilder.name("mockName").traceId(UUID.randomUUID().toString()).spanId(UUID.randomUUID().toString()).tag("key", "value").build();

        tracer.continueSpan(span);

        Span newSpan = tracer.getCurrentSpan();
        String newTraceId = newSpan.getTraceId();
        String newSpanId = newSpan.getSpanId();

        LOG.info("traceId: {}, spanId: {}", newTraceId, newSpanId);
 }

F、G 版本 SDK 使用方式

    private static final Logger LOG = LoggerFactory.getLogger(MethodHandles.lookup().lookupClass());
    @Autowired
    private Tracing tracing; 

   public void addSpan() throw Exception{
      TraceContext traceContext = tracing.tracer().currentSpan().context();

        TraceContext context = traceContext.toBuilder().traceId(2035873338086630653L).spanId(-2035873338086630653L).build();

        CurrentTraceContext currentTraceContext = tracing.currentTraceContext();
        currentTraceContext.newScope(context);

        Span spanCur = tracing.tracer().currentSpan();


        long traceId1 = spanCur.context().traceId();
        long spanId1 = spanCur.context().spanId();
        LOG.info("traceId1:{},spanId1:{}",traceId1, spanId1);


        //添加tag
        spanCur.tag("qx-test1","value");
        spanCur.tag("qx-test2","value");
        spanCur.tag("qx-test1","value");

        //获取tag
        Field state1 = spanCur.getClass().getDeclaredField("state");
        state1.setAccessible(true);
        MutableSpan mutableSpan1 = (MutableSpan)state1.get(spanCur);
        Field tags1 = mutableSpan1.getClass().getDeclaredField("tags");
        tags1.setAccessible(true);
        ArrayList<String> list1 = (ArrayList<String>) tags1.get(mutableSpan1);
        String key1 =null, value1 =null;
        for (int i = 0, length = list1.size(); i < length; i += 2) {
            key1 =  list1.get(i);
            value1 = list1.get(i + 1);

            LOG.info("tags key1: {}, value1: {}", key1, value1);
        }

        //获取 traceid、spanid
        TraceContext traceContext1 = spanCur.context();
        long traceId2 = traceContext1.traceId();
        long spanId2 = traceContext1.spanId();
        LOG.info("traceId1:{},spanId1:{}",traceId2, spanId2);
    }
目录