将跟踪数据发送到 Amazon X-Ray - Amazon X-Ray
正在生成跟踪 IDs使用 PutTraceSegments将分段文档发送到 X-Ray 进程守护程序
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

将跟踪数据发送到 Amazon X-Ray

您可以分段文档的形式将跟踪数据发送到 X-Ray。分段文档是 JSON 格式的字符串，其中包含有关您的应用程序在请求服务中所做工作的信息。您的应用程序可以将它自身所做工作的数据记录在分段中，将使用下游服务和资源的工作的数据记录在子分段中。

分段记录有关您的应用程序所做工作的信息。区段至少记录在一项任务上花费的时间、一个名称和两个 IDs。当请求在多个服务之间传输时，跟踪 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。

大多数应用程序使用 Amazon SDK 调用其他服务或访问资源。在子分段中记录有关下游调用的信息。X-Ray 使用子分段来确定未发送分段的下游服务，并在服务图上为其创建条目。

子分段可以嵌入到完整分段文档或者单独发送。对于长时间运行的请求，单独发送子分段以异步跟踪下游调用，或者避免超过最大分段文档大小 (64KB)。

例 子分段

子分段具有 type 的 subsegment 以及标识父分段的 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”
}

有关可包含在分段和子分段中的字段和值的更多信息，请参阅Amazon X-Ray 分段文档。

正在生成跟踪 IDs

要将数据发送到 X-Ray，必须为每个请求生成一个唯一的跟踪 ID。

X-Ray 跟踪 ID 格式

X-Ray trace_id 由以连字符分隔的三组数字组成。例如，1-58406520-a006649127e371903a2de979。这包括：

  • 版本号，即 1。

  • 原始请求的时间，采用 Unix 纪元时间，为 8 个十六进制数字。

    例如，2016 年 12 月 1 日上午 10:00（太平洋标准时间）的纪元时间为 1480615200 秒，或者是十六进制数字 58406520。

  • 跟踪的 96 位全局唯一标识符，使用 24 个十六进制数字。

注意

X-Ray 现在支持使用创建的跟踪 IDs OpenTelemetry 以及任何其他符合 W3C 跟踪上下文规范的框架。发送到 X-Ray 时，W3C 跟踪 ID 必须采用 X-Ray 跟踪 ID 的格式。例如，W3C 跟踪 ID 4efaaf4d1e8720b39541901950019ee5 在发送到 X-Ray 时，应与 1-4efaaf4d-1e8720b39541901950019ee5 的格式相同。X-Ray 跟踪 IDs 包括以 Unix 纪元时间为单位的原始请求时间戳，但是当以 IDs X-Ray 格式发送 W3C 跟踪时，这不是必需的。

您可以编写脚本来生成 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 守护程序的脚本，请参阅 Scorekeeep 示例应用程序。

使用 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 字符串中的引号和转义有不同的要求。有关详细信息，请参阅 用户指南中的为字符串加引号 Amazon 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，而是将分段和子分段发送到 X-Ray 进程守护程序，进程守护程序将缓存它们，然后分批上传到 X-Ray API。X-Ray SDK 将分段文档发送到进程守护程序以避免直接调用 Amazon 。

注意

请参阅 在本地运行 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 终端将分段文档发送给进程守护程序。将标头和分段文档保存到一个文本文件中，然后使用 /dev/udp 以管道形式传送到 cat。

$ 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)