ARMS エージェントは、一般的な Java フレームワークを自動的にインストルメンテーションし、コードを変更することなくトレースデータを収集します。トレースでカスタムビジネスメソッドの実行をキャプチャするには、Java 用 OpenTelemetry SDK を使用して手動でインストルメンテーションを追加し、スパンの作成、属性の設定、Baggage の伝播、およびトレースコンテキストへのアクセスを行います。
ARMS がサポートするコンポーネントとフレームワークの詳細については、「Application Monitoring のネットワーク設定」をご参照ください。
前提条件
お使いのアプリケーションが Application Monitoring (ARMS) でモニタリングされていること。
ARMS エージェントが V2.9.1.2 以降であること。アップグレードするには、「ARMS エージェントのアップグレード」をご参照ください。エージェント V2.x および 3.x はサポート終了 (EOL) となっているため、エージェントバージョン 4.x 以降にアップグレードすることを推奨します。詳細については、「ARMS エージェントのライフサイクルに関するお知らせ」をご参照ください。V4.x 以降は OpenTelemetry フレームワークをベースに構築されており、V2.x および 3.x よりも包括的な OpenTelemetry との互換性を備えています。
依存関係の追加
Java 用 OpenTelemetry SDK に、次の Maven 依存関係を追加します。詳細については、「インストルメンテーション」をご参照ください。
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-api</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk-trace</artifactId>
</dependency>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-sdk</artifactId>
</dependency>
</dependencies>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.opentelemetry</groupId>
<artifactId>opentelemetry-bom</artifactId>
<version>1.23.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>ARMS と OpenTelemetry ベースのインストルメンテーション間の互換性
用語
以下は、一般的に使用される用語です。完全な用語集については、「OpenTelemetry Specification」をご参照ください。
スパン:リクエスト内の名前付き操作 (リモートコールや内部メソッドコールなど)。
スパンコンテキスト:トレースのコンテキスト。トレース ID やスパン ID などの識別子を含みます。
属性:補足情報を記録するためにスパンにアタッチされるキーと値のペア。
Baggage:トレース全体にわたって伝播されるキーと値のペア。
Java 用 OpenTelemetry SDK の使用
SDK を使用すると、次の操作を実行できます:
インストルメンテーションコードを使用して新しいスパンを作成する。
スパンに属性を追加する。
トレースコンテキスト内で Baggage アイテムを伝播させる。
トレースコンテキストにアクセスし、トレース ID やスパン ID などの識別子を出力する。
次のサンプルコードは、これらの操作を示しています。
SDK で手動でインスタンスを作成するのではなく、GlobalOpenTelemetry.get() を呼び出して OpenTelemetry インスタンスを取得してください。そうしないと、SDK インストルメンテーションによって作成されたスパンが ARMS エージェント v4.x で表示されなくなります。
@RestController
@RequestMapping("/ot")
public class OpenTelemetryController {
private Tracer tracer;
private ScheduledExecutorService ses = Executors.newSingleThreadScheduledExecutor();
@PostConstruct
public void init() {
OpenTelemetrySdk.builder()
.setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance()))
.buildAndRegisterGlobal();
tracer = GlobalOpenTelemetry.get().getTracer("manual-sdk", "1.0.0");
ses.scheduleAtFixedRate(new Runnable() {
@Override
public void run() {
Span span = tracer.spanBuilder("schedule")
.setAttribute("schedule.time", System.currentTimeMillis())
.startSpan();
try (Scope scope = span.makeCurrent()) {
System.out.println("scheduled!");
Thread.sleep(500L);
span.setAttribute("schedule.success", true);
System.out.println(Span.current().getSpanContext().getTraceId()); // トレース ID を取得します。
} catch (Throwable t) {
span.setStatus(StatusCode.ERROR, t.getMessage());
} finally {
span.end();
}
}
}, 10, 30, TimeUnit.SECONDS);
}
@ResponseBody
@RequestMapping("/parent")
public String parent() {
Span span = tracer.spanBuilder("parent").setSpanKind(SpanKind.SERVER).startSpan();
try (Scope scope = span.makeCurrent()) {
// Baggage を使用してサービスのカスタムタグを伝播させます。
Baggage baggage = Baggage.current().toBuilder()
.put("user.id", "1")
.put("user.name", "name")
.build();
try (Scope baggageScope = baggage.storeInContext(Context.current()).makeCurrent()) {
child();
}
span.setAttribute("http.method", "GET");
span.setAttribute("http.uri", "/parent");
} finally {
span.end();
}
return "parent";
}
private void child() {
Span span = tracer.spanBuilder("child").startSpan();
try (Scope scope = span.makeCurrent()) {
System.out.println("current traceId = " + Span.current().getSpanContext().getTraceId());
System.out.println("userId in baggage = " + Baggage.current().getEntryValue("user.id"));
Thread.sleep(1000);
} catch (Throwable e) {
span.setStatus(StatusCode.ERROR, e.getMessage());
} finally {
span.end();
}
}
}詳細:
OpenTelemetryControllerのinitメソッドは、ScheduledExecutorService を使用してスケジュールされたタスクを開始します。このタスクは、開始時にスパンを作成し、終了時にそのスパンをクローズします。OpenTelemetryControllerのparentメソッドは、OpenTelemetry SDK の複数のメソッドを呼び出します。このメソッドは、呼び出されるたびに
parentという名前のスパンを作成し、メソッドの終了時にそのスパンをクローズします。また、Baggage SDK を呼び出して、
user.idとuser.nameという名前の 2 つの Baggage アイテムを追加します。これら 2 つの Baggage は、ダウンストリームのアプリケーションに伝播されます。ステップ 2.a で作成されたスパンに 2 つの属性が追加されます。
OpenTelemetryControllerのchildメソッドは、次の操作を実行します。
エージェントバージョンの比較
次の表は、これらの操作に対する ARMS エージェントの各バージョンにおけるサポート状況を示しています。
ステップ | ARMS エージェント v4.x 以降 | ARMS エージェント v3.x 以前 |
1 | サポートされています。新しいスパンが生成されます。 | サポートされています。新しいスパンが生成されます。 |
2.a | サポートされています | サポートされています |
2.b | サポートされています | サポートされていません |
2.c | サポートされています | サポートされています |
3.a | サポートされています | サポートされています。このスパンは、ステップ 2.a で作成されたスパンのメソッドスタックとして使用されます。 |
3.b | サポートされています。出力されたトレース ID は、エージェントによって提供されたものと同じです。 | サポートされていません。出力されたトレース ID は、エージェントによって提供されたものとは異なります。 |
3.c | サポートされています | サポートされています |
インストルメンテーションの効果
ARMS エージェント v4.x 以降
ステップ 1:
OpenTelemetry SDK で作成されたスパンがトレースに表示されます。

ステップ 2 およびステップ 3:
OpenTelemetry SDK で作成されたスパン (赤枠) と Tomcat インストルメンテーションのスパン (黄枠) は、同じトレースに属します。SDK が生成したスパンの属性は正しく設定されています (青枠)。

ARMS エージェント v3.x 以前
ステップ 1:

ステップ 2 およびステップ 3:
OpenTelemetry SDK で作成されたスパン (赤枠) と Tomcat インストルメンテーションのスパン (黄枠) は、同じトレースに属します。
childスパンは、parentスパン内のメソッドスタックとして表示されます。SDK が生成したスパンの属性は正しく設定されています (青枠)。

Related step
By associating a trace ID with application business logs, you can quickly locate and resolve errors.