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>

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

Spring フレームワークで X-Ray SDK を使用してアプリケーションを計測する方法については、「Spring での AOP」と「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 を直接使用するよりもout-of-the-box使用できる計測と設定も増えます。開始方法については、「」を参照してくださいゼロコード自動計測ソリューション。

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

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

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

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

Tracer を使用してスパンを作成できます。

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 raw データ内のメタデータに変換されます。属性がメタデータではなく注釈に変換されるように、上記の例では、その属性のキーをaws.xray.annotations属性のリストに追加します。詳細については、「カスタマイズされた X-Ray 注釈と注釈とメタデータを有効にする」を参照してください。 https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-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 トレースを生成することを検討してください。