AWS X-Ray CLI を利用して AWS API 使用する

AWS CLI では、X-Ray サービスに直接アクセスできます。また、X-Ray コンソールで使用されているものと同じ API を使用して、サービスグラフや未加工のトレースデータを取得できます。サンプルアプリケーションには、AWS CLI でこれらの API を使用する方法を示すスクリプトが含まれています。

前提条件

このチュートリアルでは、Scorekeep サンプルアプリケーションと、それに含まれるトレーシングデータとサービスマップを生成するスクリプトを使用します。入門チュートリアルの指示に従って、アプリケーションを起動します。

このチュートリアルでは、AWS CLI を使用して、X-Ray API の基本的な使用方法を説明します。AWS CLI は Windows、Linux、および OS-X で利用でき、コマンドラインですべての AWS サービス のパブリック API にアクセスすることが可能です。

注記

AWS CLI が、Scorekeep サンプルアプリケーションが作成されたのと同じリージョンに設定されていることを確認する必要があります。

サンプルアプリケーションに含まれるテスト用のスクリプトは、cURL を使用してトラフィックを API および jq に送信し、出力を解析します。jq 実行可能ファイルは stedolan.github.io から、curl 実行可能ファイルは https://curl.haxx.se/download.html からダウンロードできます。ほとんどの Linux および OS X インストールには cURL が含まれています。

トレースデータの生成

ゲームの進行中、ウェブアプリケーションは数秒ごとに API にトラフィックを生成し続けますが、生成されるリクエストのタイプは 1 つだけです。test-api.sh スクリプトを使用して、エンドツーエンドのシナリオを実行し、API のテスト中により多様なトレースデータを生成します。

test-api.sh スクリプトを使用するには

1. Elastic Beanstalk コンソールを開きます。

2. 環境に対応するマネジメントコンソールに移動します。

3. 環境 [URL] をページヘッダーからコピーします。

4. bin/test-api.sh を開いて API の値を環境の URL に置き換えます。

   #!/bin/bash
   API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api

5. スクリプトを実行して 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 アクション (GetServiceGraph および 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 環境を終了するには

1. Elastic Beanstalk コンソールを開きます。

2. 環境に対応するマネジメントコンソールに移動します。

3. [Actions] を選択します。

4. [Terminate Environment] を選択します。

5. [Terminate] (終了) を選択します。

30 日後、トレースデータは自動的に X-Ray から削除されます。