X-Ray による計装から OpenTelemetry による計装への移行 - AWS X-Ray
OpenTelemetry について移行に関する OpenTelemetry の概念を理解する移行の概要X-Ray デーモンから AWS CloudWatch エージェントまたは OpenTelemetry コレクターへの移行

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

X-Ray による計装から OpenTelemetry による計装への移行

注記

X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日に、 AWS X-Ray SDKs/Daemon はメンテナンスモードに移行します。 AWS は、X-Ray SDK とデーモンのリリースをセキュリティ上の問題にのみ対処するように制限します。サポートタイムラインの詳細については、「X-Ray SDK とデーモンのサポートタイムライン」を参照してください。

X-Ray は、アプリケーションのトレースとオブザーバビリティの主要な計装標準として OpenTelemetry (OTel) に移行しています。この戦略的シフトは、業界のベストプラクティス AWS に沿ったものであり、オブザーバビリティのニーズに応じて、より包括的で柔軟、かつ将来を見据えたソリューションを提供します。OpenTelemetry の業界での幅広い導入により、X-Ray と直接統合されない可能性のある外部のシステムなど、さまざまなシステムにわたるリクエストをトレース AWS できます。

この章では、スムーズな移行に関する推奨事項を提供し、OpenTelemetry ベースのソリューションへの移行の重要性を強調して、アプリケーションの計装とオブザーバビリティにおける最新の機能を継続的にサポートし、アクセスできるようにします。

アプリケーションを計装するためのオブザーバビリティソリューションとして OpenTelemetry を導入することをお勧めします。

トピック

OpenTelemetry について

OpenTelemetry は、業界標準のオブザーバビリティフレームワークで、テレメトリデータを収集するための標準化されたプロトコルとツールを提供します。メトリクス、ログ、トレースなどのテレメトリデータを計装、生成、収集、エクスポートするための統一されたアプローチを提供します。

X-Ray SDK から OpenTelemetry に移行することには、次のような利点があります。

  • フレームワークとライブラリの計装サポートの強化

  • 追加のプログラミング言語のサポート

  • 自動計装機能

  • 柔軟なサンプリング設定オプション

  • メトリクス、ログ、トレースの統合コレクション

OpenTelemetry コレクターには、X-Ray デーモンよりも多くのデータ収集形式とエクスポート先オプションが用意されています。

での OpenTelemetry サポート AWS

AWS には、OpenTelemetry を操作するための複数のソリューションが用意されています。

  • AWS Distro for OpenTelemetry

    OpenTelemetry トレースをセグメントとして X-Ray にエクスポートします。

    詳細については、「AWS Distro for OpenTelemetry」を参照してください。

  • CloudWatch Application Signals

    カスタマイズされた OpenTelemetry トレースとメトリクスをエクスポートして、アプリケーションのヘルスをモニタリングします。

    詳細については、「Application Signals の使用」を参照してください。

  • CloudWatch OTel エンドポイント

    HTTP OTel エンドポイントとネイティブの OpenTelemetry 計装を使用して、OpenTelemetry トレースを X-Ray にエクスポートします。

    詳細については、「OTel エンドポイントの使用」を参照してください。

AWS CloudWatch での OpenTelemetry の使用

AWS CloudWatch は、クライアント側のアプリケーション計測と、Application Signals、Trace、Map、Metrics、Logs などのネイティブ AWS CloudWatch サービスを通じて OpenTelemetry トレースをサポートします。詳細については、「OpenTelemetry」を参照してください。

移行に関する OpenTelemetry の概念を理解する

次の表は、X-Ray の概念を OpenTelemetry の同等の概念にマッピングしたものです。これらのマッピングを理解すると、既存の X-Ray 計装を OpenTelemetry に変換できます。

X-Ray の概念 OpenTelemetry の概念
X-Ray レコーダー トレーサープロバイダーとトレーサー
サービスプラグイン リソース検出器
セグメント (サーバー) スパン
サブセグメント (サーバー以外) スパン
X-Ray サンプリングルール OpenTelemetry サンプリング (カスタマイズ可能)
X-Ray エミッター スパンエクスポーター (カスタマイズ可能)
注釈/メタデータ 属性
ライブラリ計装 ライブラリ計装
X-Ray トレースコンテキスト スパンコンテキスト
X-Ray トレースコンテキストの伝播 W3C トレースコンテキストの伝播
X-Ray トレースサンプリング OpenTelemetry トレースサンプリング
該当なし スパン処理
該当なし バゲッジ
X-Ray デーモン OpenTelemetry Collector
注記

OpenTelemetry の概念の詳細については、「OpenTelemetry のドキュメント」を参照してください。

機能の比較

次の表は、両方のサービスでサポートされている機能を示しています。この情報を使用して、移行中に対処する必要があるギャップを特定します。

機能 X-Ray 計装 OpenTelemetry 計装
ライブラリ計装 サポート対象 サポート
X-Ray サンプリング サポート

OTel Java/.NET/Go でサポート

ADOT Java/.NET/Python/Node.js でサポート
X-Ray トレースコンテキストの伝播 サポート対象 サポート
リソース検出 サポート対象 サポート
セグメント注釈 サポート対象 サポート
セグメントメタデータ サポート対象 サポート
ゼロコードの自動計装 Java でサポート

OTel Java/.NET/Python/Node.js でサポート

ADOT Java/.NET/Python/Node.js でサポート
手動トレースの作成 サポート対象 サポート

トレースのセットアップと設定

OpenTelemetry でトレースを作成するには、トレーサーが必要です。アプリケーションでトレーサープロバイダーを初期化することで、トレーサーを取得します。これは、X-Ray レコーダーを使用して X-Ray を設定し、X-Ray トレースでセグメントとサブセグメントを作成する方法と似ています。

注記

OpenTelemetry トレーサープロバイダーは、X-Ray レコーダーよりも多くの設定オプションを提供しています。

トレースデータ構造について

基本的な概念と機能のマッピングを理解したら、トレースデータの構造やサンプリングなどの特定の実装の詳細について学習できます。

OpenTelemetry は、セグメントやサブセグメントの代わりにスパンを使用してトレースデータを構造化します。各スパンには、以下のコンポーネントが含まれています。

  • Name

  • 一意の ID

  • 開始および終了タイムスタンプ

  • スパンの種類

  • スパンコンテキスト

  • 属性 (キーと値のメタデータ)

  • イベント (タイムスタンプ付きログ)

  • 他のスパンへのリンク

  • ステータス情報

  • 親スパンのリファレンス

OpenTelemetry に移行すると、スパンは自動的に X-Ray セグメントまたはサブセグメントに変換されます。このため、既存の CloudWatch コンソールエクスペリエンスは変更されません。

スパン属性の使用

X-Ray SDK には、セグメントとサブセグメントにデータを追加する方法が 2 つあります。

‏注釈

フィルタリングと検索のためにインデックス付けされるキーと値のペア

メタデータ

検索用にインデックス化されていない複雑なデータを含むキーと値のペア

デフォルトでは、OpenTelemetry のスパン属性は X-Ray の未加工データのメタデータに変換されます。代わりに特定の属性を注釈に変換するには、それらのキーを aws.xray.annotations 属性リストに追加します。

環境でのリソースの検出

OpenTelemetry は Resource Detectors を使用して、テレメトリデータを生成するリソースに関するメタデータを収集します。このメタデータはリソース属性として保存されます。例えば、テレメトリを生成するエンティティは Amazon ECS クラスターまたは Amazon EC2 インスタンスにすることができ、これらのエンティティから記録できるリソース属性には Amazon ECS クラスター ARN または Amazon EC2 インスタンス ID を含めることができます。

サンプリング戦略の管理

トレースサンプリングは、すべてのリクエストではなく、リクエストの代表的なサブセットからデータを収集することで、コストを管理するのに役立ちます。OpenTelemetry と X-Ray はどちらもサンプリングをサポートしていますが、実装は異なります。

注記

トレースの 100% 未満をサンプリングすると、アプリケーションのパフォーマンスに関する有意義なインサイトを維持しながら、オブザーバビリティのコストを削減できます。

OpenTelemetry には複数のサンプリング戦略が組み込みで提供されており、カスタムの戦略を作成できます。一部の SDK 言語で X-Ray リモートサンプラーを設定して、OpenTelemetry で X-Ray サンプリングルールを使用することもできます。

OpenTelemetry の追加のサンプリング戦略は次のとおりです。

  • 親ベースのサンプリング – 追加のサンプリング戦略を適用する前に、親スパンのサンプリング決定を優先します。

  • トレース ID 比率ベースのサンプリング – 指定したスパンの割合をランダムにサンプリングします。

  • テイルサンプリング – サンプリングルールを適用して OpenTelemetry コレクターのトレースを完了します。

  • カスタムサンプラー – サンプリングインターフェイスを使用して独自のサンプリングロジックを実装します。

X-Ray のサンプリングの詳細については、「Sampling rules in the X-Ray console」を参照してください。

OpenTelemetry のテイルサンプリングの詳細については、「Tail sampling processor」を参照してください。

トレースコンテキストの管理

X-Ray SDK はセグメントコンテキストを管理し、トレース内のセグメントとサブセグメント間の親子関係を正しく処理します。OpenTelemetry は同様のメカニズムを使用して、スパンが正しい親スパンを持つようにします。また、リクエストコンテキスト全体でトレースデータを保存して伝播します。例えば、アプリケーションでリクエストが処理され、そのリクエストを表すサーバースパンが作成されると、OpenTelemetry はサーバースパンを OpenTelemetry コンテキストに保存します。そのようにして、子スパンが作成されると、その子スパンがコンテキスト内のスパンを親として参照できるようにします。

トレースコンテキストの伝播

X-Ray と OpenTelemetry はどちらも HTTP ヘッダーを使用して、サービス間でトレースコンテキストを伝播します。これにより、さまざまなサービスによって生成されたトレースデータをリンクし、サンプリングの決定を維持できます。

X-Ray SDK は、X-Ray トレースヘッダーを使用してトレースコンテキストを自動的に伝播します。あるサービスが別のサービスを呼び出すと、トレースヘッダーには、トレース間の親子関係を維持するために必要なコンテキストが含まれるようになります。

OpenTelemetry は、次のようなコンテキスト伝播用の複数のトレースヘッダー形式をサポートしています。

  • W3C トレースコンテキスト (デフォルト)

  • X-Ray トレースヘッダー

  • その他のカスタム形式

注記

1 つ以上のヘッダー形式を使用するように OpenTelemetry を設定できます。たとえば、X-Ray Propagator を使用して、X-Ray トレースをサポートする AWS サービスにトレースコンテキストを送信します。

X-Ray Propagator を設定して使用し、 AWS サービス間のトレースを有効にします。これにより、トレースコンテキストを API Gateway のエンドポイントおよび X-Ray をサポートする他のサービスに伝播できます。

  • X-Ray トレースヘッダーの詳細については、「X-Ray デベロッパーガイド」の「Tracing header」を参照してください。

  • OpenTelemetry コンテキストの伝播の詳細については、OpenTelemetry ドキュメントの「Context and Context Propagation」を参照してください。

ライブラリ計装の使用

X-Ray と OpenTelemetry はどちらも、アプリケーションにトレースを追加するために最小限のコード変更を必要とするライブラリ計装を提供します。

X-Ray はライブラリ計装機能を提供します。これにより、アプリケーションコードの変更を最小限に抑えながら、構築済みの X-Ray 計装を追加できます。これらの計測は、 AWS SDK や HTTP クライアントなどの特定のライブラリと、Spring Boot や Express.js などのウェブフレームワークをサポートします。

OpenTelemetry の計装ライブラリは、ライブラリフックまたは自動コード変更を通じてライブラリの詳細なスパンを生成し、コードの変更を最小限に抑えます。

OpenTelemetry のライブラリ計装が自身のライブラリをサポートしているかどうかを確認するには、「OpenTelemetry Registry」でライブラリを検索してください。

トレースのエクスポート

X-Ray と OpenTelemetry は、トレースデータをエクスポートするためにさまざまな方法を使用しています。

X-Ray トレースのエクスポート

X-Ray SDK はエミッターを使用してトレースデータを送信します。

  • セグメントとサブセグメントを X-Ray デーモンに送信します。

  • ノンブロッキング I/O に UDP を使用します。

  • SDK にデフォルトで設定されています。

OpenTelemetry トレースのエクスポート

OpenTelemetry は、設定可能なスパンエクスポーターを使用してトレースデータを送信します。

  • http/protobuf または grpc プロトコルを使用します。

  • OpenTelemetry コレクターまたは CloudWatch エージェントによってモニタリングされるエンドポイントにスパンをエクスポートします。

  • カスタムエクスポーター設定を許可します。

トレースの処理と転送

X-Ray と OpenTelemetry はどちらも、トレースデータを受信、処理、転送するためのコンポーネントを提供します。

X-Ray のトレース処理

X-Ray デーモンは次のトレース処理を担当します。

  • X-Ray SDK からの UDP トラフィックをリッスン

  • セグメントとサブセグメントをバッチ処理

  • バッチを X-Ray サービスにアップロード

OpenTelemetry のトレース処理

OpenTelemetry コレクターは次のトレース処理を担当します。

  • 計装されたサービスのトレースを受信

  • トレースデータを処理してオプションで変更

  • 処理されたトレースを X-Ray を含むさまざまなバックエンドに送信

注記

AWS CloudWatch エージェントはOpenTelemetry トレースを受信して X-Ray に送信することもできます。詳細については、「Collect metrics and traces with OpenTelemetry」を参照してください。

スパン処理 (OpenTelemetry 固有の概念)

OpenTelemetry はスパンプロセッサを使用して、スパンの作成時にスパンを変更します。

  • 作成時または完了時にスパンの読み取りと変更を許可します。

  • スパン処理のカスタムロジックを有効にします。

バゲッジ (OpenTelemetry 固有の概念)

OpenTelemetry のパーティショニング機能を使用すると、キーと値のデータを伝播できます。

  • トレースコンテキストとともに任意のデータを渡すことを可能にします。

  • サービスの境界を越えてアプリケーション固有の情報を伝達するのに役立ちます。

OpenTelemetry コレクターの詳細については、「OpenTelemetry のコレクター」を参照してください。

X-Ray の概念の詳細については、「X-Ray デベロッパーガイド」の「X-Ray concepts」を参照してください。

移行の概要

このセクションでは、移行に必要なコード変更の概要を説明します。以下のリストは、言語固有のガイダンスと X-Ray デーモンの移行手順です。

重要

X-Ray による計装から OpenTelemetry による計装に完全に移行するには、以下が必要です。

  1. X-Ray SDK の使用を OpenTelemetry ソリューションに置き換える

  2. X-Ray デーモンを CloudWatch エージェントまたは OpenTelemetry コレクター (X-Ray Exporter を追加) に置き換える

新規および既存のアプリケーションの推奨事項

新規および既存のアプリケーションでは、次のソリューションを使用してアプリケーションでトレースを有効にすることをお勧めします。

インストルメンテーション

  • OpenTelemetry の SDK

  • AWS Distro for OpenTelemetry Instrumentation

データ収集

  • OpenTelemetry Collector

  • CloudWatch エージェント

OpenTelemetry ベースのソリューションに移行した後も、CloudWatch のエクスペリエンスは変わりません。CloudWatch コンソールの [トレース] ページと [トレースマップ] ページでトレースを同じ形式で表示したり、X-Ray API を使用してトレースデータを取得したりできます。

セットアップ変更のトレース

X-Ray セットアップを OpenTelemetry セットアップに置き換える必要があります。

X-Ray と OpenTelemetry のセットアップの比較
機能 X-Ray SDK OpenTelemetry
デフォルト設定

  • X-Ray 集中サンプリング

  • X-Ray トレースコンテキストの伝播

  • X-Ray デーモンへのトレースエクスポート

  • OpenTelemetry コレクターまたは CloudWatch エージェントへのトレースのエクスポート (HTTP/gRPC)

  • W3C トレースコンテキストの伝播
手動設定

  • ローカルサンプリングルール

  • リソース検出プラグイン

  • X-Ray サンプリング (一部の言語では使用できない場合があります)

  • リソース検出

  • X-Ray トレースコンテキストの伝播

ライブラリ計装の変更

AWS SDK、HTTP クライアント、ウェブフレームワーク、およびその他のライブラリの X-Ray ライブラリ計測の代わりに OpenTelemetry Library 計測を使用するようにコードを更新します。これにより、X-Ray トレースの代わりに OpenTelemetry トレースが生成されます。

注記

コードの変更は言語とライブラリによって異なります。詳細な手順については、言語固有の移行ガイドを参照してください。

Lambda 環境計装の変更

Lambda 関数で OpenTelemetry を使用するには、次のいずれかの設定オプションを選択します。

  1. 自動計装 Lambda レイヤーを使用します。

  2. Lambda 関数の OpenTelemetry を手動でセットアップします。

    • X-Ray UDP スパンエクスポーターを使用してシンプルなスパンプロセッサを設定する

    • X-Ray Lambda プロパゲーターをセットアップする

トレースデータを手動で作成する

X-Ray セグメントとサブセグメントを OpenTelemetry スパンに置き換えます。

  • OpenTelemetry トレーサーを使用してスパンを作成する

  • スパンに属性を追加する (X-Ray メタデータと注釈に相当)

重要

X-Ray に送信した場合:

  • サーバースパンを X-Ray セグメントに変換されます。

  • その他のスパンは X-Ray サブセグメントに変換されます。

  • 属性はデフォルトでメタデータに変換されます。

属性を注釈に変換するには、そのキーを aws.xray.annotations 属性リストに追加します。詳細については、「Enable Customized X-Ray Annotations」を参照してください。

X-Ray デーモンから AWS CloudWatch エージェントまたは OpenTelemetry コレクターへの移行

CloudWatch エージェントまたは OpenTelemetry コレクターを使用して、計装されたアプリケーションからトレースを受信し、X-Ray に送信できます。

注記

バージョン 1.300025.0 以降の CloudWatch エージェントは、OpenTelemetry トレースを収集できます。X-Ray デーモンの代わりに CloudWatch エージェントを使用すると、管理が必要なエージェントの数を減らすことができます。詳細については「CloudWatch エージェントを使用してメトリクス、ログ、トレースを収集する」を参照してください。

Amazon EC2 またはオンプレミスサーバーでの移行

重要

CloudWatch エージェントまたは OpenTelemetry コレクターを使用してポートの競合を防ぐ前に、X-Ray デーモンプロセスを停止してください。

既存の X-Ray デーモンのセットアップ

デーモンのインストール

既存の X-Ray デーモンの使用は、次のいずれかの方法を使用してインストールされました。

手動インストール

X-Ray デーモン Amazon S3 バケットから実行可能ファイルをダウンロードして実行する。

自動インストール

このスクリプトを使用して、インスタンスの起動時にデーモンをインストールする。

#!/bin/bash
curl https://s3.us-east-2.amazonaws.com/aws-xray-assets.us-east-2/xray-daemon/aws-xray-daemon-3.x.rpm \
    -o /home/ec2-user/xray.rpm
yum install -y /home/ec2-user/xray.rpm
デーモンを設定する

既存の X-Ray デーモンの使用は、次のいずれかを使用して設定されました。

  • コマンドライン引数

  • 設定ファイル (xray-daemon.yaml)

例 設定ファイルを使用する
./xray -c ~/xray-daemon.yaml
デーモンを実行する

既存の X-Ray デーモンの使用は、次のコマンドで開始されました。

~/xray-daemon$ ./xray -o -n us-east-1
デーモンの削除

Amazon EC2 インスタンスから X-Ray デーモンを削除する方法

  1. デーモンサービスを停止します。

    systemctl stop xray

  2. 設定ファイルを作成します。

    rm ~/path/to/xray-daemon.yaml

  3. 設定されている場合は、ログファイルを削除します。

    注記

    ログファイルの場所は、設定によって異なります。

    • コマンドライン設定: /var/log/xray-daemon.log

    • 設定ファイル: LogPath 設定を確認

CloudWatch エージェントのセットアップ

エージェントのインストール

インストール手順については、「オンプレミスサーバーに CloudWatch エージェントをインストールする」を参照してください。

エージェントの設定

  1. トレース収集を有効にする設定ファイルを作成します。詳細については、「CloudWatch エージェント設定ファイルを作成する」を参照してください。

  2. IAM 許可をセットアップします。

    • IAM ロールをアタッチするか、エージェントの認証情報を指定します。詳細については、「IAM ロールの設定」を参照してください。

    • ロールまたは認証情報に xray:PutTraceSegments アクセス許可が含まれていることを確認します。

エージェントを開始する

エージェントを起動する手順については、「Starting the CloudWatch agent using the command line」を参照してください。

OpenTelemetry コレクターのセットアップ

コレクターのインストール

オペレーティングシステム用の OpenTelemetry コレクターをダウンロードしてインストールします。手順については、「コレクターのインストール」を参照してください。

コレクターの設定

コレクターで次のコンポーネントを設定します。

  • awsproxy 拡張機能

    X-Ray サンプリングに必要です。

  • OTel レシーバー

    アプリケーションからトレースを収集します。

  • xray エクスポーター

    X-Ray にトレースを送信します。

例 サンプルコレクターの設定 — otel-collector-config.yaml
extensions:
  awsproxy:
    endpoint: 127.0.0.1:2000
  health_check:

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 127.0.0.1:4317
      http:
        endpoint: 127.0.0.1:4318

processors:
  batch:

exporters:
  awsxray:
    region: 'us-east-1'

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [awsxray]
  extensions: [awsproxy, health_check]
重要

アクセスxray:PutTraceSegments許可を使用して AWS 認証情報を設定します。詳細については、「認証情報の指定」を参照してください。

コレクターの起動

設定ファイルを使用してコレクターを実行します。

otelcol --config=otel-collector-config.yaml

Amazon ECS での移行

重要

タスクロールには、使用するコレクターに対する xray:PutTraceSegments アクセス許可が必要です。

ポートの競合を防ぐため、同じホストで CloudWatch エージェントまたは OpenTelemetry コレクターコンテナを実行する前に、既存の X-Ray デーモンコンテナを停止してください。

CloudWatch エージェントの使用

  1. Amazon ECR Public Gallery から Docker イメージを取得します。

  2. cw-agent-otel.json という名前の設定ファイルを作成します。

    {
  "traces": {
    "traces_collected": {
      "xray": {
        "tcp_proxy": {
          "bind_address": "0.0.0.0:2000"
        }
      },
      "otlp": {
        "grpc_endpoint": "0.0.0.0:4317",
        "http_endpoint": "0.0.0.0:4318"
      }
    }
  }
}

  3. Systems Manager Parameter Store にエージェント設定を保存します。

    1. https://console.aws.amazon.com/systems-manager/ を開きます。

    2. [パラメータの作成] を選択します。

    3. 次の値を入力します。

      • 名前: /ecs/cwagent/otel-config

      • 利用枠: 標準

      • タイプ: 文字列

      • データ型: テキスト

      • 値: [ここに cw-agent-otel.json 設定を貼り付けます。]

  4. ブリッジネットワークモードを使用してタスク定義を作成します。

    タスク定義では、使用するネットワーキングモードによって設定が異なります。デフォルトはブリッジネットワーキングで、デフォルトの VPC で使用できます。ブリッジネットワークで、OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 環境変数を設定して、CloudWatch エージェント用のエンドポイントとポートを OpenTelemetry SDK に伝えます。また、アプリケーションの OpenTelemetry SDK から Collector コンテナにトレースを送信するには、アプリケーションコンテナから Collector コンテナへのリンクを作成する必要があります。

    例 CloudWatch エージェントタスク定義
    {
    "containerDefinitions": [
        {
            "name": "cwagent",
            "image": "public.ecr.aws/cloudwatch-agent/cloudwatch-agent:latest",
            "portMappings": [
                {
                    "containerPort": 4318,
                    "hostPort": 4318,
                    "protocol": "tcp"
                },
                {
                    "containerPort": 4317,
                    "hostPort": 4317,
                    "protocol": "tcp"
                },
                {
                    "containerPort": 2000,
                    "hostPort": 2000,
                    "protocol": "tcp"
                }
            ],
            "secrets": [
                {
                    "name": "CW_CONFIG_CONTENT",
                    "valueFrom": "/ecs/cwagent/otel-config"
                }
            ]
        },
        {
            "name": "application",
            "image": "APPLICATION_IMAGE",
            "links": ["cwagent"],
            "environment": [
                {
                    "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
                    "value": "http://cwagent:4318/v1/traces"
                }
            ]
        }
    ]
}

詳細については、「Amazon ECS で EC2 インスタンスレベルのメトリクスを収集するための CloudWatch エージェントのデプロイ」を参照してください。

OpenTelemetry コレクターの使用

  1. Docker Hub で Docker イメージ otel/opentelemetry-collector-contrib を取得します。

  2. 「Amazon EC2 configuring the collector」セクションで示したものと同じコンテンツを使用して otel-collector-config.yaml という名前の設定ファイルを作成しますが、127.0.0.1 の代わりに 0.0.0.0 を使用するようにエンドポイントを更新します。

  3. Amazon ECS でこの設定を使用する場合は、Systems Manager Parameter Store で設定を保存できます。まず、Systems Manager Parameter Store コンソールに移動し、[新しいパラメータを作成する] を選択します。次の情報を使用して新しいパラメータを作成します。

    • 名前: /ecs/otel/config (この名前はコレクターのタスク定義で参照されます。)

    • 利用枠: 標準

    • タイプ: 文字列

    • データ型: テキスト

    • 値: [otel-collector-config.yaml 設定をここに貼り付けます。]

  4. 例としてブリッジネットワークモードを使用し、OpenTelemetry コレクターをデプロイするタスク定義を作成します。

    タスク定義では、設定は使用するネットワーキングモードによって異なります。デフォルトはブリッジネットワーキングで、デフォルトの VPC で使用できます。ブリッジネットワークで、OTEL_EXPORTER_OTLP_TRACES_ENDPOINT 環境変数を設定して、OpenTelemetry コレクターのエンドポイントとポートを OpenTelemetry SDK に伝えます。また、アプリケーションの OpenTelemetry SDK から Collector コンテナにトレースを送信するには、アプリケーションコンテナから Collector コンテナへのリンクを作成する必要があります。

    例 OpenTelemetry コレクターのタスク定義
    {
    "containerDefinitions": [
        {
            "name": "otel-collector",
            "image": "otel/opentelemetry-collector-contrib",
            "portMappings": [
                {
                    "containerPort": 2000,
                    "hostPort": 2000
                },
                {
                    "containerPort": 4317,
                    "hostPort": 4317
                },
                {
                    "containerPort": 4318,
                    "hostPort": 4318
                }
            ],
            "command": [
                "--config",
                "env:SSM_CONFIG"
            ],
            "secrets": [
                {
                    "name": "SSM_CONFIG",
                    "valueFrom": "/ecs/otel/config"
                }
            ]
        },
        {
            "name": "application",
            "image": "APPLICATION_IMAGE",
            "links": ["otel-collector"],
            "environment": [
                {
                    "name": "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
                    "value": "http://otel-collector:4318/v1/traces"
                }
            ]
        }
    ]
}

Elastic Beanstalk での移行

重要

CloudWatch エージェントを使用してポートの競合を防ぐ前に、X-Ray デーモンプロセスを停止します。

既存の X-Ray デーモン統合は、Elastic Beanstalk コンソールを使用するか、設定ファイルを使用してアプリケーションソースコードで X-Ray デーモンを設定することで有効になりました。

CloudWatch エージェントの使用

Amazon Linux 2 プラットフォームで、.ebextensions 設定ファイルを使用して CloudWatch エージェントを設定します。

  1. プロジェクトのルートに .ebextensions という名前のディレクトリを作成します。

  2. .ebextensions ディレクトリに次の内容で cloudwatch.config というファイルを作成します。

    files:
  "/opt/aws/amazon-cloudwatch-agent/etc/config.json":
    mode: "0644"
    owner: root
    group: root
    content: |
      {
        "traces": {
          "traces_collected": {
            "otlp": {
              "grpc_endpoint": "12.0.0.1:4317",
              "http_endpoint": "12.0.0.1:4318"
            }
          }
        }
      }
container_commands:
  start_agent:
    command: /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -c file:/opt/aws/amazon-cloudwatch-agent/etc/config.json -s

  3. デプロイする際、アプリケーションソースバンドルに .ebextensions ディレクトリを含めます。

Elastic Beanstalk 設定ファイルの詳細については、「設定ファイルによる高度な環境のカスタマイズ」を参照してください。