傳送追蹤資料至 AWS X-Ray - AWS X-Ray
產生追蹤 ID使用 PutTraceSegments將區段文件傳送至 X-Ray 精靈

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

傳送追蹤資料至 AWS X-Ray

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

區段會記錄您應用程式執行工作的相關資訊。區段最少會記錄其在任務上耗費的時間、名稱及兩個 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
}

您可以使用 X 射線精靈直接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 由三個用連字符分隔的數字組成。例如 1-58406520-a006649127e371903a2de979。其中包含：

  • 版本號碼，也就是1。

  • 原始請求的時間在 Unix 紀元時間使用 8 個十六進制數字。

    例如，2016 年 12 月 1 日上午 10:00 PST (以紀元時間表示) 為1480615200秒或十六進58406520位數字。

  • 追蹤的全域唯一 96 位元識別碼，以 24 個十六進位數字顯示。

注意

X-Ray 現在支援使用以 OpenTelemetry 及符合 W3C 追蹤上下文規格的任何其他架構建立的追蹤 ID。傳送至 X-Ray 時，W3C 追蹤識別碼必須格式化為 X-Ray 追蹤 ID 格式。例如，W3C 追蹤識別碼4efaaf4d1e8720b39541901950019ee5應格式化為傳送至 X-Ray 1-4efaaf4d-1e8720b39541901950019ee5 時。X-Ray 跟踪 ID 包括 Unix 紀元時間中的原始請求時間戳，但是在以 X-Ray 格式發送 W3C 跟踪 ID 時，這不是必需的。

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

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 範例應用程式。

使用 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 API，而是將區段和子區段進行緩衝，並分批上傳至 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)