本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 將追蹤資料傳送至 AWS X-Ray
<a name="xray-api-sendingdata"></a>

您可以將追蹤資料以區段文件的形式傳送至 X-Ray。區段文件是一種 JSON 格式字串，包含您應用程式在處理請求時執行工作的相關資訊。您的應用程式可記錄其在區段中自行執行的工作相關資料，或是在子區段中使用下游服務和資源的工作相關資料。

區段會記錄您應用程式執行工作的相關資訊。區段最少會記錄其在任務上耗費的時間、名稱及兩個 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 [協助程式直接將區段傳送至 X-Ray](#xray-api-daemon)。

大多數應用程式會使用 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
<a name="xray-api-traceids"></a>

若要將資料傳送至 X-Ray，您必須為每個請求產生唯一的追蹤 ID。

**X-Ray 追蹤 ID 格式**

X-Ray `trace_id`由以連字號分隔的三個數字組成。例如 `1-58406520-a006649127e371903a2de979`。其中包含：
+ 版本編號，即 `1`。
+ 使用 **8 個十六進位數字**的 Unix epoch 時間原始請求的時間。

  例如，太平洋標準時間 2016 年 12 月 1 日上午 10：00，以秒`1480615200`為單位或以十六進位數字`58406520`為單位。
+ 追蹤的全域唯一 96 位元識別符，以 **24 個十六進位數字表示**。

**注意**  
X-Ray 現在支援使用 OpenTelemetry 建立IDs，以及符合 [W3C 追蹤內容規格](https://www.w3.org/TR/trace-context/)的任何其他架構。傳送至 X-Ray 時，W3C 追蹤 ID 必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤 ID 的格式`4efaaf4d1e8720b39541901950019ee5`應該如同傳送至 X-Ray `1-4efaaf4d-1e8720b39541901950019ee5`時一樣。X-Ray IDs 包含以 Unix epoch 時間表示的原始請求時間戳記，但在以 X-Ray 格式傳送 W3C 追蹤 IDs 時不需要這樣做。

您可以撰寫指令碼來產生 X-Ray IDs 進行測試。以下是兩個範例。

**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"
```

如需建立追蹤 IDs並將區段傳送至 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
<a name="xray-api-segments"></a>

您可以使用 [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 字串中引述和逸出引述具有不同需求。如需詳細資訊，請參閱 AWS CLI 《 使用者指南》中的[引號字串](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings)。

輸出會列出任何處理失敗的區段。例如，若追蹤 ID 內的日期為距離現在太遠的過去日期，您可能會看到如下的錯誤。

```
{
    "UnprocessedTraceSegments": [
        {
            "ErrorCode": "InvalidTraceId",
            "Message": "Invalid segment. ErrorCode: InvalidTraceId",
            "Id": "6226467e3f845502"
        }
    ]
}
```

您可以同時傳遞多個區段文件，並以空格區隔。

```
$ aws xray put-trace-segments --trace-segment-documents "$DOC1" "$DOC2"
```

## 將區段文件傳送至 X-Ray 協助程式
<a name="xray-api-daemon"></a>

您可以傳送區段和子區段至 X-Ray 協助程式，而不是將區段文件傳送至 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)
```