翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # X-Ray API を使用する X-Ray SDK がご使用のプログラミング言語をサポートしていない場合は、X-Ray API を直接使用、または AWS Command Line Interface (AWS CLI) を使用して X-Ray API コマンドを呼び出せます。次のガイダンスを使用して、API の操作方法を選択します。 + 事前フォーマットされたコマンドを使用した、またはリクエスト内のオプションを使用した、単純な構文の AWS CLI を使用します。 + X-Ray API を直接使用して、X-Ray に対するリクエストの柔軟性とカスタマイズを最大限活用します。 AWS CLI の代わりに [X-Ray API](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) を直接使用する場合は、リクエストを正しいデータ形式でパラメータ化する必要があり、認証およびエラー処理を設定する必要もある場合があります。 次の図は、X-Ray API の操作方法の選択のためのガイダンスを示しています。 ![\[X-Ray は、アプリケーションリクエストに関する詳細情報を表示します。\]](http://docs.aws.amazon.com/ja_jp/xray/latest/devguide/images/api-vs-cli.png) X-Ray API を使用してトレースデータを X-Ray に直接送信します。X-Ray API は、以下の一般的なアクションを含む、X-Ray SDK で使用可能なすべての関数をサポートしています。 + [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) - セグメントのドキュメントを X-Ray にアップロードします。 + [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) - トレース ID のリスト内のトレースのリストを取得します。取得した各トレースは、単一のリクエストからのセグメントドキュメントのコレクションです。 + [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) - トレースの ID と注釈を取得します。`FilterExpression` を指定するとトレース概要のサブセットを取得できます。 + [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html) - 特定のトレース ID のサービスグラフを取得します。 + [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) - 受信リクエストを処理してダウンストリームリクエストを呼び出すサービスを説明する、JSON 形式のドキュメントを取得します。 アプリケーションコード内の AWS Command Line Interface (AWS CLI) を使用して、プログラムで X-Ray を操作することもできます。AWS CLI は、他の AWS のサービス 用の関数を含む、X-Ray SDK で使用できるすべての関数をサポートします。次の関数は以前にリストされた API オペレーションのバージョンで、より単純な形式になっています。 + [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html) - セグメントのドキュメントを X-Ray にアップロードします。 + [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html) - トレース ID のリスト内のトレースのリストを取得します。取得した各トレースは、単一のリクエストからのセグメントドキュメントのコレクションです。 + [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html) - トレースの ID と注釈を取得します。`FilterExpression` を指定するとトレース概要のサブセットを取得できます。 + [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html) - 特定のトレース ID のサービスグラフを取得します。 + [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html) - 受信リクエストを処理してダウンストリームリクエストを呼び出すサービスを説明する、`JSON` 形式のドキュメントを取得します。 使用するには、オペレーティングシステムに [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) をインストールする必要があります。AWS は Linux、macOS、Windows の各オペレーティングシステムをサポートしています。X-Ray コマンドのリストの詳細については、「[X-Ray の AWS CLI コマンドリファレンスガイド](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html)」を参照してください。 **Topics** + [AWS X-Ray CLI を利用して AWS API 使用する](xray-api-tutorial.md) + [トレースデータを に送信する AWS X-Ray](xray-api-sendingdata.md) + [AWS X-Ray からのデータの取得](xray-api-gettingdata.md) + [AWS X-Ray API を使用したサンプリング、グループ、暗号化設定の構成](xray-api-configuration.md) + [X-Ray API でのサンプリングルールの使用](xray-api-sampling.md) + [AWS X-Ray セグメントドキュメント](xray-api-segmentdocuments.md) # AWS X-Ray CLI を利用して AWS API 使用する AWS CLI では、X-Ray サービスに直接アクセスできます。また、X-Ray コンソールで使用されているものと同じ API を使用して、サービスグラフや未加工のトレースデータを取得できます。サンプルアプリケーションには、AWS CLI でこれらの API を使用する方法を示すスクリプトが含まれています。 ## 前提条件 このチュートリアルでは、Scorekeep サンプルアプリケーションと、それに含まれるトレーシングデータとサービスマップを生成するスクリプトを使用します。[入門チュートリアル](xray-gettingstarted.md)の指示に従って、アプリケーションを起動します。 このチュートリアルでは、AWS CLI を使用して、X-Ray API の基本的な使用方法を説明します。AWS CLI は [Windows、Linux、および OS-X で利用でき](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)、コマンドラインですべての AWS のサービス のパブリック API にアクセスすることが可能です。 **注記** AWS CLI が、Scorekeep サンプルアプリケーションが作成されたのと同じリージョンに設定されていることを確認する必要があります。 サンプルアプリケーションに含まれるテスト用のスクリプトは、`cURL` を使用してトラフィックを API および `jq` に送信し、出力を解析します。`jq` 実行可能ファイルは [stedolan.github.io](https://stedolan.github.io/jq/) から、`curl` 実行可能ファイルは [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html) からダウンロードできます。ほとんどの Linux および OS X インストールには cURL が含まれています。 ## トレースデータの生成 ゲームの進行中、ウェブアプリケーションは数秒ごとに API にトラフィックを生成し続けますが、生成されるリクエストのタイプは 1 つだけです。`test-api.sh` スクリプトを使用して、エンドツーエンドのシナリオを実行し、API のテスト中により多様なトレースデータを生成します。 **`test-api.sh` スクリプトを使用するには** 1. [Elastic Beanstalk コンソール](https://console.aws.amazon.com/elasticbeanstalk)を開きます。 1. 環境に対応する[マネジメントコンソール](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)に移動します。 1. 環境 [**URL**] をページヘッダーからコピーします。 1. `bin/test-api.sh` を開いて API の値を環境の URL に置き換えます。 ``` #!/bin/bash API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api ``` 1. スクリプトを実行して API へのトラフィックを生成します。 ``` ~/debugger-tutorial$ ./bin/test-api.sh Creating users, session, game, configuring game, playing game, ending game, game complete. {"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]} ``` ## X-Ray API を使用する AWS CLI では、X-Ray が提供するすべての API アクション ([https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) および [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)) のコマンドが提供されます。サポートされているすべてのアクションおよびそこで使用するデータ型の詳細については、「[AWS X-Ray API リファレンス](https://docs.aws.amazon.com/xray/latest/api/Welcome.html)」を参照してください。 **Example bin/service-graph.sh** ``` EPOCH=$(date +%s) aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH ``` このスクリプトは直近 10 分のサービスグラフを取得します。 ``` ~/eb-java-scorekeep$ ./bin/service-graph.sh | less { "StartTime": 1479068648.0, "Services": [ { "StartTime": 1479068648.0, "ReferenceId": 0, "State": "unknown", "EndTime": 1479068651.0, "Type": "client", "Edges": [ { "StartTime": 1479068648.0, "ReferenceId": 1, "SummaryStatistics": { "ErrorStatistics": { "ThrottleCount": 0, "TotalCount": 0, "OtherCount": 0 }, "FaultStatistics": { "TotalCount": 0, "OtherCount": 0 }, "TotalCount": 2, "OkCount": 2, "TotalResponseTime": 0.054000139236450195 }, "EndTime": 1479068651.0, "Aliases": [] } ] }, { "StartTime": 1479068648.0, "Names": [ "scorekeep.elasticbeanstalk.com" ], "ReferenceId": 1, "State": "active", "EndTime": 1479068651.0, "Root": true, "Name": "scorekeep.elasticbeanstalk.com", ... ``` **Example bin/trace-urls.sh** ``` EPOCH=$(date +%s) aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL' ``` このスクリプトは 1 分前から 2 分前の間に生成されたトレースの URL を取得します。 ``` ~/eb-java-scorekeep$ ./bin/trace-urls.sh [ "http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438", "http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH", "http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA", "http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466" ] ``` **Example bin/full-traces.sh** ``` EPOCH=$(date +%s) TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text) aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]' ``` このスクリプトは 1 分前から 2 分前の間に生成されたトレース全体を取得します。 ``` ~/eb-java-scorekeep$ ./bin/full-traces.sh | less [ { "Segments": [ { "Id": "3f212bc237bafd5d", "Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}" }, { "Id": "309e355f1148347f", "Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}" } ], "Id": "1-5828d9f2-a90669393f4343211bc1cf75", "Duration": 0.05099987983703613 } ... ``` ## クリーンアップ Elastic Beanstalk 環境を終了し、Amazon EC2 インスタンス、DynamoDB テーブル、およびその他のリソースをシャットダウンします。 **Elastic Beanstalk 環境を終了するには** 1. [Elastic Beanstalk コンソール](https://console.aws.amazon.com/elasticbeanstalk)を開きます。 1. 環境に対応する[マネジメントコンソール](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)に移動します。 1. **[アクション]** を選択します。 1. [**Terminate Environment**] を選択します。 1. **[Terminate]** (終了) を選択します。 30 日後、トレースデータは自動的に X-Ray から削除されます。 # トレースデータを に送信する AWS X-Ray トレースデータは、セグメントドキュメントの形式で X-Ray に送信できます。セグメントドキュメントは、アプリケーションがリクエストのサービスで行う作業に関する情報を含む JSON 形式の文字列です。セグメント内で行われる作業、またはサブセグメントのダウンストリームサービスおよびリソースを使用する作業に関するデータはアプリケーションに記録できます。 セグメントは、アプリケーションで行われる作業に関する情報を記録します。セグメントには、少なくとも、タスク、名前、2 つの ID で使用される時間が記録されます。トレース ID は、サービス間でやり取りされるリクエストを追跡します。セグメント ID は、単一のサービスのリクエストで行われる作業を追跡します。 **Example 最小完了セグメント** ``` { "name" : "Scorekeep", "id" : "70de5b6f19ff9a0a", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "end_time" : 1.478293361449E9 } ``` リクエストを受信したら完了するまで、プレースホルダーとして進行中のセグメントを送信できます。 **Example 進行中セグメント** ``` { "name" : "Scorekeep", "id" : "70de5b6f19ff9a0b", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", “in_progress”: true } ``` セグメントは、「[`PutTraceSegments`](#xray-api-segments)」、または「[X-Ray デーモンを通じて](#xray-api-daemon)」直接 X-Ray に送信できます。 ほとんどのアプリケーションは、 AWS SDK を使用して他の サービスを呼び出したり、リソースにアクセスしたりします。*サブセグメント*のダウンストリーム呼び出しに関する情報を記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。 サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズ (64 kB) を超えないようにしたりできます。 **Example サブセグメント** サブセグメントには `subsegment` の `type` および親セグメントを識別する `parent_id` があります。 ``` { "name" : "www2.example.com", "id" : "70de5b6f19ff9a0c", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979" “end_time” : 1.478293361449E9, “type” : “subsegment”, “parent_id” : “70de5b6f19ff9a0b” } ``` セグメントとサブセグメントに含めることができるフィールドと値の詳細については、「[AWS X-Ray セグメントドキュメント](xray-api-segmentdocuments.md)」を参照してください。 **Topics** + [トレース ID を生成する](#xray-api-traceids) + [PutTraceSegments を使用する](#xray-api-segments) + [セグメントドキュメントを X-Ray デーモンに送信する](#xray-api-daemon) ## トレース ID を生成する X-Ray にデータを送信するには、リクエストごとに一意のトレース ID を生成する必要があります。 **X-Ray のトレース ID 形式** X-Ray `trace_id` は、ハイフンで区切られた 3 つの数字で構成されています。例えば、`1-58406520-a006649127e371903a2de979`。これには、以下のものが含まれます： + バージョン番号、すなわち、`1`。 + 元のリクエストの時刻。ユニックスエポックタイムで、**16 進数 8 桁**で表示されます。 例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は `1480615200` 秒、または 16 進数で `58406520` と表示されます。 + グローバルに一意なトレースの 96 ビットの識別子で、**24 桁の 16 進数**で表示されます。 **注記** X-Ray は、OpenTelemetry、および [W3C トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID `4efaaf4d1e8720b39541901950019ee5` は X-Ray に送信するとき、`1-4efaaf4d-1e8720b39541901950019ee5` の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。 テスト用の X-Ray トレース ID を生成するためのスクリプトを記述することができます。これらはその 2 つの例です。 **Python** ``` import time import os import binascii START_TIME = time.time() HEX=hex(int(START_TIME))[2:] TRACE_ID="1-{}-{}".format(HEX, binascii.hexlify(os.urandom(12)).decode('utf-8')) ``` **Bash** ``` START_TIME=$(date +%s) HEX_TIME=$(printf '%x\n' $START_TIME) GUID=$(dd if=/dev/random bs=12 count=1 2>/dev/null | od -An -tx1 | tr -d ' \t\n') TRACE_ID="1-$HEX_TIME-$GUID" ``` トレース ID を作成し、X-Ray デーモンにセグメントを送信するスクリプトについては、Scorekeep サンプルアプリケーションを参照してください。 + Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py) + Bash – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh) ## PutTraceSegments を使用する セグメントドキュメントは、[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API を使用してアップロードできます。API には、単一のパラメーター (`TraceSegmentDocuments`) があり、これを実行すると、JSON セグメントドキュメントのリストが取得されます。 AWS CLI では、`aws xray put-trace-segments` コマンドを使用してセグメントドキュメントを直接 X-Ray に送信します。 ``` $ DOC='{"trace_id": "1-5960082b-ab52431b496add878434aa25", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"}' $ aws xray put-trace-segments --trace-segment-documents "$DOC" { "UnprocessedTraceSegments": [] } ``` **注記** Windows コマンドプロセッサおよび Windows PowerShell では、JSON 文字列に引用符の使用やエスケープに関する要件が異なります。詳細については、[ ユーザーガイドの「](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings)文字列の引用 AWS CLI 」を参照してください。 この出力には、処理に失敗したセグメントが表示されます。たとえば、トレース ID の日付が遠い過去の場合は、次のようなエラーが表示されます。 ``` { "UnprocessedTraceSegments": [ { "ErrorCode": "InvalidTraceId", "Message": "Invalid segment. ErrorCode: InvalidTraceId", "Id": "6226467e3f845502" } ] } ``` 複数のセグメントドキュメントは、スペースで区切って同時に渡すことができます。 ``` $ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2" ``` ## セグメントドキュメントを X-Ray デーモンに送信する セグメントドキュメントを X-Ray API に送信する代わりに、セグメントおよびサブセグメントを X-Ray デーモンに送信できます。これにより、バッファされた後、バッチで X-Ray API にアップロードされます。X-Ray SDK は、セグメントドキュメントをデーモンに送信して、 AWS が直接呼び出されないようにします。 **注記** デーモンを実行する方法については、「[ローカルで X-Ray; デーモンを実行する](xray-daemon-local.md)」を参照してください。 UDP ポート 2000 経由で JSON でセグメントを送信します。先頭にはデーモンのヘッダー `{"format": "json", "version": 1}\n` を追加します。 ``` {"format": "json", "version": 1}\n{"trace_id": "1-5759e988-bd862e3fe1be46a994272793", "id": "defdfd9912dc5a56", "start_time": 1461096053.37518, "end_time": 1461096053.4042, "name": "test.elasticbeanstalk.com"} ``` Linux では、セグメントドキュメントを Bash ターミナルからデーモンに送信できます。ヘッダーおよびセグメントドキュメントをテキストファイルに保存し、`cat` を使用して `/dev/udp` にパイプします。 ``` $ cat segment.txt > /dev/udp/127.0.0.1/2000 ``` **Example segment.txt** ``` {"format": "json", "version": 1} {"trace_id": "1-594aed87-ad72e26896b3f9d3a27054bb", "id": "6226467e3f845502", "start_time": 1498082657.37518, "end_time": 1498082695.4042, "name": "test.elasticbeanstalk.com"} ``` [デーモンのログ](xray-daemon.md#xray-daemon-logging)を確認し、セグメントが X-Ray に送信されていることを確認します。 ``` 2017-07-07T01:57:24Z [Debug] processor: sending partial batch 2017-07-07T01:57:24Z [Debug] processor: segment batch size: 1. capacity: 50 2017-07-07T01:57:24Z [Info] Successfully sent batch of 1 segments (0.020 seconds) ``` # AWS X-Ray からのデータの取得 AWS X-Ray では、JSON のトレース全体、トレースサマリ、サービスグラフを生成するために送信するトレースデータを処理します。生成されたデータは、AWS CLI を使用して API から直接取得することができます。 **Topics** + [サービスグラフの取得](#xray-api-servicegraph) + [グループ別サービスグラフの取得](#xray-api-servicegraphgroup) + [トレースの取得](#xray-api-traces) + [根本原因分析の取得と絞り込み](#xray-api-analytics) ## サービスグラフの取得 JSON サービスグラフを取得するには、[https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) API を使用することができます。この API には、開始時間と終了時間を設定する必要があります。これらは `date` コマンドを使用して Linux 端末から計算することができます。 ``` $ date +%s 1499394617 ``` `date +%s` は、日付を秒単位で出力します。この数字を終了時間として使用し、日付から差し引いて、開始時間を取得します。 **Example 最後の 10 分間のサービスグラフを取得するスクリプト。** ``` EPOCH=$(date +%s) aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH ``` 次の例では、4 つのノードを持つサービスグラフを示します。これには、クライアントノード、EC2 インスタンス、DynamoDB テーブル、および Amazon SNS トピックが含まれます。 **Example GetServiceGraph 出力** ``` { "Services": [ { "ReferenceId": 0, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Type": "client", "State": "unknown", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 2, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "Aliases": [] } ] }, { "ReferenceId": 1, "Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA", "Names": [ "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA" ], "Type": "AWS::DynamoDB::Table", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "DurationHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ] }, { "ReferenceId": 2, "Name": "xray-sample.elasticbeanstalk.com", "Names": [ "xray-sample.elasticbeanstalk.com" ], "Root": true, "Type": "AWS::EC2::Instance", "State": "active", "StartTime": 1528317567.0, "EndTime": 1528317589.0, "Edges": [ { "ReferenceId": 1, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.12 }, "ResponseTimeHistogram": [ { "Value": 0.076, "Count": 1 }, { "Value": 0.044, "Count": 1 } ], "Aliases": [] }, { "ReferenceId": 3, "StartTime": 1528317567.0, "EndTime": 1528317589.0, "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "Aliases": [] } ], "SummaryStatistics": { "OkCount": 3, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 1, "TotalCount": 1 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 4, "TotalResponseTime": 0.273 }, "DurationHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.005, "Count": 1 }, { "Value": 0.015, "Count": 1 }, { "Value": 0.157, "Count": 1 }, { "Value": 0.096, "Count": 1 } ] }, { "ReferenceId": 3, "Name": "SNS", "Names": [ "SNS" ], "Type": "AWS::SNS", "State": "unknown", "StartTime": 1528317583.0, "EndTime": 1528317589.0, "Edges": [], "SummaryStatistics": { "OkCount": 2, "ErrorStatistics": { "ThrottleCount": 0, "OtherCount": 0, "TotalCount": 0 }, "FaultStatistics": { "OtherCount": 0, "TotalCount": 0 }, "TotalCount": 2, "TotalResponseTime": 0.125 }, "DurationHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ], "ResponseTimeHistogram": [ { "Value": 0.049, "Count": 1 }, { "Value": 0.076, "Count": 1 } ] } ] } ``` ## グループ別サービスグラフの取得 グループの内容に基づきサービスグラフを呼び出すには、`groupName` または `groupARN` を含めます。以下の例では、Example1 という名前のグループへのサービスグラフの呼び出しを示します。 **Example グループ Example1 の名前別サービスグラフを取得するスクリプト** ``` aws xray get-service-graph --group-name "Example1" ``` ## トレースの取得 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API を使用して、トレースサマリのリストを取得します。トレースサマリには、ダウンロードするトレース全体 (注釈、リクエストと応答に関する情報、ID) などを識別するのに使用できる情報が含まれます。 `TimeRangeType` を呼び出すときに、2 つの `aws xray get-trace-summaries` フラグを使用できます。 + **TraceId** – デフォルト `GetTraceSummaries` の検索は TraceID 時間を使用し、計算された `[start_time, end_time)` の範囲内で開始されたトレースを返します。このタイムスタンプの範囲は、TraceId 内のタイムスタンプのエンコードに基づいて計算されるか、手動で定義できます。 + **イベント時間 **– AWS X-Ray では、経時的に発生するイベントを検索するために、イベントのタイムスタンプを使用してトレースを検索できます。イベント時間では、トレースの開始時間に関係なく、`[start_time, end_time)` の範囲内でアクティブなトレースが返されます。 `aws xray get-trace-summaries` コマンドを使用して、トレースサマリのリストを取得します。以下のコマンドは、デフォルトの TraceId 時間を使用して、過去 1 〜 2 分間のトレースサマリーのリストを取得します。 **Example トレースサマリを取得するスクリプト** ``` EPOCH=$(date +%s) aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) ``` **Example GetTraceSummaries 出力** ``` { "TraceSummaries": [ { "HasError": false, "Http": { "HttpStatus": 200, "ClientIp": "205.255.255.183", "HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session", "UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36", "HttpMethod": "POST" }, "Users": [], "HasFault": false, "Annotations": {}, "ResponseTime": 0.084, "Duration": 0.084, "Id": "1-59602606-a43a1ac52fc7ee0eea12a82c", "HasThrottle": false }, { "HasError": false, "Http": { "HttpStatus": 200, "ClientIp": "205.255.255.183", "HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user", "UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36", "HttpMethod": "POST" }, "Users": [ { "UserName": "5M388M1E" } ], "HasFault": false, "Annotations": { "UserID": [ { "AnnotationValue": { "StringValue": "5M388M1E" } } ], "Name": [ { "AnnotationValue": { "StringValue": "Ola" } } ] }, "ResponseTime": 3.232, "Duration": 3.232, "Id": "1-59602603-23fc5b688855d396af79b496", "HasThrottle": false } ], "ApproximateTime": 1499473304.0, "TracesProcessedCount": 2 } ``` 出力のトレース ID を使用して、[https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API でトレース全体を取得します。 **Example BatchGetTraces コマンド** ``` $ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b ``` **Example BatchGetTraces 出力** ``` { "Traces": [ { "Duration": 3.232, "Segments": [ { "Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}", "Id": "1fb07842d944e714" }, { "Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}", "Id": "194fcc8747581230" }, { "Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}", "Id": "00f91aa01f4984fd" }, { "Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}", "Id": "17ba309b32c7fbaf" }, { "Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}", "Id": "1ee3c4a523f89ca5" } ], "Id": "1-59602603-23fc5b688855d396af79b496" } ], "UnprocessedTraceIds": [] } ``` トレース全体には、同一のトレース ID を使用して取得されるすべてのセグメントドキュメントからコンパイルされた、各セグメントのドキュメントが含まれます。これらのドキュメントは、アプリケーションによって X-Ray に送信されたデータを表していません。その代わりに、X-Ray サービスによって生成された処理済みドキュメントを表します。X-Ray はアプリケーションによって送信されたセグメントドキュメントをコンパイルして、完全なトレースドキュメントを作成し、[セグメントドキュメントスキーマ](xray-api-segmentdocuments.md)に準拠しないデータを削除します。 X-Ray は、セグメント自体を送信しないサービスへのダウンストリーム呼び出しの*推測セグメント*を作成します。たとえば、計測されたクライアントを使用して DynamoDB を呼び出したときに、X-Ray SDK の視点からの呼び出しに関する詳細をサブセグメントに記録します。ただし、DynamoDB は対応するセグメントを送信しません。X-Ray は、サブセグメントにある情報を使用して、トレースマップで DynamoDB リソースを表す推測セグメントを作成し、トレースドキュメントに追加します。 API から複数のトレースを取得するには、`get-trace-summaries` の出力から [AWS CLI クエリ](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter)を使用して抽出できるトレース ID のリストが必要です。リストから `batch-get-traces` の入力にリダイレクトし、特定の時間のトレース全体を取得します。 **Example 1 分間のトレース全体を取得するスクリプト。** ``` EPOCH=$(date +%s) TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text) aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]' ``` ## 根本原因分析の取得と絞り込み [GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) を使用して、トレースサマリを生成すると、根本原因に基づいて絞り込まれたフィルタ式を作成するために、部分的なトレースサマリを JSON 形式で再利用できます。絞り込みのステップのウォークスルーについては、以下の例を参照してください。 **Example 例 GetTraceSummaries 出力 - 応答時間の根本原因セクション** ``` { "Services": [ { "Name": "GetWeatherData", "Names": ["GetWeatherData"], "AccountId": 123456789012, "Type": null, "Inferred": false, "EntityPath": [ { "Name": "GetWeatherData", "Coverage": 1.0, 'Remote": false }, { "Name": "get_temperature", "Coverage": 0.8, "Remote": false } ] }, { "Name": "GetTemperature", "Names": ["GetTemperature"], "AccountId": 123456789012, "Type": null, "Inferred": false, "EntityPath": [ { "Name": "GetTemperature", "Coverage": 0.7, "Remote": false } ] } ] } ``` 上記の出力を編集して省略することで、この JSON は一致した根本原因のエンティティのフィルタになる可能性があります。JSON に存在するすべてのフィールドについて、候補は完全に一致する必要があります。そうしないと、トレースが返されません。削除されたフィールドはワイルドカード値になります。これは、フィルタ式クエリ構造と互換性のある形式です。 **Example 再フォーマットされた応答時間の根本原因** ``` { "Services": [ { "Name": "GetWeatherData", "EntityPath": [ { "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] } ``` この JSON は、`rootcause.json = #[{}]` への呼び出しを通じてフィルタ式の一部として使用されます。フィルタ式を使用するクエリの詳細については、「[フィルタ式](xray-console-filters.md)」の章を参照してください。 **Example JSON フィルタの例** ``` rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }] ``` # AWS X-Ray API を使用したサンプリング、グループ、暗号化設定の構成 AWS X-Ray にはAPIs が用意されています。 [サンプリングルールの設定](xray-console-sampling.md) [でのデータ保護AWS X-Ray](xray-console-encryption.md) **Topics** + [暗号化設定](#xray-api-configuration-encryption) + [サンプリングルール](#xray-api-configuration-sampling) + [グループ](#xray-api-configuration-groups) ## 暗号化設定 [https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html) を使用して、暗号化に使用する AWS Key Management Service (AWS KMS) キーを指定します。 **注記** X-Ray は非対称 KMS キーをサポートしていません。 ``` $ aws xray put-encryption-config --type KMS --key-id alias/aws/xray { "EncryptionConfig": { "KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5", "Status": "UPDATING", "Type": "KMS" } } ``` キー ID には、(例に示すような) エイリアス、キー ID、または Amazon リソースネーム (ARN) を使用できます。 [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html)を使用して現在の設定を取得します。X-Ray が設定の適用を終了すると、ステータスが [`UPDATING`] から [`ACTIVE`] に変わります。 ``` $ aws xray get-encryption-config { "EncryptionConfig": { "KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5", "Status": "ACTIVE", "Type": "KMS" } } ``` KMS の使用を停止し、デフォルトの暗号化を使用するには、暗号化タイプを `NONE` に設定します。 ``` $ aws xray put-encryption-config --type NONE { "EncryptionConfig": { "Status": "UPDATING", "Type": "NONE" } } ``` ## サンプリングルール X-Ray API を使用して、アカウントの[サンプリングルール](xray-console-sampling.md)を管理できます。タグの追加と管理の詳細については、「[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)」を参照してください。 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html)ですべてのサンプリングルールを取得します。 ``` $ aws xray get-sampling-rules { "SamplingRuleRecords": [ { "SamplingRule": { "RuleName": "Default", "RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default", "ResourceARN": "*", "Priority": 10000, "FixedRate": 0.05, "ReservoirSize": 1, "ServiceName": "*", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 0.0, "ModifiedAt": 1529959993.0 } ] } ``` 別のルールに一致しないすべてのリクエストにデフォルトのルールが適用されます。このルールは最も優先度が低く、削除することはできません。ただし、[https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)を使用してレートとリザーバのサイズを変更できます。 **Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)の API 入力 – 10000-default.json** ``` { "SamplingRuleUpdate": { "RuleName": "Default", "FixedRate": 0.01, "ReservoirSize": 0 } } ``` 次の例では、以前のファイルを入力として使用し、デフォルトのルールをリザーバなしの 1% に変更します。タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。サンプリングルールから既存のタグを削除するための、[UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)の使用 ``` $ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}] { "SamplingRuleRecords": [ { "SamplingRule": { "RuleName": "Default", "RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default", "ResourceARN": "*", "Priority": 10000, "FixedRate": 0.01, "ReservoirSize": 0, "ServiceName": "*", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 0.0, "ModifiedAt": 1529959993.0 }, ``` [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html)を使用して追加のサンプリングルールを作成します。ルールを作成するときは、ルールフィールドの大部分を指定する必要があります。次の例では 2 つのルールを作成します。この最初のルールでは、Scorekeep サンプルアプリケーションの基本レートを設定します。これは、より優先度の高いルールに一致しない API からのすべてのリクエストに一致します。 **Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)の API 入力 – 9000-base-scorekeep.json** ``` { "SamplingRule": { "RuleName": "base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 5, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1 } } ``` 2 つ目のルールも Scorekeep に適用されますが、このルールはより優先度が高く具体的です。このルールは、ポーリングリクエストに関して非常に低いサンプリングレートを設定します。これらは、ゲームの状態の変更を確認するためにクライアントによって数秒ごとに行われる GET リクエストです。 **Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html)の API 入力 – 5000-polling-scorekeep.json** ``` { "SamplingRule": { "RuleName": "polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1 } } ``` タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。 ``` $ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}] { "SamplingRuleRecord": { "SamplingRule": { "RuleName": "polling-scorekeep", "RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1, "Attributes": {} }, "CreatedAt": 1530574399.0, "ModifiedAt": 1530574399.0 } } $ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json { "SamplingRuleRecord": { "SamplingRule": { "RuleName": "base-scorekeep", "RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 5, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 1530574410.0, "ModifiedAt": 1530574410.0 } } ``` サンプリングルールを削除するには、[https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html)を使用します。 ``` $ aws xray delete-sampling-rule --rule-name polling-scorekeep { "SamplingRuleRecord": { "SamplingRule": { "RuleName": "polling-scorekeep", "RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1, "Attributes": {} }, "CreatedAt": 1530574399.0, "ModifiedAt": 1530574399.0 } } ``` ## グループ X-Ray API を使用して、アカウントのグループを管理することができます。グループは、フィルタ式で定義されるトレースのコレクションです。グループを使用して、追加のサービスグラフを生成し、Amazon CloudWatch メトリクスを指定できます。X-Ray API を使用したサービスグラフとメトリクスの操作の詳細については、「[AWS X-Ray からのデータの取得](xray-api-gettingdata.md)」を参照してください。グループの詳細については、「[グループの設定](xray-console-groups.md)」を参照してください。タグの追加と管理の詳細については、「[X-Ray のサンプリングルールとグループのタグ付け](xray-tagging.md)」を参照してください。 `CreateGroup` を使用してグループを作成します。タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。 ``` $ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}] { "GroupName": "TestGroup", "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID", "FilterExpression": "service(\"example.com\") {fault OR error}" } ``` `GetGroups` を使用して既存のグループをすべて取得します。 ``` $ aws xray get-groups { "Groups": [ { "GroupName": "TestGroup", "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID", "FilterExpression": "service(\"example.com\") {fault OR error}" }, { "GroupName": "TestGroup2", "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID", "FilterExpression": "responsetime > 2" } ], "NextToken": "tokenstring" } ``` `UpdateGroup` を使用してグループを更新します。タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。グループから既存のタグを削除するには、[UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)を使用します。 ``` $ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}] { "GroupName": "TestGroup", "GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID", "FilterExpression": "service(\"example.com\") {fault OR error}" } ``` `DeleteGroup` を使用してグループを削除します。 ``` $ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" { } ``` # X-Ray API でのサンプリングルールの使用 AWS X-Ray SDK は、X-Ray API を使用してサンプリングルールの取得、サンプリング結果の報告、およびクォータの取得を行います。これらの API を使用すれば、サンプリングルールの仕組みを理解したり、X-Ray SDK でサポートされていない言語でサンプリングを実行したりできます。 まず、[https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html)を使用してすべてのサンプリングルールを取得します。 ``` $ aws xray get-sampling-rules { "SamplingRuleRecords": [ { "SamplingRule": { "RuleName": "Default", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default", "ResourceARN": "*", "Priority": 10000, "FixedRate": 0.01, "ReservoirSize": 0, "ServiceName": "*", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 0.0, "ModifiedAt": 1530558121.0 }, { "SamplingRule": { "RuleName": "base-scorekeep", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 2, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 1530573954.0, "ModifiedAt": 1530920505.0 }, { "SamplingRule": { "RuleName": "polling-scorekeep", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1, "Attributes": {} }, "CreatedAt": 1530918163.0, "ModifiedAt": 1530918163.0 } ] } ``` 出力には、デフォルトルールとカスタムルールが含まれています。まだサンプリングルールを作成していない場合は、「[サンプリングルール](xray-api-configuration.md#xray-api-configuration-sampling)」を参照してください。 優先度の昇順で受信リクエストのルールを評価します。ルールが一致したら、固定レートとリザーバのサイズを使用してサンプリングデシジョンを作成します。サンプリングされたリクエストを記録し、(トレースを目的とする) サンプリングされていないリクエストは無視します。サンプリングデシジョンが作成されたら、ルールの評価を停止します。 ルールのリザーバのサイズは、固定レートを適用する前に記録する 1 秒あたりのトレースの目標数です。リザーバはすべてのサービスに累積的に適用されるため、直接使用することはできません。ただし、0 以外の場合は、X-Ray がクォータを割り当てるまでリザーバから 1 秒に 1 個トレースを借りることが可能です。クォータを受信する前に、1 秒ごとに最初のリクエストを記録し、追加のリクエストに固定レートを適用します。固定レートは、0～1.00 (100%) の 10 進数です。 次の例は、過去 10 秒間に作成されたサンプリングデシジョンの詳細を含む[https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html)の呼び出しを示したものです。 ``` $ aws xray get-sampling-targets --sampling-statistics-documents '[ { "RuleName": "base-scorekeep", "ClientID": "ABCDEF1234567890ABCDEF10", "Timestamp": "2018-07-07T00:20:06", "RequestCount": 110, "SampledCount": 20, "BorrowCount": 10 }, { "RuleName": "polling-scorekeep", "ClientID": "ABCDEF1234567890ABCDEF10", "Timestamp": "2018-07-07T00:20:06", "RequestCount": 10500, "SampledCount": 31, "BorrowCount": 0 } ]' { "SamplingTargetDocuments": [ { "RuleName": "base-scorekeep", "FixedRate": 0.1, "ReservoirQuota": 2, "ReservoirQuotaTTL": 1530923107.0, "Interval": 10 }, { "RuleName": "polling-scorekeep", "FixedRate": 0.003, "ReservoirQuota": 0, "ReservoirQuotaTTL": 1530923107.0, "Interval": 10 } ], "LastRuleModification": 1530920505.0, "UnprocessedStatistics": [] } ``` X-Ray からのレスポンスには、リザーバから借りる代わりに使用するクォータが含まれています。この例では、サービスがリザーバから 10 秒間に 10 個のトレースを借り、他の 100 個のリクエストに 10% の固定レートを適用した結果、サンプリングされたリクエストの合計数が 20 個になりました。クォータは (有効期限で示される) 5 分間、または新しいクォータが割り当てられるまで有効です。X-Ray では、ここで割り当てられなかったとしても、デフォルトより長いレポート間隔を割り当てる場合があります。 **注記** 最初の呼び出しのときには、X-Ray からのレスポンスにクォータが含まれていない可能性があります。その場合は、クォータが割り当てられるまで、リザーバからクォータを借り続けてください。 レスポンスの他の 2 つのフィールドは、入力の問題を示している可能性があるため、前回呼び出した[https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html)の `LastRuleModification` を確認します。より新しい場合は、そのルールの新しいコピーを取得します。`UnprocessedStatistics` には、ルールが削除されたこと、入力の統計ドキュメントが古すぎること、またはアクセス許可のエラーが発生していることを示すエラーが含まれている可能性があります。 # AWS X-Ray セグメントドキュメント **トレースセグメント**は、アプリケーションが対応するリクエストの JSON 表現です。トレースセグメントは、元のリクエストに関する情報、アプリケーションがローカルで実行する作業に関する情報、およびアプリケーションが ** リソース、HTTP API、SQL データベースに対して行うダウンストリーム呼び出しに関する情報の**サブセグメントAWSを記録します。 **セグメントドキュメント**は、セグメントに関する情報を X-Ray に伝えます。セグメントドキュメントは最大で 64 kB とし、サブセグメントを含むセグメント全体、リクエストが進行中であることを示すセグメントのフラグメント、または別個に送信される単一のサブセグメントを含むことができます。セグメントドキュメントは、[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API を使用して直接 X-Ray に送信できます。 X-Ray はセグメントドキュメントをコンパイルおよび処理し、それぞれ [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) および [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API を使用してアクセスできる、クエリ可能な**トレースサマリー**および**トレース全体**を生成します。このサービスは、X-Ray に送信するセグメントとサブセグメントに加えて、サブセグメントの情報を使用して**推測セグメント**を生成し、トレース全体に追加します。推定セグメントは、トレースマップのダウンストリームサービスとリソースを表します。 X-Ray は、セグメントドキュメントの **JSON スキーマ**を提供します。スキーマは、「[xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip)」からダウンロードできます。スキーマに示されたフィールドとオブジェクトについては、以下のセクションで詳しく説明します。 セグメントフィールドのサブセットは、フィルタ式で使用するために X-Ray によってインデックスが作成されます。たとえば、セグメントの `user` フィールドを一意の ID に設定した場合、X-Ray コンソールで、または `GetTraceSummaries` API を使用して、特定のユーザーに関連付けられたセグメントを検索できます。詳細については、「[フィルター式の使用](xray-console-filters.md)」を参照してください。 X-Ray SDK でアプリケーションを計測すると、SDK によりセグメントドキュメントが生成されます。セグメントドキュメントを直接 X-Ray に送信する代わりに、SDK がそれらのドキュメントをローカル UDP ポート経由で [X-Ray デーモン](xray-daemon.md)に送信します。詳細については、「[セグメントドキュメントを X-Ray デーモンに送信する](xray-api-sendingdata.md#xray-api-daemon)」を参照してください。 **Topics** + [セグメントフィールド](#api-segmentdocuments-fields) + [サブセグメント](#api-segmentdocuments-subsegments) + [HTTP リクエストデータ](#api-segmentdocuments-http) + [‏注釈](#api-segmentdocuments-annotations) + [メタデータ](#api-segmentdocuments-metadata) + [AWS リソースデータ](#api-segmentdocuments-aws) + [エラーと例外](#api-segmentdocuments-errors) + [SQL クエリ](#api-segmentdocuments-sql) ## セグメントフィールド セグメントは、アプリケーションが対応するリクエストに関する追跡情報を記録します。セグメントは、少なくともリクエストの名前、ID、開始時間、トレース ID、および終了時間を記録します。 **Example 最小完了セグメント** ``` { "name" : "example.com", "id" : "70de5b6f19ff9a0a", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "end_time" : 1.478293361449E9 } ``` 次のフィールドは、セグメントで必須、または条件付きで必須です。 **注記** 特に明記されていない限り、値は文字列である必要があります (最大 250 文字)。 **必須のセグメントフィールド** + `name` – リクエストを処理したサービスの論理名 (最大 **200 文字**)。たとえば、アプリケーション名やドメイン名です。名前には、Unicode 文字、数字、空白、および次の記号を含めることができます:`_` ､`.`､`:`､`/`､`%`､`&`､`#`､`=`､`+`､`\`､`-`､`@` + `id` – セグメントの 64 ビット識別子。**16 進数の数字**であり、同じトレース内のセグメント間で一意です。 + `trace_id` – 1 つのクライアントリクエストから送信されるすべてのセグメントとサブセグメントに接続する一意の識別子です。 **X-Ray のトレース ID 形式** X-Ray `trace_id` は、ハイフンで区切られた 3 つの数字で構成されています。例えば、`1-58406520-a006649127e371903a2de979`。これには、以下のものが含まれます： + バージョン番号、すなわち、`1`。 + 元のリクエストの時刻。ユニックスエポックタイムで、**16 進数 8 桁**で表示されます。 例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は `1480615200` 秒、または 16 進数で `58406520` と表示されます。 + グローバルに一意なトレースの 96 ビットの識別子で、**24 桁の 16 進数**で表示されます。 **注記** X-Ray は、OpenTelemetry、および [W3C トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID `4efaaf4d1e8720b39541901950019ee5` は X-Ray に送信するとき、`1-4efaaf4d-1e8720b39541901950019ee5` の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。 **トレース ID セキュリティ** トレース ID は[レスポンスヘッダー](xray-concepts.md#xray-concepts-tracingheader)に表示されます。攻撃者が将来のトレース ID を計算できないように安全なランダムのアルゴリズムを使用してトレース ID を生成し、その ID を使用してアプリケーションにリクエストを送信します。 + `start_time` – セグメントが作成された時間の**数値** (エポック時間の浮動小数点で表した秒数)。例えば、`1480615200.010`、`1.480615200010E9` です。必要なだけ桁数を使用します。利用できる場合は、マイクロ秒の精度をお勧めします。 + `end_time` – セグメントが切断された時間を表す**数値**。例えば、`1480615200.090`、`1.480615200090E9` です。`end_time` または `in_progress` のいずれかを指定します。 + `in_progress` – ** ではなく ** を設定して、開始されたが完了していないセグメントを記録する`true`ブール値`end_time`。アプリケーションが処理に時間がかかるリクエストを受信したときに、進行中のセグメントを送信して、リクエストの受信を追跡します。レスポンスが送信されると、完了したセグメントが送信され進行中のセグメントを上書きします。リクエストごとに、1 つの完全なセグメントと、1 つまたは 0 個の進行中のセグメントのみを送信します。 **サービス名** セグメントの `name` は、セグメントを生成するサービスのドメイン名または論理名と一致する必要があります。ただし、これは強制ではありません。権限を持つアプリケーション[https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html)は、任意の名前でセグメントを送信できます。 次のフィールドは、セグメントではオプションです。 **オプションのセグメントフィールド** + `service` – アプリケーションに関する情報を含むオブジェクト。 + `version` – リクエストに対応したアプリケーションのバージョンを識別する文字列。 + `user` – リクエストを送信したユーザーを識別する文字列。 + `origin` – アプリケーションを実行している AWS リソースのタイプ。 **サポートされる値** + `AWS::EC2::Instance` – Amazon EC2 インスタンス。 + `AWS::ECS::Container` – Amazon ECS コンテナ。 + `AWS::ElasticBeanstalk::Environment` – Elastic Beanstalk 環境 複数の値をアプリケーションに適用する場合は、最も具体的な値を使用します。たとえば、複数コンテナの Docker Elastic Beanstalk の環境では、Amazon ECS コンテナでアプリケーションが実行され、そのコンテナは Amazon EC2 インスタンスで実行されます。この場合、環境は他の 2 つのリソースの親として、オリジンを `AWS::ElasticBeanstalk::Environment` に設定します。 + `parent_id` – 計測したアプリケーションからリクエストが発信された場合に指定するサブセグメント ID。X-Ray SDK は親サブセグメント ID をダウンストリーム HTTP 呼び出しの[トレースヘッダー](xray-concepts.md#xray-concepts-tracingheader)に追加します。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。 + `http` – 元の HTTP リクエストに関する情報を含む [`http`](#api-segmentdocuments-http) オブジェクト。 + `aws` – アプリケーションがリクエストに対応した[`aws`](#api-segmentdocuments-aws)リソースに関する情報を含む AWS オブジェクト。 + `error`、`throttle`、`fault`、`cause` – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む [error](#api-segmentdocuments-errors) フィールド。 + `annotations` – X-Ray で検索用にインデックスを作成するキーと値のペアを含む [`annotations`](#api-segmentdocuments-annotations) オブジェクト。 + `metadata` – セグメントに保存する追加のデータを含む [`metadata`](#api-segmentdocuments-metadata) オブジェクト。 + `subsegments` – **オブジェクトの**配列[`subsegment`](#api-segmentdocuments-subsegments)。 ## サブセグメント サブセグメントを作成して、AWS のサービス と AWS SDK で作成するリソースへの呼び出し、内部または外部 HTTP ウェブ API への呼び出し、あるいは SQL データベースクエリの呼び出しを記録することができます。また、サブセグメントを作成してアプリケーションでコードブロックをデバッグしたり、注釈を付けたりできます。サブセグメントには他のサブセグメントを含めることができるため、内部関数呼び出しに関するメタデータを記録するカスタムサブセグメントには、他のカスタムサブセグメントおよびダウンストリーム呼び出し用のサブセグメントを含めることができます。 サブセグメントは、ダウンストリーム呼び出しを、それを呼び出したサービスの視点から記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。 サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズを超えないようにしたりできます。 **Example 埋め込みサブセグメントを含むセグメント** 独立したサブセグメントには、親セグメントを識別する `type` の `subsegment`、および `parent_id` があります。 ``` { "trace_id" : "1-5759e988-bd862e3fe1be46a994272793", "id" : "defdfd9912dc5a56", "start_time" : 1461096053.37518, "end_time" : 1461096053.4042, "name" : "www.example.com", "http" : { "request" : { "url" : "https://www.example.com/health", "method" : "GET", "user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7", "client_ip" : "11.0.3.111" }, "response" : { "status" : 200, "content_length" : 86 } }, "subsegments" : [ { "id" : "53995c3f42cd8ad8", "name" : "api.example.com", "start_time" : 1461096053.37769, "end_time" : 1461096053.40379, "namespace" : "remote", "http" : { "request" : { "url" : "https://api.example.com/health", "method" : "POST", "traced" : true }, "response" : { "status" : 200, "content_length" : 861 } } } ] } ``` 長期間実行されるリクエストについては、進行中のセグメントを送信してリクエストが受信されたことを X-Ray に通知し、セグメントを個別に送信して追跡してから、元のリクエストを完了することができます。 **Example 進行中セグメント** ``` { "name" : "example.com", "id" : "70de5b6f19ff9a0b", "start_time" : 1.478293361271E9, "trace_id" : "1-581cf771-a006649127e371903a2de979", "in_progress": true } ``` **Example 独立したサブセグメント** 独立したサブセグメントには、親セグメントを識別する `type` の `subsegment`、`trace_id`、および `parent_id` があります。 ``` { "name" : "api.example.com", "id" : "53995c3f42cd8ad8", "start_time" : 1.478293361271E9, "end_time" : 1.478293361449E9, "type" : "subsegment", "trace_id" : "1-581cf771-a006649127e371903a2de979" "parent_id" : "defdfd9912dc5a56", "namespace" : "remote", "http" : { "request" : { "url" : "https://api.example.com/health", "method" : "POST", "traced" : true }, "response" : { "status" : 200, "content_length" : 861 } } } ``` リクエストが完了したら、`end_time` とともに再送信してセグメントを閉じます。完了セグメントは進行中のセグメントを上書きします。 非同期ワークフローをトリガーした、完了したリクエストに対してサブセグメントを個別に送信することもできます。たとえば、ウェブ API は、ユーザーがリクエストした作業を開始する直前に `OK 200` 応答を返す場合があります。応答が送信されたらすぐに、完全なセグメントを X-Ray に送信し、それに続いて後で完了する作業のサブセグメントを送信できます。セグメントと同様に、サブセグメントフラグメントを送信して、サブセグメントが開始されたことを記録した後で、ダウンストリーム呼び出しが完了したら完全なサブセグメントでそれを上書きできます。 次のフィールドは、サブセグメントで必須、または条件付きで必須です。 **注記** 特に明記されていない限り、値は文字列です (最大 250 文字)。 **必須のサブセグメントフィールド** + `id` – サブセグメントの 64 ビット識別子。**16 進数の数字**であり、同じトレース内のセグメント間で一意です。 + `name` – サブセグメントの論理名。ダウンストリーム呼び出しの場合は、リソースまたはサービスを呼び出した後のサブセグメントの名前。カスタムサブセグメントの場合は、計測するコードの後にサブセグメントの名前を付けます (関数名など)。 + `start_time` – サブセグメントが作成された時間を表す**数値**で、エポック時間を浮動小数点で表した秒 (ミリ秒)。例えば、`1480615200.010`、`1.480615200010E9` です。 + `end_time` – サブセグメントが切断された時間を表す**数値**。例えば、`1480615200.090`、`1.480615200090E9` です。`end_time` または `in_progress` を指定します。 + `in_progress` – ** ではなく ** を設定して、開始されたが完了していないサブセグメントを記録する`true`ブール値`end_time`。ダウンストリームリクエストごとに、1 つの完全なサブセグメントと、1 つまたは 0 個の進行中のサブセグメントのみを送信します。 + `trace_id` – サブセグメントの親セグメントのトレース ID。サブセグメントを個別に送信する場合にのみ必要です。 **X-Ray のトレース ID 形式** X-Ray `trace_id` は、ハイフンで区切られた 3 つの数字で構成されています。例えば、`1-58406520-a006649127e371903a2de979`。これには、以下のものが含まれます： + バージョン番号、すなわち、`1`。 + 元のリクエストの時刻。ユニックスエポックタイムで、**16 進数 8 桁**で表示されます。 例えば、エポックタイムで 2016 年 12 月 1 日 10:00AM PST (太平洋標準時刻) は `1480615200` 秒、または 16 進数で `58406520` と表示されます。 + グローバルに一意なトレースの 96 ビットの識別子で、**24 桁の 16 進数**で表示されます。 **注記** X-Ray は、OpenTelemetry、および [W3C トレースコンテキスト仕様](https://www.w3.org/TR/trace-context/)に準拠するその他のフレームワークを使用して作成されたトレース ID をサポートするようになりました。W3C トレース ID は X-Ray に送信するとき、X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID `4efaaf4d1e8720b39541901950019ee5` は X-Ray に送信するとき、`1-4efaaf4d-1e8720b39541901950019ee5` の形式にする必要があります。X-Ray トレース ID には元のリクエストの Unix エポックタイムのタイムスタンプが含まれますが、これは W3C トレース ID を X-Ray 形式で送信する場合に必要ありません。 + `parent_id` – サブセグメントの親セグメントのセグメント ID。サブセグメントを個別に送信する場合にのみ必要です。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。 + `type` – `subsegment`。サブセグメントを個別に送信する場合にのみ必要です。 次のフィールドは、サブセグメントではオプションです。 **オプションのサブセグメントフィールド** + `namespace` – AWS SDK 呼び出しの場合は `aws`、他のダウンストリーム呼び出しの場合は `remote`。 + `http` – 送信 HTTP 呼び出しに関する情報を含む [`http`](#api-segmentdocuments-http) オブジェクト。 + `aws` – アプリケーションが呼び出したダウンストリーム[`aws`](#api-segmentdocuments-aws)リソースに関する情報を含む AWS オブジェクト。 + `error`、`throttle`、`fault`、`cause` – エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む [error](#api-segmentdocuments-errors) フィールド。 + `annotations` – X-Ray で検索用にインデックスを作成するキーと値のペアを含む [`annotations`](#api-segmentdocuments-annotations) オブジェクト。 + `metadata` – セグメントに保存する追加のデータを含む [`metadata`](#api-segmentdocuments-metadata) オブジェクト。 + `subsegments` – [`subsegment`](#api-segmentdocuments-subsegments)オブジェクトの**配列**。 + `precursor_ids` – このサブセグメントの前に完了した同じ親を持つサブセグメントを識別するサブセグメント ID の**配列**。 ## HTTP リクエストデータ HTTP ブロックを使用して、(セグメントで) アプリケーションが対応した HTTP リクエスト、または (サブセグメントで) アプリケーションがダウンストリーム HTTP API に対して行ったリクエストの詳細を記録します。このオブジェクトのほとんどのフィールドは、HTTP リクエストと応答で見つかった情報にマッピングされます。 **`http`** すべてのフィールドはオプションです。 + `request` – リクエストに関する情報。 + `method` – リクエストメソッド。例えば、`GET`。 + `url` – リクエストのプロトコル、ホスト名、およびパスからコンパイルされた、リクエストの完全な URL。 + `user_agent` – リクエスタのクライアントからのユーザーエージェント文字列。 + `client_ip` – リクエスタの IP アドレス。IP パケットの `Source Address` から、または転送リクエストの場合は `X-Forwarded-For` ヘッダーから取得できます。 + `x_forwarded_for` – (セグメントのみ) ** が ** ヘッダーから読み取られ、偽造されている可能性があるため信頼できないことを示す`client_ip`ブール値`X-Forwarded-For`。 + `traced` – (サブセグメントのみ) ダウンストリーム呼び出しが別の追跡されたサービスであることを示す**ブール値**。このフィールドが `true` に設定されている場合、このブロックを含むサブセグメントの `parent_id` に一致する `id` を含むセグメントをダウンストリームサービスがアップロードするまで、X-Ray はトレースが壊れていると見なします。 + `response` – レスポンスに関する情報。 + `status` – レスポンスの HTTP ステータスを示す**整数**。 + `content_length` – レスポンス本文の長さをバイト単位で示す**整数**。 ダウンストリームウェブ API に対する呼び出しを計測するときは、HTTP リクエストおよびレスポンスに関する情報を含むセグメントを記録します。X-Ray はサブセグメントを使用してリモート API の推測セグメントを生成します。 **Example Amazon EC2 で実行しているアプリケーションにより提供される HTTP 呼び出し用のセグメント** ``` { "id": "6b55dcc497934f1a", "start_time": 1484789387.126, "end_time": 1484789387.535, "trace_id": "1-5880168b-fd5158284b67678a3bb5a78c", "name": "www.example.com", "origin": "AWS::EC2::Instance", "aws": { "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-0b5a4678fc325bg98" }, "xray": { "sdk_version": "2.11.0 for Java" }, }, "http": { "request": { "method": "POST", "client_ip": "78.255.233.48", "url": "http://www.example.com/api/user", "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0", "x_forwarded_for": true }, "response": { "status": 200 } } ``` **Example ダウンストリーム HTTP 呼び出しのサブセグメント** ``` { "id": "004f72be19cddc2a", "start_time": 1484786387.131, "end_time": 1484786387.501, "name": "names.example.com", "namespace": "remote", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } } } ``` **Example ダウンストリーム HTTP 呼び出しの推定セグメント** ``` { "id": "168416dc2ea97781", "name": "names.example.com", "trace_id": "1-62be1272-1b71c4274f39f122afa64eab", "start_time": 1484786387.131, "end_time": 1484786387.501, "parent_id": "004f72be19cddc2a", "http": { "request": { "method": "GET", "url": "https://names.example.com/" }, "response": { "content_length": -1, "status": 200 } }, "inferred": true } ``` ## ‏注釈 セグメントとサブセグメントは、X-Ray がフィルタ式で使用するためにインデックスを作成する 1 つ以上のフィールドが含まれた `annotations` オブジェクトを含むことができます。フィールドは、文字列、数値、またはブール値を持つことができます (オブジェクトや配列を含むことはできません)。X-Ray は、トレースごとに 50 の注釈までインデックスを付けます。 **Example 注釈を使用した HTTP 呼び出しのセグメント** ``` { "id": "6b55dcc497932f1a", "start_time": 1484789187.126, "end_time": 1484789187.535, "trace_id": "1-5880168b-fd515828bs07678a3bb5a78c", "name": "www.example.com", "origin": "AWS::EC2::Instance", "aws": { "ec2": { "availability_zone": "us-west-2c", "instance_id": "i-0b5a4678fc325bg98" }, "xray": { "sdk_version": "2.11.0 for Java" }, }, "annotations": { "customer_category" : 124, "zip_code" : 98101, "country" : "United States", "internal" : false }, "http": { "request": { "method": "POST", "client_ip": "78.255.233.48", "url": "http://www.example.com/api/user", "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0", "x_forwarded_for": true }, "response": { "status": 200 } } ``` キーはフィルタで動作するために英数字である必要があります。アンダースコアは使用できます。その他の記号や空白は使用できません。 ## メタデータ セグメントとサブセグメントは、オブジェクトと配列を含めて、任意の型の値を持つ 1 つ以上のフィールドが含まれた `metadata` オブジェクトを含むことができます。X-Ray はメタデータのインデックスを作成せず、セグメントドキュメントが最大サイズ (64 kB) を超えない限り、任意のサイズにすることができます。[https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API によって返された完全なセグメントドキュメントで、メタデータを表示できます。`debug` で始まるフィールドキー (次の例の `AWS.`) は、AWS が提供する SDK およびクライアントでの使用のために予約されています。 **Example カスタムサブセグメントとメタデータ** ``` { "id": "0e58d2918e9038e8", "start_time": 1484789387.502, "end_time": 1484789387.534, "name": "## UserModel.saveUser", "metadata": { "debug": { "test": "Metadata string from UserModel.saveUser" } }, "subsegments": [ { "id": "0f910026178b71eb", "start_time": 1484789387.502, "end_time": 1484789387.534, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 58, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG", "resource_names": [ "scorekeep-user" ] } } ] } ``` ## AWS リソースデータ セグメントの場合、`aws` オブジェクトはアプリケーションが実行されているリソースに関する情報を含みます。複数のフィールドを単一のリソースに適用できます。たとえば、Elastic Beanstalk の複数コンテナの Docker 環境で実行されているアプリケーションは、Amazon EC2 インスタンス、インスタンス上で実行されている Amazon ECS コンテナ、および Elastic Beanstalk 環境自体に関する情報を持つことができます。 **`aws` (セグメント)** すべてのフィールドはオプションです。 + `account_id` – アプリケーションが別の AWS アカウント にセグメントを送信する場合、アプリケーションを実行しているアカウントの ID を記録します。 + `cloudwatch_logs` – 単一の CloudWatch ロググループを記述するオブジェクトの配列。 + `log_group` – CloudWatch のロググループ名。 + `arn` – CloudWatch のロググループ ARN。 + `ec2` – Amazon EC2 インスタンスに関する情報。 + `instance_id` – EC2 インスタンスのインスタンス ID。 + `instance_size` – EC2 インスタンスのタイプ。 + `ami_id` – Amazon マシンイメージ ID。 + `availability_zone` – インスタンスが実行されているアベイラビリティーゾーン。 + `ecs` – Amazon ECS コンテナに関する詳細。 + `container` – コンテナのホスト名。 + `container_id` – コンテナの完全なコンテナ ID。 + `container_arn` – コンテナインスタンスの ARN。 + `eks` – Amazon EKS クラスターに関する情報。 + `pod` – EKS ポッドのホスト名。 + `cluster_name` – EKS クラスター名。 + `container_id` – コンテナの完全なコンテナ ID。 + `elastic_beanstalk` – Elastic Beanstalk 環境に関する情報。この情報は、最新の Elastic Beanstalk プラットフォームの `/var/elasticbeanstalk/xray/environment.conf` という名前のファイルにあります。 + `environment_name` – 環境の名前。 + `version_label` – リクエストに対応したインスタンスに現在デプロイされているアプリケーションバージョンの名前。 + `deployment_id` – リクエストに対応したインスタンスに対して最後に成功したデプロイの ID を示す**数値**。 + `xray` – 使用した計測のタイプとバージョンに関するメタデータ。 + `auto_instrumentation` – 自動計測が使用されたかどうかを示すブール値 (例えば、Java Agent)。 + `sdk_version` – 使用中の SDK またはエージェントのバージョン。 + `sdk` – SDK のタイプ。 **Example AWSプラグインを使用した ブロック** ``` "aws":{ "elastic_beanstalk":{ "version_label":"app-5a56-170119_190650-stage-170119_190650", "deployment_id":32, "environment_name":"scorekeep" }, "ec2":{ "availability_zone":"us-west-2c", "instance_id":"i-075ad396f12bc325a", "ami_id": }, "cloudwatch_logs":[ { "log_group":"my-cw-log-group", "arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group" } ], "xray":{ "auto_instrumentation":false, "sdk":"X-Ray for Java", "sdk_version":"2.8.0" } } ``` サブセグメントの場合、アプリケーションがアクセスする AWS のサービス およびリソースに関する情報を記録します。X-Ray はこの情報を使用して、サービスマップのダウンストリームサービスを表す推定セグメントを作成します。 **`aws` (サブセグメント)** すべてのフィールドはオプションです。 + `operation` – AWS のサービス またはリソースに対して呼び出された API アクションの名前。 + `account_id` – アプリケーションが別のアカウントのリソースにアクセスするか、別のアカウントにセグメントを送信する場合は、アプリケーションがアクセスした AWS リソースを所有しているアカウントの ID を記録します。 + `region` – リソースがアプリケーションとは異なるリージョンにある場合は、そのリージョンを記録します。例えば、`us-west-2`。 + `request_id` – リクエストの一意の識別子。 + `queue_url` – Amazon SQS キューのオペレーションの場合は、キューの URL。 + `table_name` – DynamoDB テーブルのオペレーションの場合、テーブルの名前。 **Example 項目を保存するための DynamoDB に対する呼び出しのサブセグメント** ``` { "id": "24756640c0d0978a", "start_time": 1.480305974194E9, "end_time": 1.4803059742E9, "name": "DynamoDB", "namespace": "aws", "http": { "response": { "content_length": 60, "status": 200 } }, "aws": { "table_name": "scorekeep-user", "operation": "UpdateItem", "request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG", } } ``` ## エラーと例外 エラーが発生した場合は、エラーと生成された例外に関する詳細を記録できます。アプリケーションがユーザーにエラーを返す場合はセグメントにエラーを記録し、ダウンストリーム呼び出しがエラーを返す場合はサブセグメントにエラーを記録します。 **エラーのタイプ** 次の 1 つ以上のフィールドを `true` に設定して、エラーが発生したことを示します。複合エラーの場合は、複数のタイプを適用できます。たとえば、ダウンストリーム呼び出しからの `429 Too Many Requests` エラーにより、アプリケーションは `500 Internal Server Error` を返すことがあり、その場合は 3 つすべてのタイプが適用されます。 + `error` – クライアントエラーが発生したことを示す**ブール値** (レスポンスステータスコードは 4XX Client Error でした)。 + `throttle` – リクエストが調整されたことを示す**ブール値** (レスポンスステータスコードは *429 Too Many Requests* でした)。 + `fault` – サーバーエラーが発生したことを示す**ブール値** (レスポンスステータスコードは 5XX Server Error でした)。 セグメントまたはサブセグメントに **cause** オブジェクトを含めてエラーの原因を示します。 **`cause`** 原因は、**16 文字**の例外 ID、または次のフィールドを含むオブジェクトとすることができます。 + `working_directory` – 例外が発生したときの作業ディレクトリのフルパス。 + `paths` – 例外が発生したときに使用されているライブラリまたはモジュールへのパスの**配列**。 + `exceptions` – **例外**オブジェクトの**配列**。 1 つまたは複数の**例外**オブジェクトのエラーに関する詳細情報を含めます。 **`exception`** すべてのフィールドはオプションです。 + `id` – 例外の 64 ビット識別子。**16 進数の数字**であり、同じトレース内のセグメント間で一意です。 + `message` – 例外メッセージ。 + `type` – 例外のタイプ。 + `remote` – ダウンストリームサービスによって返されたエラーが原因で例外が発生したことを示す**ブール値**。 + `truncated` – ** から省略されたスタックフレームの数を示す**整数`stack`。 + `skipped` – この例外とその子の間でスキップされた例外 (発生した例外) の数を示す**整数**。 + `cause` – 例外の親 (この例外を発生させた例外) の例外 ID。 + `stack` – **stackFrame** オブジェクトの**配列**。 使用可能な場合、コールスタックに関する情報を **stackFrame** オブジェクトに記録します。 **`stackFrame`** すべてのフィールドはオプションです。 + `path` – ファイルの相対パス。 + `line` – ファイルの行。 + `label` – 関数またはメソッド名。 ## SQL クエリ アプリケーションが SQL データベースに対して実行するクエリのサブセグメントを作成できます。 **`sql`** すべてのフィールドはオプションです。 + `connection_string` – SQL Server または URL 接続文字列を使用しないその他のデータベース接続の場合は、パスワードを除く接続文字列を記録します。 + `url` – URL 接続文字列を使用するデータベース接続の場合は、パスワードを除く URL を記録します。 + `sanitized_query` – データベースクエリと、プレースホルダーによって削除または置換されたユーザー指定の値。 + `database_type` – データベースエンジンの名前。 + `database_version` – データベースエンジンのバージョン番号。 + `driver_version` – アプリケーションが使用するデータベースエンジンドライバーの名前とバージョン番号。 + `user` – データベースユーザー名。 + `preparation` – クエリで `call` を使用した場合は `PreparedCall`、クエリで `statement` を使用した場合は `PreparedStatement`。 **Example サブセグメントと SQL クエリ** ``` { "id": "3fd8634e78ca9560", "start_time": 1484872218.696, "end_time": 1484872218.697, "name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com", "namespace": "remote", "sql" : { "url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb", "preparation": "statement", "database_type": "PostgreSQL", "database_version": "9.5.4", "driver_version": "PostgreSQL 9.4.1211.jre7", "user" : "dbuser", "sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;" } } ```