OpenTelemetry Java への移行

X-Ray Java エージェントを有効にする場合、アプリケーションの JVM 引数を変更する必要がありました。

-javaagent:/path-to-disco/disco-java-agent.jar=pluginPath=/path-to-disco/disco-plugins

OpenTelemetry ベースの Java エージェントを使用する方法

X-Ray SDK for Java を使用してコードを計装するには、まず AWSXRay クラスをサービスプラグインとローカルサンプリングルールで設定する必要があり、次に提供されたレコーダーを使用しました。

static { AWS XRayRecorderBuilder builder = AWS XRayRecorderBuilder.standard().withPlugin(new EC2Plugin()).withPlugin(new ECSPlugin()); AWS XRay.setGlobalRecorder(builder.build());
}

以下の依存関係は必須です。

<dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>io.opentelemetry</groupId>
                <artifactId>opentelemetry-bom</artifactId>
                <version>1.49.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>io.opentelemetry.instrumentation</groupId>
                <artifactId>opentelemetry-instrumentation-bom</artifactId>
                <version>2.15.0</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-sdk</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-api</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.semconv</groupId>
            <artifactId>opentelemetry-semconv</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-exporter-otlp</artifactId>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-xray</artifactId>
            <version>1.46.0</version>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-xray-propagator</artifactId>
            <version>1.46.0-alpha</version>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.contrib</groupId>
            <artifactId>opentelemetry-aws-resources</artifactId>
            <version>1.46.0-alpha</version>
        </dependency>
    </dependencies>

TracerProvider をインスタンス化して OpenTelemetry SDK を設定し、OpenTelemetrySdk オブジェクトをグローバルに登録します。以下のコンポーネントを設定します。

Spring Framework で X-Ray SDK を使用してアプリケーションを計装する方法については、「AOP with Spring and the X-Ray SDK for Java」を参照してください。Spring で AOP を有効にするには、以下の手順を実行します。

OpenTelemetry は、Spring Boot アプリケーションの受信リクエストのトレースを収集するための計装ライブラリを提供します。最小限の設定で Spring Boot 計装を有効にするには、次の依存関係を含めます。

<dependency>
           <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-spring-boot-starter</artifactId>
        </dependency>

OpenTelemetry のセットアップで Spring Boot 計装を有効にして設定する方法の詳細については、OpenTelemetry の「はじめに」を参照してください。

Spring Boot アプリケーションを計装するためのデフォルトの推奨方法は、OpenTelemetry Java エージェントとバイトコード計装を使用することです。これにより、SDK を直接使用する場合と比較してすぐに使える計装と設定が多くなります。開始するには、「ゼロコード自動計装ソリューション」を参照してください。

X-Ray SDK for Java は、ビルドにaws-xray-recorder-sdk-aws-sdk-v2-instrumentorサブモジュールを追加したときに、すべての AWS SDK v2 クライアントを自動的に計測できます。

AWS SDK for Java 2.2 以降 AWS で個々のクライアントのダウンストリームクライアント呼び出しを計測するために、ビルド設定の aws-xray-recorder-sdk-aws-sdk-v2-instrumentor モジュールが除外され、 aws-xray-recorder-sdk-aws-sdk-v2モジュールが含まれていました。個々のクライアントは、TracingInterceptor で設定することで計装されました。

import com.amazonaws.xray.interceptors.TracingInterceptor;
import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
//...

public class MyModel {
  private DynamoDbClient client = DynamoDbClient.builder()
    .region(Region.US_WEST_2)
    .overrideConfiguration(
      ClientOverrideConfiguration.builder()
        .addExecutionInterceptor(new TracingInterceptor())
        .build()
      )
    .build();
//...

すべての AWS SDK クライアントを自動的に計測するには、 opentelemetry-aws-sdk-2.2-autoconfigureサブモジュールを追加します。

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-aws-sdk-2.2-autoconfigure</artifactId>
            <version>2.15.0-alpha</version>
            <scope>runtime</scope>
        </dependency>

個々の AWS SDK クライアントを計測するには、 opentelemetry-aws-sdk-2.2サブモジュールを追加します。

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-aws-sdk-2.2</artifactId>
            <version>2.15.0-alpha</version>
            <scope>compile</scope>
        </dependency>

次に、 AWS SDK クライアントの作成時にインターセプターを登録します。

import io.opentelemetry.instrumentation.awssdk.v2_2.AwsSdkTelemetry;

// ...

    AwsSdkTelemetry telemetry = AwsSdkTelemetry.create(openTelemetry);
    private final S3Client S3_CLIENT = S3Client.builder()
      .overrideConfiguration(ClientOverrideConfiguration.builder()
        .addExecutionInterceptor(telemetry.newExecutionInterceptor())
        .build())
      .build();

X-Ray を使用して送信 HTTP リクエストを計装するには、X-Ray SDK for Java のバージョンの Apache HttpClient が必要でした。

import com.amazonaws.xray.proxies.apache.http.HttpClientBuilder;
...
  public String randomName() throws IOException {
    CloseableHttpClient httpclient = HttpClientBuilder.create().build();

X-Ray Java SDK と同様に、OpenTelemetry は、Apache HttpClient に OpenTelemetry ベースのスパンとコンテキスト伝播を提供する HttpClientBuilder のインスタンスの作成を許可するビルダーメソッドを持つ ApacheHttpClientTelemetry クラスを提供します。

<dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-apache-httpclient-5.2</artifactId>
            <version>2.15.0-alpha</version>
            <scope>compile</scope>
        </dependency>

以下は、opentelemetry-java-instrumentation のコード例です。newHttpClient() によって提供される HTTP クライアントは、実行されたリクエストのトレースを生成します。

import io.opentelemetry.api.OpenTelemetry;
import io.opentelemetry.instrumentation.apachehttpclient.v5_2.ApacheHttpClientTelemetry;
import org.apache.hc.client5.http.classic.HttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClientBuilder;

public class ApacheHttpClientConfiguration {

  private OpenTelemetry openTelemetry;

  public ApacheHttpClientConfiguration(OpenTelemetry openTelemetry) {
    this.openTelemetry = openTelemetry;
  }

  // creates a new http client builder for constructing http clients with open telemetry instrumentation
  public HttpClientBuilder createBuilder() {
    return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClientBuilder();
  }

  // creates a new http client with open telemetry instrumentation
  public HttpClient newHttpClient() {
    return ApacheHttpClientTelemetry.builder(openTelemetry).build().newHttpClient();
  }
}

X-Ray SDK では、X-Ray セグメントとサブセグメントを手動で作成するには、beginSegment および beginSubsegment メソッドが必要です。

  Segment segment = xrayRecorder.beginSegment("ManualSegment");
        segment.putAnnotation("annotationKey", "annotationValue");
        segment.putMetadata("metadataKey", "metadataValue");

        try {
            Subsegment subsegment = xrayRecorder.beginSubsegment("ManualSubsegment");
            subsegment.putAnnotation("key", "value");

            // Do something here

        } catch (Exception e) {
            subsegment.addException(e);
        } finally {
            xrayRecorder.endSegment();
        }

カスタムスパンを使用すると、計装ライブラリでキャプチャされない内部アクティビティのパフォーマンスをモニタリングできます。Server タイプのスパンのみが X-Ray セグメントに変換され、他のすべてのスパンは X-Ray サブセグメントに変換されることに注意してください。

まず、openTelemetry.getTracer メソッドで取得できるスパンを生成するには、トレーサーを作成する必要があります。これにより、「SDK を使用した手動計装ソリューション」の例でグローバルに登録した TracerProvider から 1 つのトレーサーインスタンスが提供されます。必要に応じていくつでもトレーサーインスタンスを作成できますが、アプリケーション全体で 1 つのトレーサーを持つことが一般的です。

Tracer tracer = openTelemetry.getTracer("my-app");

トレーサーを使用してスパンを作成できます。

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.SpanKind;
import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.context.Scope;

...

// SERVER span will become an X-Ray segment
Span span = tracer.spanBuilder("get-token")
  .setKind(SpanKind.SERVER)
  .setAttribute("key", "value")
  .startSpan();
try (Scope ignored = span.makeCurrent()) {

  span.setAttribute("metadataKey", "metadataValue");
  span.setAttribute("annotationKey", "annotationValue");
  
  // The following ensures that "annotationKey: annotationValue" is an annotation in X-Ray raw data.
  span.setAttribute(AttributeKey.stringArrayKey("aws.xray.annotations"), List.of("annotationKey"));

  // Do something here
}

span.end();

スパンのデフォルトタイプは INTERNAL です。

// Default span of type INTERNAL will become an X-Ray subsegment
Span span = tracer.spanBuilder("process-header")
  .startSpan();
try (Scope ignored = span.makeCurrent()) {
  doProcessHeader();
}

OpenTelemetry SDK を使用してトレースに注釈とメタデータを追加する

上記の例では、setAttribute メソッドを使用して各スパンに属性を追加します。デフォルトでは、すべてのスパン属性は X-Ray の未加工データのメタデータに変換されます。属性がメタデータではなく注釈に変換されるように、上記の例では、その属性のキーを aws.xray.annotations 属性のリストに追加しています。詳細については、「Enable the Customized X-Ray Annotations」および「注釈とメタデータ」を参照してください。

OpenTelemetry ベースの Java エージェントを使用する

Java エージェントを使用してアプリケーションを自動的に計装する場合は、アプリケーションで手動計装を実行する必要があります。例えば、自動計装ライブラリでカバーされていないセクションのコードをアプリケーション内で計装する場合です。

エージェントで手動計装を実行するには、opentelemetry-api アーティファクトを使用する必要があります。アーティファクトバージョンをエージェントバージョンより新しいものにすることはできません。

import io.opentelemetry.api.GlobalOpenTelemetry;
import io.opentelemetry.api.trace.Span;

// ...
  
        Span parentSpan = Span.current();
        Tracer tracer = GlobalOpenTelemetry.getTracer("my-app");
        Span span = tracer.spanBuilder("my-span-name")
            .setParent(io.opentelemetry.context.Context.current().with(parentSpan))
            .startSpan();
        span.end();

X-Ray SDK を使用する場合、Lambda でアクティブトレースを有効にした後、X-Ray SDK を使用するための追加の設定は必要ありません。Lambda は Lambda ハンドラー呼び出しを表すセグメントを作成し、追加の設定なしで X-Ray SDK を使用してサブセグメントまたは計装ライブラリを作成できます。

自動計測 Lambda レイヤー – 次のソリューションを使用して AWS 、販売された Lambda レイヤーを使用して Lambda を自動的に計測できます。

自動計装レイヤーとともに手動計装を使用するには、「SDK を使用した手動計装ソリューション」を参照してください。コールドスタートを減らすには、OpenTelemetry 手動計装を使用して Lambda 関数の OpenTelemetry トレースを生成することを検討してください。