Application Real-Time Monitoring Service:ARMS SDK for Java (deprecated)

Usage notes

For agents v4.x or later, use the OpenTelemetry Java SDK for custom instrumentation and to retrieve trace context:

• Use the OpenTelemetry Java SDK for custom instrumentation

• Use the OpenTelemetry Java SDK to propagate context in intra-process asynchronous scenarios

• Use the OpenTelemetry Java SDK to propagate context across processes

Only use the ARMS SDK if you cannot upgrade to a 4.x agent. For all other scenarios, use the OpenTelemetry Java SDK for custom instrumentation and to retrieve trace context.

Prerequisites

• In the ARMS console, enable Application Monitoring for your application, and install and start the agent in your Java application. For more information, see Install an agent manually.

• Include the arms-sdk-1.7.3.jar dependency in your application.

  <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 pom.xml, download arms-sdk-1.7.3.jar.

Retrieve trace and RPC IDs

Use the following code to retrieve a trace ID and an 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 retrieve it as shown in the following steps:

1. Set custom 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. Retrieve the custom baggage.

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

3. In agents of version 4.x and later, baggage is used only for propagation. Its content is not automatically added to the tags of each Span. If required, you must manually set a custom tag for a Span.

Set custom span tags

A custom tag is valid only for the Span on which it is set and is not propagated. Add and retrieve custom tags as follows:

1. In your application code, add one or more custom tags to a Span.

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

2. In your application code, retrieve the custom tags of a Span.

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

Query by custom baggage and tags

You can query traces using the custom baggage and tags set on a Span.

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

• A tag is valid only within the current Span. You can add multiple business-related items as tags.

1. Log in to the ARMS console. In the navigation pane on the left, choose Application Monitoring > Trace Query.

2. On the Trace Query page, select a region at the top of the page. Then, select a Parameter type, enter the custom tag in the Parameter value field, and click Add to query criteria.

3. In the list of traces, click the trace ID of the desired trace.

4. On the Trace details page, hover over a service name to view the tags for that Span.

   

5. For agent v4.x and later, to include baggage in a Span, retrieve the baggage and then set it as a custom tag. See Propagate custom baggage and Set a custom tag for a Span.