ARMS Java SDK (not recommended)

Usage

For agent versions 4.x and later, we recommend using the OpenTelemetry Java SDK for custom instrumentation and to obtain trace context:

• Manually instrument applications with the OpenTelemetry Java SDK

• Propagate context in intra-process asynchronous scenarios by using the OpenTelemetry Java SDK

• Propagate context across processes by using the OpenTelemetry Java SDK

Using the ARMS SDK for custom instrumentation or to obtain trace context is not recommended unless you cannot upgrade to a version 4.x agent.

Prerequisites

• You have enabled Application Monitoring for your application in the ARMS console and started the agent in your Java application. For more information, see Manually install an agent.

• Your application includes the arms-sdk-1.7.3.jar dependency.

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

  Note

  If you cannot obtain the dependency from the pom.xml file, download arms-sdk-1.7.3.jar.

Get the trace ID and RPC ID

Use the following code to get the trace ID and RPC ID.

Span span = Tracer.builder().getSpan();   // This does not create a new span.
String traceId = span.getTraceId();
String rpcId = span.getRpcId();

Propagate custom baggage

To propagate custom baggage, add code to set and get the items as follows:

1. Add custom baggage in your application code.

   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. Get the custom baggage from your application code.

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

3. For agent versions 4.x and later, baggage is only propagated. The agent does not automatically add this content to the tags of each span. If you need this data in the tags, you must manually set a custom tag for a span.

Set custom tags for a span

Tags apply only to the specific span on which they are set and are not propagated to other spans. To set and get custom tags, follow these steps:

1. Add custom tags to a span in your application code. You can add multiple tags.

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

2. Get the custom tags of a span.

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

Query traces by custom baggage and tags

Use the custom baggage and tags set on a span to query traces.

• Baggage is propagated to downstream services and is typically used for business context propagation. Avoid setting an excessive number of baggage items.

• A tag applies only to the current span. You can set multiple tags for business data.

1. Log in to the ARMS console. In the left-side navigation pane, select Application Monitoring > Trace Query.

2. On the Trace Query page, select the target region at the top. Then, select a Parameter Type, enter the custom tag value in the Parameter Value field, and click Add to Query Condition.

3. In the list of traces, click the Trace ID of the target trace.

4. On the Traces details page, hover over the Service Name column to view the tags for the current span.

   For example, the custom tags tag-userid (with the value 123456789) and tag-bu (with the value taobao) are added to the span's tags.

5. For agent versions 4.x and later, to write baggage content to a span, first retrieve all baggage items as described in Propagate custom baggage. Then, write them to the span using the method described in Set custom tags for a span.