すべてのプロダクト
Search
ドキュメントセンター

Cloud Monitor:Java 用 OpenTelemetry SDK によるトレースへのカスタムインストルメンテーションコードの追加

最終更新日:Oct 10, 2026

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();
        }
    }
}

詳細:

  1. OpenTelemetryController の init メソッドは、ScheduledExecutorService を使用してスケジュールされたタスクを開始します。このタスクは、開始時にスパンを作成し、終了時にそのスパンをクローズします。

  2. OpenTelemetryController の parent メソッドは、OpenTelemetry SDK の複数のメソッドを呼び出します。

    1. このメソッドは、呼び出されるたびに parent という名前のスパンを作成し、メソッドの終了時にそのスパンをクローズします。

    2. また、Baggage SDK を呼び出して、user.id と user.name という名前の 2 つの Baggage アイテムを追加します。これら 2 つの Baggage は、ダウンストリームのアプリケーションに伝播されます。

    3. ステップ 2.a で作成されたスパンに 2 つの属性が追加されます。

  3. OpenTelemetryController の child メソッドは、次の操作を実行します。

    1. このメソッドは、呼び出されるたびに child という名前のスパンを作成し、メソッドの終了時にそのスパンをクローズします。このスパンは、ステップ 2.a で作成されたスパンの子であることにご注意ください。

    2. このメソッドはトレースコンテキストを取得し、トレース ID を出力します。

    3. また、ステップ 2.b で追加された Baggage アイテム (user.id と user.name) を取得して出力します。

エージェントバージョンの比較

次の表は、これらの操作に対する 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 で作成されたスパンがトレースに表示されます。

    image

  • ステップ 2 およびステップ 3:

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

    image.png

ARMS エージェント v3.x 以前

  • ステップ 1:

    2024-12-16_15-41-45

  • ステップ 2 およびステップ 3:

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

    image

    image

Related step

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