ARMS SDKs for Java - Application Real-Time Monitoring Service

This topic describes how to use Application Real-Time Monitoring Service (ARMS) SDKs to dynamically obtain a trace ID and the properties of the trace from the service code.

Note

ARMS allows you to use OpenTelemetry SDK for Java to instrument and monitor your application. We recommend that you use OpenTelemetry SDK for Java to instrument your application. For more information, see Use OpenTelemetry SDK for Java to add custom instrumentation code to traces.

Prerequisites

Your Java application is connected to ARMS. The ARMS agent for application monitoring is installed and started in the application. For more information, see Manually install an ARMS agent.
arms-sdk-1.7.3.jar is introduced to the 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 the pom.xml file, download arms-sdk-1.7.3.jar.

Obtain a trace ID and an RPC ID

You can run the following code to obtain a trace ID and a remote procedure call (RPC) ID:

Span span = Tracer.builder().getSpan();   // A span is not created.
String traceId = span.getTraceId();
String rpcId = span.getRpcId();

Pass through custom baggage items

To pass through custom baggage items, you must perform the following steps to add the items to and obtain the items from the service code:

Add baggage items to the service 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);

Obtain the baggage items from the service code.

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

(Optional) Add custom tags to the span. For more information, see Add custom tags to a span. In an ARMS agent V4.x or later, baggage items can only be passed through, but not be added to the tags of each span.

Add custom tags to a span

You can add a custom tag only to the current span. You cannot pass a custom tag to other spans. To add custom tags to a span, perform the following steps to add the tags to and obtain the tags from the service code:

Add tags to a span in the service code. You can specify 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");

Obtain the tags from the service code.

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

Query traces based on baggage items and tags

You can use baggage items and tags that are added to a span to query traces.

A baggage item can be passed to the downstream and is generally used to color business data. We do not recommend that you specify a large number of baggage items.
A tag applies only to the current span. You can add multiple tags to a span.

Log on to the ARMS console. In the left-side navigation pane, choose Application Monitoring > Trace Query.
On the Trace Query page, select a region in the top navigation bar, and then select a value from the Parameter type drop-down list. Enter a value in the Parameter value field, and click Add to query criteria.
In the returned results, find the trace that you want to query and click the trace ID.
On the Traces tab, move the pointer over the value in the Service column to view the tags and baggage items of the current span.
(Optional) To add baggage items to the tags of the span in an ARMS agent V4.x or later, retrieve all baggage items by referring to Pass through custom baggage items, and add them to the span by referring to Add custom tags to a span.