ARMS Java SDK使用说明

前提条件

• 已在ARMS控制台上创建应用监控，并已在Java程序中挂载和启动应用监控的探针。具体操作，请参见手动安装探针。

• 程序中已引入arms-sdk-1.7.3.jar依赖。

  <dependency>
      <groupId>com.alibaba.arms.apm</groupId>
      <artifactId>arms-sdk</artifactId>
      <version>1.7.3</version>
  </dependency>

  说明

  如果无法获取pom.xml中的依赖，请直接下载arms-sdk-1.7.3.jar。

获取TraceId与RpcId

您可通过以下代码获取TraceId与RpcId。

Span span = Tracer.builder().getSpan();   //此处未创建新的Span。
String traceId = span.getTraceId();
String rpcId = span.getRpcId();

透传业务自定义标签baggage

若您要透传业务自定义标签，则需要在代码中写入添加和获取自定义标签，具体操作步骤如下：

1. 在业务代码中添加自定义标签baggage。

   Map<String, String> baggage = new HashMap<String, String>();
   baggage.put("key-01", "value-01");
   baggage.put("key-02", "value-02");
   baggage.put("key-03", "value-03");
   Span span = Tracer.builder().getSpan();
   span.withBaggage(baggage);

2. 在业务代码中获取自定义标签baggage。

   Span span = Tracer.builder().getSpan();
   Map<String, String> baggage = span.baggageItems();

3. 在4.x及更高版本的探针中，Baggage仅具备透传能力，内容不会自动加入到每个Span的Tags中。如有需要，请手动为Span设置自定义标签tag。

为Span设置自定义标签tag

为Span设置自定义标签只会在当前Span中有效，并不会透传。您需要在代码中写入添加和获取自定义的标签，具体操作步骤如下：

1. 在业务代码中为Span添加自定义标签tag，可以添加多个标签。

   Span span = Tracer.builder().getSpan();
   // Add a tag to the Span.
   span.setTag("tag-key1", "tag-value1");
   span.setTag("tag-key2", "tag-value2");

2. 在业务代码中获取Span自定义标签tag。

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

根据自定义标签baggage和tag查询调用链

通过Span设置的自定义标签baggage和tag可以用来按标签维度查询调用链。

• baggage上的标签具有透传到下游效果，一般用于业务染色，标签项不建议设置过多。

• tag上的标签只在本Span作用域内有效，可以设置多个业务项。

1. 登录ARMS控制台，在左侧导航栏选择应用监控 > 调用链路查询。

2. 在调用链路查询页面顶部选择目标地域，然后选择参数类型，在参数值中填入自定义标签，单击添加到查询条件。

3. 在调用链列表中单击目标链路的TraceID。

4. 在调用链路详情页面，鼠标移动至服务名称，会显示当前Span对应的Tags信息。

   

5. 对于4.x及更高版本的探针，如果希望将Baggage的内容写入到您的Span上，可以参考上文透传业务自定义标签baggage中的方式获取到所有的baggage，并通过为Span设置自定义标签tag写入到Span中。