ARMS Java SDK使用說明 - Application Real-Time Monitoring Service

藉助ARMS提供的SDK，您可以在業務代碼中動態擷取TraceId及相關調用鏈屬性。

使用說明

對於4.x版本探針，推薦優先使用OpenTelemetry Java SDK進行自訂埋點和擷取鏈路上下文資訊：

如非特殊情況無法升級4.x探針，不再推薦使用ARMS SDK進行自訂埋點以及擷取Trace上下文資訊。

前提條件

已在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

說明

對於在spring-cloud-gateway中通過filter方式增加baggage情境，當探針升級到4.2.x版本並在自訂配置中開啟spring-bean外掛程式後，baggage透傳功能會失效。如需使用baggage透傳功能，請關閉spring-bean外掛程式或者降級探針到4.1.x及以下版本。

若您要透傳業務自訂標籤，則需要在代碼中寫入添加和擷取自訂標籤，具體操作步驟如下：

在業務代碼中添加自訂標籤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);

在業務代碼中擷取自訂標籤baggage。

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

在4.x及更高版本的探針中，Baggage僅具備透傳能力，內容不會自動加入到每個Span的Tags中。如有需要，請手動為Span設定自訂標籤tag。

為Span設定自訂標籤tag

為Span設定自訂標籤只會在當前Span中有效，並不會透傳。您需要在代碼中寫入添加和擷取自訂的標籤，具體操作步驟如下：

在業務代碼中為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");

在業務代碼中擷取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範圍內有效，可以設定多個業務項。

登入ARMS控制台，在左側導覽列選擇應用監控 > 調用鏈路查詢。
在調用鏈路查詢頁面頂部選擇目標地區，然後選擇參數類型，在參數值中填入自訂標籤，單擊添加到查詢條件。
在調用鏈列表中單擊目標鏈路的TraceID。
在調用鏈路詳情頁面，滑鼠移動至服務名稱，會顯示當前Span對應的Tags資訊。
對於4.x及更高版本的探針，如果希望將Baggage的內容寫入到您的Span上，可以參考上文透傳業務自訂標籤baggage中的方式擷取到所有的baggage，並通過為Span設定自訂標籤tag寫入到Span中。