翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# X-Ray による計装から OpenTelemetry による計装への移行
**注記**
X-Ray SDK/デーモンメンテナンス通知 – 2026 年 2 月 25 日、 AWS X-Ray SDKsデーモンはメンテナンスモードに移行します。 AWS では、X-Ray SDK とデーモンのリリースがセキュリティの問題にのみ対処するように制限されます。サポートタイムラインの詳細については、「[X-Ray SDK とデーモンのサポートタイムライン](xray-sdk-daemon-timeline.md)」を参照してください。
X-Ray は、アプリケーションのトレースとオブザーバビリティの主要な計装標準として OpenTelemetry (OTel) に移行しています。この戦略的シフトは、業界のベストプラクティス AWS に沿ったもので、オブザーバビリティのニーズに応じて、より包括的で柔軟、かつ将来を見据えたソリューションを提供します。OpenTelemetry は業界で広く採用 AWS されているため、X-Ray と直接統合されない可能性のある外部のシステムなど、さまざまなシステムにわたるリクエストを追跡できます。
この章では、スムーズな移行に関する推奨事項を提供し、OpenTelemetry ベースのソリューションへの移行の重要性を強調して、アプリケーションの計装とオブザーバビリティにおける最新の機能を継続的にサポートし、アクセスできるようにします。
アプリケーションを計装するためのオブザーバビリティソリューションとして OpenTelemetry を導入することをお勧めします。
**Topics**
+ [OpenTelemetry について](#migration-to-opentelemetry)
+ [移行に関する OpenTelemetry の概念を理解する](#opentelemetry-concepts)
+ [移行の概要](#migration-overview)
+ [X-Ray デーモンから AWS CloudWatch エージェントまたは OpenTelemetry コレクターへの移行](#xray-Daemon-migration)
+ [OpenTelemetry Java への移行](xray-migration-opentelemetry.md)
+ [OpenTelemetry Go への移行](manual-instrumentation-go.md)
+ [OpenTelemetry Node.js への移行](migrate-xray-to-opentelemetry-nodejs.md)
+ [OpenTelemetry .NET への移行](introduction-dotnet.md)
+ [OpenTelemetry Python への移行](migrate-xray-to-opentelemetry-python.md)
+ [OpenTelemetry Ruby への移行](migrate-xray-to-opentelemetry-ruby.md)
## OpenTelemetry について
OpenTelemetry は、業界標準のオブザーバビリティフレームワークで、テレメトリデータを収集するための標準化されたプロトコルとツールを提供します。メトリクス、ログ、トレースなどのテレメトリデータを計装、生成、収集、エクスポートするための統一されたアプローチを提供します。
X-Ray SDK から OpenTelemetry に移行することには、次のような利点があります。
+ フレームワークとライブラリの計装サポートの強化
+ 追加のプログラミング言語のサポート
+ 自動計装機能
+ 柔軟なサンプリング設定オプション
+ メトリクス、ログ、トレースの統合コレクション
OpenTelemetry コレクターには、X-Ray デーモンよりも多くのデータ収集形式とエクスポート先オプションが用意されています。
### での OpenTelemetry サポート AWS
AWS には、OpenTelemetry を操作するための複数のソリューションが用意されています。
+ AWS Distro for OpenTelemetry
OpenTelemetry トレースをセグメントとして X-Ray にエクスポートします。
詳細については、「[AWS Distro for OpenTelemetry](https://aws-otel.github.io/)」を参照してください。
+ CloudWatch Application Signals
カスタマイズされた OpenTelemetry トレースとメトリクスをエクスポートして、アプリケーションのヘルスをモニタリングします。
詳細については、「[Application Signals の使用](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)」を参照してください。
+ CloudWatch OTel エンドポイント
HTTP OTel エンドポイントとネイティブの OpenTelemetry 計装を使用して、OpenTelemetry トレースを X-Ray にエクスポートします。
詳細については、「[OTel エンドポイントの使用](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html)」を参照してください。
#### AWS CloudWatch での OpenTelemetry の使用
AWS CloudWatch は、クライアント側のアプリケーション計測と、Application Signals、Trace、Map、Metrics、Logs などのネイティブ AWS CloudWatch サービスを通じて OpenTelemetry トレースをサポートします。詳細については、「[OpenTelemetry](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OpenTelemetry-Sections.html)」を参照してください。
## 移行に関する 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 のドキュメント](https://opentelemetry.io/docs)」を参照してください。
### 機能の比較
次の表は、両方のサービスでサポートされている機能を示しています。この情報を使用して、移行中に対処する必要があるギャップを特定します。
| 機能 | 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 は、セグメントやサブセグメントの代わりに*スパン*を使用してトレースデータを構造化します。各スパンには、以下のコンポーネントが含まれています。
+ 名前
+ 一意の ID
+ 開始および終了タイムスタンプ
+ スパンの種類
+ スパンコンテキスト
+ 属性 (キーと値のメタデータ)
+ イベント (タイムスタンプ付きログ)
+ 他のスパンへのリンク
+ ステータス情報
+ 親スパンのリファレンス
OpenTelemetry に移行すると、スパンは自動的に X-Ray セグメントまたはサブセグメントに変換されます。このため、既存の CloudWatch コンソールエクスペリエンスは変更されません。
##### スパン属性の使用
X-Ray SDK には、セグメントとサブセグメントにデータを追加する方法が 2 つあります。
注釈
フィルタリングと検索のためにインデックス付けされるキーと値のペア
メタデータ
検索用にインデックス化されていない複雑なデータを含むキーと値のペア
デフォルトでは、OpenTelemetry のスパン属性は X-Ray の未加工データのメタデータに変換されます。代わりに特定の属性を注釈に変換するには、それらのキーを `aws.xray.annotations` 属性リストに追加します。
+ OpenTelemetry の概念の詳細については、「[OpenTelemetry のトレース](https://opentelemetry.io/docs/concepts/signals/traces/)」を参照してください。
+ OpenTelemetry データが X-Ray データにどのようにマッピングされるかの詳細については、「[OpenTelemetry to X-Ray data model translation](https://aws-otel.github.io/docs/getting-started/X-Ray#otel-to-X-Ray-data-model-translation-behavior-of-aws-X-Ray-exporter)」を参照してください。
### 環境でのリソースの検出
OpenTelemetry は *Resource Detectors* を使用して、テレメトリデータを生成するリソースに関するメタデータを収集します。このメタデータは*リソース属性*として保存されます。例えば、テレメトリを生成するエンティティは Amazon ECS クラスターまたは Amazon EC2 インスタンスにすることができ、これらのエンティティから記録できるリソース属性には Amazon ECS クラスター ARN または Amazon EC2 インスタンス ID を含めることができます。
+ サポートされているリソースタイプの詳細については、「[OpenTelemetry Resource Semantic Conventions](https://opentelemetry.io/docs/reference/specification/resource/semantic_conventions/)」を参照してください。
+ X-Ray サービスプラグインの詳細については、「[Configuring the X-Ray SDK](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-python-configuration.html)」を参照してください。
### サンプリング戦略の管理
トレースサンプリングは、すべてのリクエストではなく、リクエストの代表的なサブセットからデータを収集することで、コストを管理するのに役立ちます。OpenTelemetry と X-Ray はどちらもサンプリングをサポートしていますが、実装は異なります。
**注記**
トレースの 100% 未満をサンプリングすると、アプリケーションのパフォーマンスに関する有意義なインサイトを維持しながら、オブザーバビリティのコストを削減できます。
OpenTelemetry には複数のサンプリング戦略が組み込みで提供されており、カスタムの戦略を作成できます。一部の SDK 言語で X-Ray *リモートサンプラー*を設定して、OpenTelemetry で X-Ray サンプリングルールを使用することもできます。
OpenTelemetry の追加のサンプリング戦略は次のとおりです。
+ 親ベースのサンプリング – 追加のサンプリング戦略を適用する前に、親スパンのサンプリング決定を優先します。
+ トレース ID 比率ベースのサンプリング – 指定したスパンの割合をランダムにサンプリングします。
+ テイルサンプリング – サンプリングルールを適用して OpenTelemetry コレクターのトレースを完了します。
+ カスタムサンプラー – サンプリングインターフェイスを使用して独自のサンプリングロジックを実装します。
X-Ray のサンプリングの詳細については、「[Sampling rules in the X-Ray console](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)」を参照してください。
OpenTelemetry のテイルサンプリングの詳細については、「[Tail sampling processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/tailsamplingprocessor)」を参照してください。
### トレースコンテキストの管理
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](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader)」を参照してください。
+ OpenTelemetry コンテキストの伝播の詳細については、OpenTelemetry ドキュメントの「[Context and Context Propagation](https://opentelemetry.io/docs/concepts/context-propagation/)」を参照してください。
### ライブラリ計装の使用
X-Ray と OpenTelemetry はどちらも、アプリケーションにトレースを追加するために最小限のコード変更を必要とするライブラリ計装を提供します。
X-Ray はライブラリ計装機能を提供します。これにより、アプリケーションコードの変更を最小限に抑えながら、構築済みの X-Ray 計装を追加できます。これらの計測は、 AWS SDK や HTTP クライアントなどの特定のライブラリと、Spring Boot や Express.js などのウェブフレームワークをサポートします。
OpenTelemetry の計装ライブラリは、ライブラリフックまたは自動コード変更を通じてライブラリの詳細なスパンを生成し、コードの変更を最小限に抑えます。
OpenTelemetry のライブラリ計装が自身のライブラリをサポートしているかどうかを確認するには、「[OpenTelemetry Registry](https://opentelemetry.io/ecosystem/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](AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-OpenTelemetry-metrics.html)」を参照してください。
### スパン処理 (OpenTelemetry 固有の概念)
OpenTelemetry はスパンプロセッサを使用して、スパンの作成時にスパンを変更します。
+ 作成時または完了時にスパンの読み取りと変更を許可します。
+ スパン処理のカスタムロジックを有効にします。
### バゲッジ (OpenTelemetry 固有の概念)
OpenTelemetry のパーティショニング機能を使用すると、キーと値のデータを伝播できます。
+ トレースコンテキストとともに任意のデータを渡すことを可能にします。
+ サービスの境界を越えてアプリケーション固有の情報を伝達するのに役立ちます。
OpenTelemetry コレクターの詳細については、「[OpenTelemetry のコレクター](https://opentelemetry.io/docs/collector/)」を参照してください。
X-Ray の概念の詳細については、「X-Ray デベロッパーガイド」の「[X-Ray concepts](https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html)」を参照してください。
## 移行の概要
このセクションでは、移行に必要なコード変更の概要を説明します。以下のリストは、言語固有のガイダンスと X-Ray デーモンの移行手順です。
**重要**
X-Ray による計装から OpenTelemetry による計装に完全に移行するには、以下が必要です。
X-Ray SDK の使用を OpenTelemetry ソリューションに置き換える
X-Ray デーモンを CloudWatch エージェントまたは OpenTelemetry コレクター (X-Ray Exporter を追加) に置き換える
+ [OpenTelemetry Java への移行](xray-migration-opentelemetry.md)
+ [OpenTelemetry Go への移行](manual-instrumentation-go.md)
+ [OpenTelemetry Node.js への移行](migrate-xray-to-opentelemetry-nodejs.md)
+ [OpenTelemetry .NET への移行](introduction-dotnet.md)
+ [OpenTelemetry Python への移行](migrate-xray-to-opentelemetry-python.md)
+ [OpenTelemetry Ruby への移行](migrate-xray-to-opentelemetry-ruby.md)
### 新規および既存のアプリケーションの推奨事項
新規および既存のアプリケーションでは、次のソリューションを使用してアプリケーションでトレースを有効にすることをお勧めします。
インストルメンテーション
+ OpenTelemetry の SDK
+ AWS Distro for OpenTelemetry Instrumentation
データ収集
+ OpenTelemetry Collector
+ CloudWatch エージェント
OpenTelemetry ベースのソリューションに移行した後も、CloudWatch のエクスペリエンスは変わりません。CloudWatch コンソールの [トレース] ページと [トレースマップ] ページでトレースを同じ形式で表示したり、[X-Ray API](https://docs.aws.amazon.com/xray/latest/devguide/xray-api.html) を使用してトレースデータを取得したりできます。
### セットアップ変更のトレース
X-Ray セットアップを OpenTelemetry セットアップに置き換える必要があります。
**X-Ray と OpenTelemetry のセットアップの比較**
| 機能 | X-Ray SDK | OpenTelemetry |
| --- | --- | --- |
| デフォルト設定 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/xray-sdk-migration.html) |
| 手動設定 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/xray-sdk-migration.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/xray-sdk-migration.html) |
### ライブラリ計装の変更
AWS SDK、HTTP クライアント、ウェブフレームワーク、およびその他のライブラリの X-Ray Library Instrumentation の代わりに OpenTelemetry Library Instrumentation を使用するようにコードを更新します。これにより、X-Ray トレースの代わりに OpenTelemetry トレースが生成されます。
**注記**
コードの変更は言語とライブラリによって異なります。詳細な手順については、言語固有の移行ガイドを参照してください。
### Lambda 環境計装の変更
Lambda 関数で OpenTelemetry を使用するには、次のいずれかの設定オプションを選択します。
1. 自動計装 Lambda レイヤーを使用します。
+ (推奨) [AWS OpenTelemetry 用の Lambda Layer](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Signals-Enable-LambdaMain.html)
**注記**
トレースのみを使用するには、Lambda 環境変数 `OTEL_AWS_APPLICATION_SIGNALS_ENABLED=false` を設定します。
+ [AWS ADOT 用 マネージド Lambda Layer](https://aws-otel.github.io/docs/getting-started/lambda)
1. 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](https://aws-otel.github.io/docs/getting-started/x-ray#enable-the-customized-x-ray-annotations)」を参照してください。
## X-Ray デーモンから AWS CloudWatch エージェントまたは OpenTelemetry コレクターへの移行
CloudWatch エージェントまたは OpenTelemetry コレクターを使用して、計装されたアプリケーションからトレースを受信し、X-Ray に送信できます。
**注記**
バージョン 1.300025.0 以降の CloudWatch エージェントは、OpenTelemetry トレースを収集できます。X-Ray デーモンの代わりに CloudWatch エージェントを使用すると、管理が必要なエージェントの数を減らすことができます。詳細については「[CloudWatch エージェントを使用してメトリクス、ログ、トレースを収集する](AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)」を参照してください。
**Topics**
+ [Amazon EC2 またはオンプレミスサーバーでの移行](#ec2-onprem-migration)
+ [Amazon ECS での移行](#ecs-migration)
+ [Elastic Beanstalk での移行](#beanstalk-migration)
### 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`)
**Example 設定ファイルを使用する**
```
./xray -c ~/xray-daemon.yaml
```
##### デーモンを実行する
既存の X-Ray デーモンの使用は、次のコマンドで開始されました。
```
~/xray-daemon$ ./xray -o -n us-east-1
```
##### デーモンの削除
Amazon EC2 インスタンスから X-Ray デーモンを削除する方法
1. デーモンサービスを停止します。
```
systemctl stop xray
```
1. 設定ファイルを作成します。
```
rm ~/path/to/xray-daemon.yaml
```
1. 設定されている場合は、ログファイルを削除します。
**注記**
ログファイルの場所は、設定によって異なります。
コマンドライン設定: `/var/log/xray-daemon.log`
設定ファイル: `LogPath` 設定を確認
#### CloudWatch エージェントのセットアップ
##### エージェントのインストール
インストール手順については、「[オンプレミスサーバーに CloudWatch エージェントをインストールする](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_user-first)」を参照してください。
##### エージェントの設定
1. トレース収集を有効にする設定ファイルを作成します。詳細については、「[CloudWatch エージェント設定ファイルを作成する](AmazonCloudWatch/latest/monitoring/create-cloudwatch-agent-configuration-file.html)」を参照してください。
1. IAM 許可をセットアップします。
+ IAM ロールをアタッチするか、エージェントの認証情報を指定します。詳細については、「[IAM ロールの設定](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#install-CloudWatch-Agent-iam_permissions-first)」を参照してください。
+ ロールまたは認証情報に `xray:PutTraceSegments` アクセス許可が含まれていることを確認します。
##### エージェントを開始する
エージェントを起動する手順については、「[Starting the CloudWatch agent using the command line](AmazonCloudWatch/latest/monitoring/install-CloudWatch-Agent-commandline-fleet.html#start-CloudWatch-Agent-EC2-commands-fleet)」を参照してください。
#### OpenTelemetry コレクターのセットアップ
##### コレクターのインストール
オペレーティングシステム用の OpenTelemetry コレクターをダウンロードしてインストールします。手順については、「[コレクターのインストール](https://opentelemetry.io/docs/collector/installation/)」を参照してください。
##### コレクターの設定
コレクターで次のコンポーネントを設定します。
+ awsproxy 拡張機能
X-Ray サンプリングに必要です。
+ OTel レシーバー
アプリケーションからトレースを収集します。
+ xray エクスポーター
X-Ray にトレースを送信します。
**Example サンプルコレクターの設定 — 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 認証情報を設定します。詳細については、「[認証情報の指定](sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials)」を参照してください。
##### コレクターの起動
設定ファイルを使用してコレクターを実行します。
```
otelcol --config=otel-collector-config.yaml
```
### Amazon ECS での移行
**重要**
タスクロールには、使用するコレクターに対する `xray:PutTraceSegments` アクセス許可が必要です。
ポートの競合を防ぐため、同じホストで CloudWatch エージェントまたは OpenTelemetry コレクターコンテナを実行する前に、既存の X-Ray デーモンコンテナを停止してください。
#### CloudWatch エージェントの使用
1. [Amazon ECR Public Gallery](https://gallery.ecr.aws/cloudwatch-agent/cloudwatch-agent) から Docker イメージを取得します。
1. `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"
}
}
}
}
```
1. Systems Manager Parameter Store にエージェント設定を保存します。
1. [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/) を開きます。
1. **[パラメータの作成]** を選択します。
1. 次の値を入力します。
+ 名前: `/ecs/cwagent/otel-config`
+ 利用枠: 標準
+ タイプ: 文字列
+ データ型: テキスト
+ 値: [ここに cw-agent-otel.json 設定を貼り付けます。]
1. ブリッジネットワークモードを使用してタスク定義を作成します。
タスク定義では、使用するネットワーキングモードによって設定が異なります。デフォルトはブリッジネットワーキングで、デフォルトの VPC で使用できます。ブリッジネットワークで、`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 環境変数を設定して、CloudWatch エージェント用のエンドポイントとポートを OpenTelemetry SDK に伝えます。また、アプリケーションの OpenTelemetry SDK から Collector コンテナにトレースを送信するには、アプリケーションコンテナから Collector コンテナへのリンクを作成する必要があります。
**Example 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 エージェントのデプロイ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/deploy-container-insights-ECS-instancelevel.html)」を参照してください。
#### OpenTelemetry コレクターの使用
1. [Docker Hub](https://hub.docker.com/r/otel/opentelemetry-collector-contrib) で Docker イメージ `otel/opentelemetry-collector-contrib` を取得します。
1. 「**Amazon EC2 configuring the collector**」セクションで示したものと同じコンテンツを使用して `otel-collector-config.yaml` という名前の設定ファイルを作成しますが、`127.0.0.1` の代わりに `0.0.0.0` を使用するようにエンドポイントを更新します。
1. Amazon ECS でこの設定を使用する場合は、Systems Manager Parameter Store で設定を保存できます。まず、Systems Manager Parameter Store コンソールに移動し、**[新しいパラメータを作成する]** を選択します。次の情報を使用して新しいパラメータを作成します。
+ 名前: /ecs/otel/config (この名前はコレクターのタスク定義で参照されます。)
+ 利用枠: 標準
+ タイプ: 文字列
+ データ型: テキスト
+ 値: [otel-collector-config.yaml 設定をここに貼り付けます。]
1. 例としてブリッジネットワークモードを使用し、OpenTelemetry コレクターをデプロイするタスク定義を作成します。
タスク定義では、設定は使用するネットワーキングモードによって異なります。デフォルトはブリッジネットワーキングで、デフォルトの VPC で使用できます。ブリッジネットワークで、`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` 環境変数を設定して、OpenTelemetry コレクターのエンドポイントとポートを OpenTelemetry SDK に伝えます。また、アプリケーションの OpenTelemetry SDK から Collector コンテナにトレースを送信するには、アプリケーションコンテナから Collector コンテナへのリンクを作成する必要があります。
**Example 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` という名前のディレクトリを作成します。
1. `.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
```
1. デプロイする際、アプリケーションソースバンドルに `.ebextensions` ディレクトリを含めます。
Elastic Beanstalk 設定ファイルの詳細については、「[設定ファイルによる高度な環境のカスタマイズ](elasticbeanstalk/latest/dg/ebextensions.html)」を参照してください。