翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# トレースデータを に送信する 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)
```