翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# で Step Functions リクエストデータをトレースする AWS X-Ray
[AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) を使用して、ステートマシンのコンポーネントの視覚化、パフォーマンスのボトルネックの特定、およびエラーの原因となったリクエストのトラブルシューティングを行うことができます。ステートマシンはトレースデータを X-Ray に送信し、X-Ray はデータを処理してサービスマップと検索可能なトレースサマリーを生成します。
ステートマシンで X-Ray を有効にすると、X-Ray が利用可能なすべての AWS リージョンで、Step Functions で実行されるリクエストをトレースできます。これにより、Step Functions リクエスト全体の詳細な概要が提供されます。Step Functions は、トレース ID がアップストリームサービスによって渡されない場合でも、ステートマシンを実行するためにトレースを X-Ray に送信します。X-Ray サービスマップを使用して、X-Ray と統合された AWS サービスを含むリクエストのレイテンシーを表示できます。また、サンプリングルールを設定することで、X-Ray で記録するリクエストとサンプリングレートを条件に応じて指定できます。
ステートマシン用 X-Ray が有効にならず、アップストリームサービスがトレース ID を渡さない場合、Step Functions はステートマシン実行用トレースを X-Ray 送信しません。ただし、アップストリームサービスによってトレース ID が渡されると、Step Functions はステートマシン実行のため、トレースを X-Ray に送信します。
両方がサポートされているリージョンでは、Step Functions AWS X-Ray で を使用できます。X-Ray とStep Funcion のリージョンサポートに関する情報については、[Step Functions](https://docs.aws.amazon.com/general/latest/gr/step-functions.html) と [X-Ray](https://docs.aws.amazon.com/general/latest/gr/xray.html) エンドポイントとクォータページを参照してください。
**X-Ray 関数と Step Functions 結合クォータ**
最大 7 日間、トレースにデータを追加し、30 日前のトレースデータと、X-Ray がトレースデータを格納する時間の長さに関するクエリを行うことができます。トレースは X-Ray クォータの対象となります。その他のクォータに加えて、X-Ray は Step Functions ステートマシンに最小保証トレースサイズ 100 KiB を提供します。X-Ray に 100 KiB を超えるトレースデータが提供された場合、トレースがフリーズする可能性があります。X-Ray の他のクォータの詳細については、[X-Ray エンドポイントとクォータ](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray) ページの Service Quotas セクションを参照してください。
**重要**
Step Functions は、[*分散マップ状態*](state-map-distributed.md)によって開始された子ワークフロー実行の X-Ray トレースをサポートしていません。このような実行では、[トレースドキュメントのサイズ制限](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)を簡単に超える可能性があるためです。
**Topics**
+ [セットアップと設定](#xray-concept-create)
+ [概念](#xray-concepts)
+ [サービス統合](#xray-concept-integrations)
+ [X-Ray コンソールの表示](#xray-concept-tracing-details)
+ [Step Functions の X-Ray トレース情報を表示](#concepts-xray-tracing-events)
+ [トレース](#concepts-xray-traces)
+ [サービスマップ](#concepts-xray-tracing-overview)
+ [セグメントとサブセグメント](#concepts-xray-tracing-segments)
+ [分析](#concepts-xray-tracing-analytics)
+ [設定](#concepts-xray-tracing-config)
+ [トレースマップまたはサービスマップにデータがない場合はどうなりますか。](#concepts-xray-troubleshooting)
## セットアップと設定
### ステートマシンの作成時に X-Ray トレースを有効にする
**[Specify details]** (詳細の指定) ページの **[Enable X-Ray tracing]** (X-Ray によるトレースを有効にする) を選択して、新しいステートマシンの作成時に X-Ray トレースを有効にできます。
1. [Step Functions コンソール](https://console.aws.amazon.com/states/home)を開き、**[ステートマシンの作成]** を選択します。
1. **[作成方法を選択]** ページで、適切なオプションを選択してステートマシンを作成します。**[サンプルプロジェクトを実行]** を選択する場合、ステートマシンの作成時に X-Ray トレースを有効にすることはできません。ステートマシンの作成後に X-Ray トレースを有効にする必要があります。既存のステートマシンで X-Ray を有効にする方法の詳細については、「[既存のステートマシンで X-Ray を有効にする](#xray-concept-enable-existing)」を参照してください。
[**次へ**] を選択します。
1. [**詳細の指定**] ページで、ステートマシンを設定します。
1. [**X-Ray トレースを有効にする**] を選択します。
Step Functions ステートマシンは、ステートマシンの実行のために X-Ray にトレースを送信します。
**注記**
既存の IAM ロールの使用を選択する場合は、X-Ray の書き込みを許可を確実に行う必要があります。必要なアクセス許可の詳細については、以下のトピックを参照してください。
### Step Functions AWS X-Ray で を使用する IAM ポリシー
X-Ray のトレースを有効にするには、トレースを許可する適切な許可を含んだ IAM ポリシーが必要です。ステートマシンが他の統合サービスを使用している場合は、追加の IAM ポリシーが必要になる場合があります。特定のサービス統合の IAM ポリシーを参照してください。
既存のステートマシンのために X-Ray のトレースを有効にする場合は、X-Ray のトレースを有効にできる許可を含んだポリシーを追加する必要があります。
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"xray:PutTraceSegments",
"xray:PutTelemetryRecords",
"xray:GetSamplingRules",
"xray:GetSamplingTargets"
],
"Resource": [
"*"
]
}
]
}
```
### 既存のステートマシンで X-Ray を有効にする
既存のステートマシンで X-Ray を有効にする:
1. [Step Functions コンソール](https://console.aws.amazon.com/states/home)で、トレースを有効にするステートマシンを選択します。
1. **[編集]** を選択します。
1. [**X-Ray トレースを有効にする**] を選択します。
追加の変更が必要になる可能性があることを知らせる通知が表示されます。
**注記**
既存のステートマシンで X-Ray を有効にする場合、トレースを実行できるだけのアクセス権限を十分に付与する IAM ポリシーが備わるように調整が必要です。手動で追加するか、生成できます。詳細については、[Step Functions AWS X-Ray で を使用する IAM ポリシー](#xray-iam) の IAM ポリシーのセクションを参照してください。
1. (オプション) X-Ray 権限が含まれるように、ステートマシンの新しいロールを自動生成します。
1. **[保存]** を選択します。
### Step Functions 用 X-Ray トレースを設定
X-Ray トレースを有効にしてステートマシンを初めて実行すると、X-Ray トレースのデフォルトの設定値が使用されます。 AWS X-Ray は、アプリケーションに送信されるすべてのリクエストのデータを収集しません。代わりに、統計的に有意な数のリクエストのデータを収集します。デフォルトでは、毎秒、最初のリクエストを記録し、追加リクエストの 5% を記録します。1 秒あたり 1 つのリクエストが*リザーバ*です。これにより、サービスがリクエストを処理している限り、毎秒少なくとも 1 つのトレースが記録されます。5% は、リザーバサイズを超えて追加リクエストがサンプリングされる*レート*です。
開始時にサービス料がかからないように、デフォルトのサンプリングレートは控えめになっています｡ デフォルトのサンプリングルールを変更し、サービスまたはリクエストのプロパティに基づいてサンプリングを適用する追加のルールを設定するように X-Ray を設定できます。
たとえば、サンプリングを無効にし、状態を変更したり、 AWS アカウント または トランザクションを処理する呼び出しに対するすべてのリクエストをトレースできます。バックグラウンドポーリング、ヘルスチェック、接続保守などの大量の読み取り専用呼び出しには、低いレートでサンプリングを行い、発生した問題に気づけるデータを得ることができます。
ステートマシンのサンプリングルールを設定:
1. [X-Ray コンソール](https://console.aws.amazon.com/xray/home) に移動します。
1. **[Sampling]** (サンプリング) を選択します。
1. ルールを作成するには、**[Create sampling rule]** (サンプリングルールの作成) を選択します。
ルールを編集するには、ルールの名前を選択します。
ルールを削除するには、ルールを選択し、**[Actions]** (アクション) メニューを使用して削除します。
名前や優先度など、既存のサンプリングルールの一部は変更できません。代わりに、既存のルールを追加またはクローンを作成し、望みの変更を行い、新しいルールを活用します。
X-Ray サンプリングルールの詳細および各種パラメータの設定方法については、[X-Ray コンソールにおけるサンプリングルールの設定](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html)を参照してください。
### アップストリームサービスの統合
エクスプレス、同期、標準ワークフローなどの Step Functions ワークフローの実行をアップストリームサービスと統合するには、`traceHeader` を設定する必要があります。API Gateway で HTTP API を使用している場合、これは自動的に行われます。ただし、Lambda 関数や SDK を使用している場合は、[https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) または [https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html) API コールで `traceHeader` を自分で設定する必要があります。
`traceHeader` 形式を `\p{ASCII}∗` として指定する必要があります。また、Step Functions が同じトレース ID を使用できるようにするには、形式を `Root={TRACE_ID};Sampled={1 or 0}` として指定する必要があります。Lambda 関数を使用している場合は、`TRACE_ID` を現在のセグメントのトレース ID に置き換え、サンプリングモードが true の場合は、Sampled フィールドを `1` に設定し、サンプリングモードが false の場合は `0` に設定します。トレース ID をこの形式で指定すると、完全なトレースが確実に得られます。
以下は、`traceHeader` を指定する方法を示すために Python で記述された例です。
```
state_machine = config.get_string_paramter("STATE_MACHINE_ARN")
if (xray_recorder.current_subsegment() is not None and
xray_recorder.current_subsegment().sampled) :
trace_id = "Root={};Sampled=1".format(
xray_recorder.current_subsegment().trace_id
)
else:
trace_id = "Root=not enabled;Sampled=0"
LOGGER.info("trace %s", trace_id)
# execute it
response = states.start_sync_execution(
stateMachineArn=state_machine,
input=event['body'],
name=context.aws_request_id,
traceHeader=trace_id
)
LOGGER.info(response)
```
**X-Ray ヘッダーまたはペイロードのトレース**
X-Ray トレースの場合、すべての AWS サービスは HTTP リクエストの `X-Amzn-Trace-Id`ヘッダーを使用します。トレースを識別するにはヘッダーの使用をお勧めします。`StartExecution` および `StartSyncExecution` API オペレーションでは、リクエストペイロードの本文から `traceHeader` を使用することもできます。**両方の**ソースが指定されている場合、 Step Functions はリクエスト本文**の値よりもヘッダー**値 (推奨) を使用します。
## 概念
### X-Ray コンソール
AWS X-Ray コンソールでは、ステートマシンで X-Ray が有効になっているときにアプリケーションが処理するリクエストのサービスマップとトレースを表示できます。
ステートマシン実行のために X-Ray コンソールにアクセスする方法に関する情報は、[X-Ray コンソールの表示](#xray-concept-tracing-details) を参照してください。
X-Ray コンソールの詳細については、[X-Ray コンソールのドキュメント](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html)を参照してください。
### セグメント、サブセグメント、およびトレース
ステートマシンへのリクエストに関する情報を**セグメント**が記録します。これには、ステートマシンが実行する作業などの情報が含まれており、ダウンストリームコールに関する情報がある**サブセグメント**を含む可能性があります。
**トレース**では、1 つのリクエストで生成されたセグメントをすべて収集します。
### サンプリング
効率的にトレースを行ってアプリケーションが処理するリクエストの代表的なサンプルを提供するため、X-Ray によって**サンプリング**アルゴリズムが適用され、トレースするリクエストが決定されます。これは、サンプリングルールを編集すれば、変更できます。
### メトリクス
ステートマシンの場合、X-Ray は呼び出し時間、状態遷移時間、Step Functions 全実行時間、およびこの実行時間の分散を計測します。この情報には、X-Ray コンソールを通じてアクセスできます。
### 分析
AWS X-Ray Analytics コンソールは、トレースデータを解釈するためのインタラクティブなツールです。現在のトレースセットに関連付けられているグラフとメトリクスおよびフィールドのパネルをクリックして、アクティブなデータセットをきめ細かく絞り込むことができます。ステートマシンのパフォーマンス、パフォーマンス問題の発見と特定方法を分析できます。
X-Ray 分析の詳細については、[AWS X-Ray 「分析コンソールの操作」を参照してください。](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-analytics.html)
## Step Functions サービス統合と X-Ray
Step Functions と統合 AWS するサービスの一部は、リクエストにトレースヘッダーを追加したり、X-Ray デーモンを実行したり、サンプリングの決定を行ったり、トレースデータを X-Ray にアップロード AWS X-Ray したりすることで、 との統合を提供します。その他は AWS X-Ray SDK を使用して計測する必要があります。X-Ray 統合をまだサポートしていないものもあります。Step Functions とのサービス統合を使用する場合は、完全なトレースデータを提供するために X-Ray 統合が必要です。
### ネイティブ X-Ray サポート
ネイティブ X-Ray サポートとのサービス統合には、次のものがあります。
+ [Amazon Simple Notification Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sns.html)
+ [Amazon Simple Queue Service](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-sqs.html)
+ [AWS Lambda](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-lambda.html)
+ AWS Step Functions
### 必要な計器
[X-Ray 計器](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html)が必要なサービス統合:
+ Amazon Elastic Container Service
+ AWS Batch
+ AWS Fargate
### クライアント側のトレースのみ
その他のサービス統合では、X-Ray のトレースはサポートされません。ただし、クライアント側のトレースは引き続き収集できます。
+ Amazon DynamoDB
+ Amazon EMR
+ Amazon SageMaker AI
+ AWS CodeBuild
+ AWS Glue
## X-Ray コンソールの表示
X-Ray は、サービスからセグメント形式でデータを受け取ります。X-Ray は、トレースへの共通リクエストを含むセグメントをグループ化します。X-Ray は、トレースを処理して、アプリケーションのビジュアル表現を提供するサービスグラフを生成します。
ステートマシンの実行をスタートしたら、**[Execution details]** (実行詳細) セクションで **[X-Ray trace map]** (X-Ray トレースマップ) を選択して X-Ray トレースを表示できます。
ステートマシンに対する X-Ray を有効にした後、X-Ray コンソールでその実行のトレース情報を表示できます。
## Step Functions の X-Ray トレース情報を表示
次の手順は、X-Ray を有効にして実行した後にコンソールに表示できる情報の種類を示しています。[Amazon SQS、Amazon SNS、Lambda を使ってコールバックパターンの例を作成する](callback-task-sample-sqs.md) サンプルプロジェクト用 X-Ray トレースが表示されます。
## トレース
実行が完了したら、X-Ray コンソールに移動すると、X-Ray の **[トレース]** ページが表示されます。これにより、サービスマップの概要と、ステートマシンのトレースおよびセグメント情報が表示されます。
![\[ステートマシンの X-Ray トレースのスクリーンショットの例。\]](http://docs.aws.amazon.com/ja_jp/step-functions/latest/dg/images/xray-tracing-overview.png)
## サービスマップ
X-Ray コンソールのサービスマップは、エラーが発生しているサービス、高レイテンシーとの接続があるサービスを特定するか、不成功に終わったリクエストのトレースを識別する助けとなります。
![\[X-Ray トレースのサービスマップに焦点を当てたスクリーンショットの例。\]](http://docs.aws.amazon.com/ja_jp/step-functions/latest/dg/images/xray-tracing-servicemap.png)
トレースマップ上で、サービスノードを選択して、その接続を移動したリクエストを閲覧するため、そのノードまたは 2 つのノード間のエッジへのリクエストを閲覧できます。ここで、`WaitForCallBack` ノードが選択されており、その実行および応答ステータスに関する追加情報を表示できます。
![\[X-Ray トレースノードの例の詳細。\]](http://docs.aws.amazon.com/ja_jp/step-functions/latest/dg/images/xray-tracing-servicemap-detail.png)
X-Ray サービスマップとステートマシンとの相関関係を確認できます。X-Ray をサポートしていれば、Step Functions によって呼び出されるサービス統合ごとにサービスマップノードがあります。
![\[トレースするステートマシンを図で表した例。\]](http://docs.aws.amazon.com/ja_jp/step-functions/latest/dg/images/sample-callback-example.png)
## セグメントとサブセグメント
**トレース**は、1 つのリクエストで生成された**セグメント**を収集します。各セグメントには、リソース名、リクエストの詳細、行った作業の詳細が含まれています。**[Trace]** (トレース) ページでは、セグメントと、拡大した場合は対応するサブセグメントが表示されます。セグメントまたはサブセグメントを選択して、その詳細を表示できます。
サービスマップ上のノードごとに別のセグメントがあります。
![\[ステートマシンのセグメントとサブセグメントのスクリーンショットの例。\]](http://docs.aws.amazon.com/ja_jp/step-functions/latest/dg/images/xray-tracing-segments.png)
セグメントを選択すると、リソース名、リクエストの詳細、行った作業の詳細が含まれています。
セグメントでは、完了した作業に関するデータをサブセグメントに分けることができます。サブセグメントを選択すると、より詳細なタイミング情報と詳細を表示できます。サブセグメントには、 AWS サービス、外部 HTTP API、または SQL データベースへの呼び出しに関する追加の詳細を含めることができます。
## 分析
AWS X-Ray **Analytics** コンソールは、トレースデータを解釈するためのインタラクティブなツールです。これを使用して、ステートマシンのパフォーマンスをより簡単に理解できます。インタラクティブな応答時間グラフと時系列グラフを使用して、トレースを調査、分析、および視覚化できるため、パフォーマンスとレイテンシーの問題を特定するのに役立ちます。
現在のトレースセットに関連付けられているグラフとメトリクスおよびフィールドのパネルをクリックして、アクティブなデータセットをきめ細かく絞り込むことができます。
## 設定
X-Ray コンソールから、サンプリングと暗号化オプションを設定できます。
+ **[Sampling]** (サンプリング) を選択して、サンプリングレートと設定の詳細を表示します。
サンプリングルールを変更して記録するデータの量を制御し、特定の要件に合わせてサンプリング動作を変更できます。
+ **Encryption** (暗号化) を選択して、暗号化設定を変更します。
デフォルトの設定を使用すると、X-Ray ではトレースと保管中のデータを暗号化できます。または、必要に応じて KMS キーを選択できます。後の方法を選択した場合、スタンダード [AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/) 料金が適用されます。
## トレースマップまたはサービスマップにデータがない場合はどうなりますか。
X-Ray が有効なものの、X-Ray コンソールでデータが表示されない場合は、次の点をチェックしてください。
+ IAM ロールを正しく設定して、X-Ray への書き込みが許可されるようにします。
+ サンプリングルールでは、データのサンプリングが許可されています。
+ 新しく作成または変更した IAM ロールが適用されるまでに短い遅延が生じる可能性があるため、数分後にトレースマップまたはサービスマップを再度チェックしてください。
+ X-Ray トレースパネルに**データが見つかりません**と表示される場合は、[IAM アカウント設定](https://console.aws.amazon.com/iam/home?#/account_settings)を確認し、目的のリージョンで AWS Security Token Service が有効になっていることを確認します。詳細については、*IAM ユーザーガイド*[の「 AWS STS でのアクティブ化と非アクティブ化 AWS リージョン](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_enable-regions.html#sts-regions-activate-deactivate)」を参照してください。