翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
X-Ray API を使用する
X-Ray SDK がプログラミング言語をサポートしていない場合は、X-Ray APIs を直接使用するか、 AWS Command Line Interface （AWS CLI) を使用して X-Ray API コマンドを呼び出すことができます。次のガイダンスを使用して、API の操作方法を選択します。
-
事前フォーマットされたコマンドを使用するか、リクエスト内のオプションを使用して、構文 AWS CLI を簡素化するには、 を使用します。
-
X-Ray API を直接使用して、X-Ray に対して行うリクエストの柔軟性とカスタマイズを最大化します。
の代わりに X-Ray API を直接使用する場合は AWS CLI、リクエストを正しいデータ形式でパラメータ化する必要があり、認証とエラー処理を設定する必要もあります。
次の図は、X-Ray API を操作する方法を選択するガイダンスを示しています。
X-Ray API を使用して、トレースデータを X-Ray に直接送信します。X-Ray API は、以下の一般的なアクションを含め、X-Ray SDK で使用できるすべての関数をサポートします。
-
PutTraceSegments – セグメントドキュメントを X-Ray にアップロードします。
-
BatchGetTraces – トレース IDsのリスト内のトレースのリストを取得します。取得された各トレースは、1 つのリクエストからのセグメントドキュメントのコレクションです。
-
GetTraceSummaries – トレースIDs と注釈を取得します。を指定
FilterExpressionして、トレース概要のサブセットを取得できます。 -
GetTraceGraph – 特定のトレース ID のサービスグラフを取得します。
-
GetServiceGraph – 受信リクエストを処理し、ダウンストリームリクエストを呼び出す のサービスを説明するJSONフォーマットされたドキュメントを取得します。
アプリケーションコード内で AWS Command Line Interface （AWS CLI) を使用して、プログラムで X-Ray とやり取りすることもできます。 AWS CLI は、X-Ray SDK で使用できるすべての関数をサポートします。これには、他の 用の関数も含まれます AWS のサービス。次の関数は、前述の API オペレーションのバージョンで、形式がよりシンプルです。
-
put-trace-segments
– セグメントドキュメントを X-Ray にアップロードします。 -
batch-get-traces
– トレース IDsのリスト内のトレースのリストを取得します。取得された各トレースは、1 つのリクエストからのセグメントドキュメントのコレクションです。 -
get-trace-summaries
– トレースIDs と注釈を取得します。を指定 FilterExpressionして、トレース概要のサブセットを取得できます。 -
get-trace-graph
– 特定のトレース ID のサービスグラフを取得します。 -
get-service-graph
– 受信リクエストを処理し、ダウンストリームリクエストを呼び出す のサービスを説明する JSONフォーマットされたドキュメントを取得します。
開始するには、オペレーティングシステムAWS CLIの をインストールする必要があります。 はLinux、、 macOS オペレーティングシステム AWS をサポートしていますWindows。X-Ray コマンドのリストの詳細については、AWS CLI 「X-Ray の コマンドリファレンスガイド
X-Ray API の詳細
X-Ray API は、 AWS SDK を介して AWS Command Line Interface、または HTTPS 経由で直接、すべての X-Ray 機能へのアクセスを提供します。X-Ray API リファレンスに、各 API アクションの入力パラメータ、およびフィールドと返されるデータ型が記載されています。
AWS SDK を使用して、X-Ray API を使用するプログラムを開発できます。X-Ray コンソールと X-Ray デーモンはどちらも AWS SDK を使用して X-Ray と通信します。各言語の AWS SDK には、X-Ray API アクションとタイプにマッピングするクラスとメソッドのリファレンスドキュメントがあります。
AWS SDK リファレンス
-
Java – AWS SDK for Java
-
JavaScript – AWS SDK for JavaScript
-
.NET – AWS SDK for .NET
-
Ruby – AWS SDK for Ruby
-
Go – AWS SDK for Go
-
PHP – AWS SDK for PHP
-
Python – AWS SDK for Python (Boto)
AWS Command Line Interface は、 SDK for Python を使用して AWS APIsを呼び出すコマンドラインツールです。 AWS API を初めて学習する場合、 は利用可能なパラメータを調べ、JSON またはテキスト形式でサービス出力を表示する簡単な方法 AWS CLI を提供します。
aws xray サブAWS CLI コマンドの詳細については、「 コマンドリファレンス」を参照してください。
AWS CLI を使用すると、X-Ray サービスに直接アクセスし、X-Ray コンソールがサービスグラフと raw トレースデータを取得するために使用するのと同じ APIs を使用できます。サンプルアプリケーションには、 AWS CLI でこれらの APIs を使用する方法を示すスクリプトが含まれています。
前提条件
このチュートリアルでは、Scorekeep サンプルアプリケーションと、それに含まれるトレーシングデータとサービスマップを生成するスクリプトを使用します。サンプルアプリケーションチュートリアルの指示に従って、アプリケーションを起動します。
このチュートリアルでは、 AWS CLI を使用して X-Ray API の基本的な使用法を示します。Windows、Linux、および OS-X で使用できる AWS CLI は、すべての のパブリック APIs へのコマンドラインアクセスを提供します AWS のサービス。
注記
AWS CLI が、サンプルアプリケーションが作成されたリージョンと同じリージョンに設定されていることを確認する必要があります。
サンプルアプリケーションに含まれるテスト用のスクリプトは、cURL を使用してトラフィックを API および jq に送信し、出力を解析します。jq 実行可能ファイルは stedolan.github.iocurl 実行可能ファイルは https://curl.haxx.se/download.html
トレースデータの生成
ゲームの進行中、ウェブアプリケーションは数秒ごとに API にトラフィックを生成し続けますが、生成されるリクエストのタイプは 1 つだけです。test-api.sh スクリプトを使用して、エンドツーエンドのシナリオを実行し、API のテスト中により多様なトレースデータを生成します。
test-api.sh スクリプトを使用するには
Elastic Beanstalk コンソール
を開きます。 環境に対応するマネジメントコンソールに移動します。
-
環境 [URL] をページヘッダーからコピーします。
-
bin/test-api.shを開いて API の値を環境の URL に置き換えます。#!/bin/bash API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api -
スクリプトを実行して API へのトラフィックを生成します。
~/debugger-tutorial$./bin/test-api.shCreating 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 は、 GetServiceGraphや など、X-Ray が提供するすべての API アクションのコマンドを提供しますGetTraceSummaries。サポートされているすべてのアクションおよびそこで使用するデータ型の詳細については、「AWS X-Ray API リファレンス」を参照してください。
例 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",
...例 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"
]例 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 環境を終了するには
Elastic Beanstalk コンソール
を開きます。 環境に対応するマネジメントコンソールに移動します。
-
[アクション] を選択します。
-
[Terminate Environment] を選択します。
-
[Terminate] (終了) を選択します。
30日 後、トレースデータは自動的に X-Ray から削除されます。
トレースデータは、セグメントドキュメントの形式で X-Ray に送信できます。セグメントドキュメントは、アプリケーションがリクエストのサービスで行う作業に関する情報を含む JSON 形式の文字列です。セグメント内で行われる作業、またはサブセグメントのダウンストリームサービスおよびリソースを使用する作業に関するデータはアプリケーションに記録できます。
セグメントは、アプリケーションで行われる作業に関する情報を記録します。セグメントには、少なくとも、タスク、名前、2 つの ID で使用される時間が記録されます。トレース ID は、サービス間でやり取りされるリクエストを追跡します。セグメント ID は、単一のサービスのリクエストで行われる作業を追跡します。
例 最小完了セグメント
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}リクエストを受信したら完了するまで、プレースホルダーとして進行中のセグメントを送信できます。
例 進行中セグメント
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}セグメントは、「PutTraceSegments」、または「X-Ray デーモンを通じて」直接 X-Ray に送信できます。
ほとんどのアプリケーションは、 AWS SDK を使用して他の サービスを呼び出すか、リソースにアクセスします。サブセグメントのダウンストリーム呼び出しに関する情報を記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。
サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズ (64 kB) を超えないようにしたりできます。
例 サブセグメント
サブセグメントには 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”
}セグメントとサブセグメントに含めることができるフィールドと値の詳細については、「X-Ray セグメントドキュメント」を参照してください。
X-Ray にデータを送信するには、リクエストごとに一意のトレース ID を生成する必要があります。
X-Ray トレース ID 形式
X-Ray trace_id は、ハイフンで区切られた 3 つの数字で構成されています。例えば、1-58406520-a006649127e371903a2de979 と指定します。これには、以下のものが含まれます：
-
バージョン番号。
1 -
8 桁の 16 進数を使用した Unix エポック時間での元のリクエストの時刻。
例えば、2016 年 12 月 1 日午前 10:00 PST のエポックタイムは
1480615200秒、1658406520進数です。 -
24 桁の 16 進数のトレースのグローバルに一意の 96 ビット識別子。
注記
X-Ray は、 OpenTelemetry および W3C トレースIDs をサポートするようになりました。 W3C 1-4efaaf4d-1e8720b39541901950019ee5ときに としてフォーマット4efaaf4d1e8720b39541901950019ee5する必要があります。X-Ray トレース IDs には、Unix エポックタイムの元のリクエストタイムスタンプが含まれますが、これは W3C トレース IDs 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 –
xray_start.py -
Bash –
xray_start.sh
セグメントドキュメントは、PutTraceSegments 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 文字列の引用符とエスケープ引用符の要件が異なります。詳細については、 ユーザーガイドの「文字列の引用 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 API に送信する代わりに、セグメントおよびサブセグメントを X-Ray デーモンに送信できます。これにより、バッファされた後、バッチで X-Ray API にアップロードされます。X-Ray SDK は、セグメントドキュメントをデーモンに送信して、 AWS が直接呼び出されないようにします。
注記
デーモンを実行する方法については、「ローカルで X-Ray; デーモンを実行する」を参照してください。
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例 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"}デーモンのログを確認し、セグメントが 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)X-Ray は、送信するトレースデータを処理して、JSON で完全なトレース、トレースの概要、サービスグラフを生成します。生成されたデータは、 AWS CLI を使用して API から直接取得できます。
JSON サービスグラフを取得するには、GetServiceGraph API を使用することができます。この API には、開始時間と終了時間を設定する必要があります。これらは date コマンドを使用して Linux 端末から計算することができます。
$ date +%s
1499394617date +%s は、日付を秒単位で出力します。この数字を終了時間として使用し、日付から差し引いて、開始時間を取得します。
例 最後の 10 分間のサービスグラフを取得するスクリプト。
EPOCH=$(date +%s) aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
次の例では、4 つのノードを持つサービスグラフを示します。これには、クライアントノード、EC2 インスタンス、DynamoDB テーブル、および Amazon SNS トピックが含まれます。
例 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 という名前のグループへのサービスグラフの呼び出しを示します。
例 グループ Example1 の名前別サービスグラフを取得するスクリプト
aws xray get-service-graph --group-name "Example1"
GetTraceSummaries API を使用して、トレースサマリのリストを取得します。トレースサマリには、ダウンロードするトレース全体 (注釈、リクエストと応答に関する情報、ID) などを識別するのに使用できる情報が含まれます。
aws xray
get-trace-summaries を呼び出すときに、2 つの TimeRangeType フラグを使用できます。
-
TraceId – デフォルトの
GetTraceSummaries検索では TraceID 時間を使用し、計算[start_time, end_time)範囲内で開始されたトレースを返します。このタイムスタンプの範囲は、 内のタイムスタンプのエンコードに基づいて計算されるか TraceId、手動で定義できます。 -
イベント時間 – 時間の経過とともに発生したイベントを検索するために、 AWS X-Ray ではイベントタイムスタンプを使用してトレースを検索できます。イベント時間では、トレースの開始時間に関係なく、
[start_time, end_time)の範囲内でアクティブなトレースが返されます。
aws xray get-trace-summaries コマンドを使用して、トレースサマリのリストを取得します。次のコマンドは、デフォルト TraceId 時間を使用して、過去 1～2 分間のトレースの概要のリストを取得します。
例 トレースサマリを取得するスクリプト
EPOCH=$(date +%s) aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
例 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 を使用して、BatchGetTraces API でトレース全体を取得します。
例 BatchGetTraces コマンド
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b例 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 はアプリケーションによって送信されたセグメントドキュメントをコンパイルして、完全なトレースドキュメントを作成し、セグメントドキュメントスキーマに準拠しないデータを削除します。詳細については、「X-Ray セグメントドキュメント」を参照してください。
X-Ray は、セグメント自体を送信しないサービスへのダウンストリーム呼び出しの推測セグメントを作成します。たとえば、計測されたクライアントを使用して DynamoDB を呼び出したときに、X-Ray SDK の視点からの呼び出しに関する詳細をサブセグメントに記録します。ただし、DynamoDB は対応するセグメントを送信しません。X-Ray は、サブセグメントの情報を使用して、トレースマップ内の DynamoDB リソースを表す推定セグメントを作成し、トレースドキュメントに追加します。
API から複数のトレースを取得するには、get-trace-summaries の出力から AWS CLI クエリを使用して抽出できるトレース ID のリストが必要です。リストから batch-get-traces の入力にリダイレクトし、特定の時間のトレース全体を取得します。
例 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 を使用してトレースサマリーを生成すると、部分的なトレースサマリーを JSON 形式で再利用して、根本原因に基づいて絞り込まれたフィルター式を作成できます。絞り込みのステップのウォークスルーについては、以下の例を参照してください。
例 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 に存在するすべてのフィールドについて、候補は完全に一致する必要があります。そうしないと、トレースが返されません。削除されたフィールドはワイルドカード値になります。これは、フィルタ式クエリ構造と互換性のある形式です。
例 再フォーマットされた応答時間の根本原因
{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [ { "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }
この JSON は、rootcause.json = #[{}] への呼び出しを通じてフィルタ式の一部として使用されます。フィルター式を使用したクエリの詳細については、「X-Ray コンソールの探索」の「フィルター式の使用」セクションを参照してください。
例 JSON フィルタの例
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
X-Ray にはAPIs が用意されています。
暗号化設定
PutEncryptionConfig を使用して、暗号化に使用する 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) を使用できます。
GetEncryptionConfigを使用して現在の設定を取得します。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 を使用して、アカウントのサンプリングルールを管理できます。サンプリングの詳細については、「」を参照してくださいサンプリングルールを設定する。タグの追加と管理の詳細については、「X-Ray のサンプリングルールとグループのタグ付け」を参照してください。
GetSamplingRulesですべてのサンプリングルールを取得します。
$ 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
}
]
}別のルールに一致しないすべてのリクエストにデフォルトのルールが適用されます。このルールは最も優先度が低く、削除することはできません。ただし、UpdateSamplingRuleを使用してレートとリザーバのサイズを変更できます。
例 UpdateSamplingRuleの API 入力 – 10000-default.json
{ "SamplingRuleUpdate": { "RuleName": "Default", "FixedRate": 0.01, "ReservoirSize": 0 } }
次の例では、以前のファイルを入力として使用し、デフォルトのルールをリザーバなしの 1% に変更します。タグはオプションです。タグを追加する場合は、タグキーが必要で、タグ値はオプションです。サンプリングルールから既存のタグを削除するには、 を使用しますUntagResource。
$ 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
},
CreateSamplingRuleを使用して追加のサンプリングルールを作成します。ルールを作成するときは、ルールフィールドの大部分を指定する必要があります。次の例では 2 つのルールを作成します。この最初のルールでは、Scorekeep サンプルアプリケーションの基本レートを設定します。これは、より優先度の高いルールに一致しない API からのすべてのリクエストに一致します。
例 UpdateSamplingRuleの 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 リクエストです。
例 UpdateSamplingRuleの 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
}
}サンプリングルールを削除するには、DeleteSamplingRuleを使用します。
$ 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 を使用したサービスグラフとメトリクスの操作の詳細については、「X-Ray からデータを取得する」を参照してください。グループの詳細については、「グループを設定する」を参照してください。タグの追加と管理の詳細については、「X-Ray のサンプリングルールとグループのタグ付け」を参照してください。
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。
$ 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 SDK は X-Ray API を使用して、サンプリングルールの取得、サンプリング結果のレポート、クォータの取得を行います。これらの API を使用すれば、サンプリングルールの仕組みを理解したり、X-Ray SDK でサポートされていない言語でサンプリングを実行したりできます。
まず、GetSamplingRulesを使用してすべてのサンプリングルールを取得します。
$ 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
}
]
}
出力には、デフォルトルールとカスタムルールが含まれています。まだサンプリングルールを作成していない場合は、「X-Ray API を使用したサンプリング、グループ、および暗号化設定の構成」を参照してください。
優先度の昇順で受信リクエストのルールを評価します。ルールが一致したら、固定レートとリザーバのサイズを使用してサンプリングデシジョンを作成します。サンプリングされたリクエストを記録し、(トレースを目的とする) サンプリングされていないリクエストは無視します。サンプリングデシジョンが作成されたら、ルールの評価を停止します。
ルールのリザーバのサイズは、固定レートを適用する前に記録する 1 秒あたりのトレースの目標数です。リザーバはすべてのサービスに累積的に適用されるため、直接使用することはできません。ただし、0 以外の場合は、X-Ray がクォータを割り当てるまでリザーバから 1 秒に 1 個トレースを借りることが可能です。クォータを受信する前に、1 秒ごとに最初のリクエストを記録し、追加のリクエストに固定レートを適用します。固定レートは、0～1.00 (100%) の 10 進数です。
次の例は、過去 10 秒間に作成されたサンプリングデシジョンの詳細を含むGetSamplingTargetsの呼び出しを示したものです。
$ 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 つのフィールドは、入力の問題を示している可能性があるため、前回呼び出したGetSamplingRulesの LastRuleModification を確認します。より新しい場合は、そのルールの新しいコピーを取得します。UnprocessedStatistics には、ルールが削除されたこと、入力の統計ドキュメントが古すぎること、またはアクセス許可のエラーが発生していることを示すエラーが含まれている可能性があります。
トレースセグメントは、アプリケーションが対応するリクエストの JSON 表現です。トレースセグメントは、元のリクエストに関する情報、アプリケーションがローカルで実行する作業に関する情報、およびアプリケーションが リソース、HTTP API、SQL データベースに対して行うダウンストリーム呼び出しに関する情報のサブセグメント AWS を記録します。
セグメントドキュメントは、セグメントに関する情報を X-Ray に伝えます。セグメントドキュメントは最大で 64 kB とし、サブセグメントを含むセグメント全体、リクエストが進行中であることを示すセグメントのフラグメント、または別個に送信される単一のサブセグメントを含むことができます。セグメントドキュメントは、PutTraceSegments API を使用して直接 X-Ray に送信できます。
X-Ray はセグメントドキュメントをコンパイルおよび処理し、それぞれGetTraceSummariesおよびBatchGetTraces API を使用してアクセスできる、クエリ可能なトレースサマリおよびトレース全体を生成します。このサービスは、X-Ray に送信するセグメントとサブセグメントに加えて、サブセグメントの情報を使用して推測セグメントを生成し、トレース全体に追加します。推定セグメントは、トレースマップ内のダウンストリームサービスとリソースを表します。
X-Ray は、セグメントドキュメントの JSON スキーマを提供します。スキーマは xray-segmentdocument-schema-v1.0.0 からダウンロードできます。スキーマに示されたフィールドとオブジェクトについては、以下のセクションで詳しく説明します。
セグメントフィールドのサブセットは、フィルタ式で使用するために X-Ray によってインデックスが作成されます。たとえば、セグメントの user フィールドを一意の ID に設定した場合、X-Ray コンソールで、または GetTraceSummaries API を使用して、特定のユーザーに関連付けられたセグメントを検索できます。詳細については、「フィルター式を使用する」を参照してください。
X-Ray SDK でアプリケーションを計測すると、SDK によりセグメントドキュメントが生成されます。セグメントドキュメントを直接 X-Ray に送信する代わりに、SDK がそれらのドキュメントをローカル UDP ポート経由で X-Ray デーモンに送信します。詳細については、「セグメントドキュメントを X-Ray デーモンに送信する」を参照してください。
セグメントは、アプリケーションが対応するリクエストに関する追跡情報を記録します。セグメントは、少なくともリクエストの名前、ID、開始時間、トレース ID、および終了時間を記録します。
例 最小完了セグメント
{
"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 -
8 桁の 16 進数を使用した Unix エポック時間での元のリクエストの時刻。
例えば、2016 年 12 月 1 日午前 10:00 PST のエポックタイムは
1480615200秒、1658406520進数です。 -
24 桁の 16 進数のトレースのグローバルに一意の 96 ビット識別子。
注記
X-Ray は、 OpenTelemetry および W3C トレースIDs をサポートするようになりました。 W3C
W3C トレース ID は、X-Ray に送信するときに X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID は X-Ray に送信する 1-4efaaf4d-1e8720b39541901950019ee5ときに としてフォーマット4efaaf4d1e8720b39541901950019ee5する必要があります。X-Ray トレース IDs には、Unix エポックタイムの元のリクエストタイムスタンプが含まれますが、これは W3C トレース IDs X-Ray 形式で送信する場合には必要ありません。トレース ID セキュリティ
トレース ID はレスポンスヘッダーに表示されます。攻撃者が将来のトレース 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 は、セグメントを生成するサービスのドメイン名または論理名と一致する必要があります。ただし、これは強制ではありません。権限を持つアプリケーションPutTraceSegmentsは、任意の名前でセグメントを送信できます。
次のフィールドは、セグメントではオプションです。
オプションのセグメントフィールド
-
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 呼び出しのトレースヘッダーに追加します。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。 -
http– 元の HTTP リクエストに関する情報を含むhttpオブジェクト。 -
aws– アプリケーションがリクエストを処理した AWS リソースに関する情報を含む aws オブジェクト。 -
error、throttle、fault、cause– エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む error フィールド。 -
annotations– X-Ray で検索用にインデックスを作成するキーと値のペアを含むannotationsオブジェクト。 -
metadata– セグメントに保存する追加のデータを含むmetadataオブジェクト。 -
subsegments– オブジェクトの配列subsegment。
サブセグメントを作成して、 AWS SDK で行った AWS のサービス およびリソースへの呼び出し、内部または外部の HTTP ウェブ APIsへの呼び出し、または SQL データベースクエリを記録できます。また、サブセグメントを作成してアプリケーションでコードブロックをデバッグしたり、注釈を付けたりできます。サブセグメントには他のサブセグメントを含めることができるため、内部関数呼び出しに関するメタデータを記録するカスタムサブセグメントには、他のカスタムサブセグメントおよびダウンストリーム呼び出し用のサブセグメントを含めることができます。
サブセグメントは、ダウンストリーム呼び出しを、それを呼び出したサービスの視点から記録します。X-Ray はサブセグメントを使用して、セグメントを送信しないダウンストリームサービスを識別し、そのエントリをサービスグラフに作成します。
サブセグメントはフルセグメントドキュメントに埋め込むことも、個別に送信することもできます。サブセグメントを個別に送信して、長期実行されているリクエストのダウンストリーム呼び出しを非同期でトレースしたり、セグメントドキュメントの最大サイズを超えないようにしたりできます。
例 埋め込みサブセグメントを含むセグメント
独立したサブセグメントには、親セグメントを識別する 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 に通知し、セグメントを個別に送信して追跡してから、元のリクエストを完了することができます。
例 進行中セグメント
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}例 独立したサブセグメント
独立したサブセグメントには、親セグメントを識別する 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 -
8 桁の 16 進数を使用した Unix エポック時間での元のリクエストの時刻。
例えば、2016 年 12 月 1 日午前 10:00 PST のエポックタイムは
1480615200秒、1658406520進数です。 -
24 桁の 16 進数のトレースのグローバルに一意の 96 ビット識別子。
注記
X-Ray は、 OpenTelemetry および W3C トレースIDs をサポートするようになりました。 W3C
W3C トレース ID は、X-Ray に送信するときに X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID は X-Ray に送信する 1-4efaaf4d-1e8720b39541901950019ee5ときに としてフォーマット4efaaf4d1e8720b39541901950019ee5する必要があります。X-Ray トレース IDs には、Unix エポックタイムの元のリクエストタイムスタンプが含まれますが、これは W3C トレース IDs X-Ray 形式で送信する場合には必要ありません。 -
-
parent_id– サブセグメントの親セグメントのセグメント ID。サブセグメントを個別に送信する場合にのみ必要です。ネストされたサブセグメントの場合、サブセグメントは親としてセグメントまたはサブセグメントを持つことができます。 -
type–subsegment。サブセグメントを個別に送信する場合にのみ必要です。
次のフィールドは、サブセグメントではオプションです。
オプションのサブセグメントフィールド
-
namespace– AWS SDK 呼び出しの場合はaws、他のダウンストリーム呼び出しの場合はremote。 -
http– 送信 HTTP 呼び出しに関する情報を含むhttpオブジェクト。 -
aws– アプリケーションが呼び出したダウンストリーム AWS リソースに関する情報を含む aws オブジェクト。 -
error、throttle、fault、cause– エラーが発生したことを示し、エラーの原因となった例外に関する情報を含む error フィールド。 -
annotations– X-Ray で検索用にインデックスを作成するキーと値のペアを含むannotationsオブジェクト。 -
metadata– セグメントに保存する追加のデータを含むmetadataオブジェクト。 -
subsegments– subsegmentオブジェクトの配列。 -
precursor_ids– このサブセグメントの前に完了した同じ親を持つサブセグメントを識別するサブセグメント ID の配列。
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 の推測セグメントを生成します。
例 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
}
}例 ダウンストリーム 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
}
}
}例 ダウンストリーム 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 の注釈までインデックスを付けます。
例 注釈を使用した 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) を超えない限り、任意のサイズにすることができます。BatchGetTraces API によって返された完全なセグメントドキュメントで、メタデータを表示できます。で始まるフィールドキー (debug次の例では ) AWS.は、 AWSが提供する SDKs とクライアントが使用するために予約されています。
例 カスタムサブセグメントとメタデータ
{
"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 オブジェクトはアプリケーションが実行されているリソースに関する情報を含みます。複数のフィールドを単一のリソースに適用できます。たとえば、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 のタイプ。
-
例 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 テーブルのオペレーションの場合、テーブルの名前。
例 項目を保存するための 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
すべてのフィールドはオプションです。
-
connection_string– SQL Server または URL 接続文字列を使用しないその他のデータベース接続の場合は、パスワードを除く接続文字列を記録します。 -
url– URL 接続文字列を使用するデータベース接続の場合は、パスワードを除く URL を記録します。 -
sanitized_query– データベースクエリと、プレースホルダーによって削除または置換されたユーザー指定の値。 -
database_type– データベースエンジンの名前。 -
database_version– データベースエンジンのバージョン番号。 -
driver_version– アプリケーションが使用するデータベースエンジンドライバーの名前とバージョン番号。 -
user– データベースユーザー名。 -
preparation– クエリでcallを使用した場合はPreparedCall、クエリでstatementを使用した場合はPreparedStatement。
例 サブセグメントと 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=?;"
}
}