将跟踪数据发送到 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
}

您可以使用 PutTraceSegments 或通过 X-Ray 进程守护程序直接将分段发送给 X-Ray。

大多数应用程序使用 AWS 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”
}

有关可包含在分段和子分段中的字段和值的更多信息，请参阅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，纪元时间为1480615200秒或十六58406520进制数字。

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

注意

X-Ray 现在支持使用创建的跟踪 ID OpenTelemetry 以及任何其他符合 W3C 跟踪上下文规范的框架。发送到 X-Ray 时，W3C 跟踪 ID 必须采用 X-Ray 跟踪 ID 格式进行格式化。例如，W3C 跟踪 ID 的格式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"

请参阅 Scorekeep 示例应用程序，以了解用于创建跟踪 ID 并将分段发送给 X-Ray 进程守护程序的脚本。

• 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，而是将分段和子分段发送到 X-Ray 进程守护程序，进程守护程序将缓存它们，然后分批上传到 X-Ray API。X-Ray 开发工具包将分段文档发送到进程守护程序以避免直接调用 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 终端将分段文档发送给进程守护程序。将标头和分段文档保存到一个文本文件中，然后使用 /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)