トレースデータを AWS 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”
}

セグメントとサブセグメントに含めることができるフィールドと値の詳細については、「AWS X-Ray セグメントドキュメント」を参照してください。

トレース ID を生成する

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秒または 16 進数58406520です。

• 24 桁の 16 進数 でトレースにグローバルに一意の 96 ビット識別子。

注記

X-Ray は、W3C トレースIDs をサポートするようになりました。 OpenTelemetry W3C W3C トレース ID は、X-Ray に送信する際に X-Ray トレース ID 形式でフォーマットする必要があります。例えば、W3C トレース ID は、X-Ray に送信する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

セグメントドキュメントは、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 デーモンに送信する

セグメントドキュメントを 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)