您可以分段文档的形式将跟踪数据发送到 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 现在支持通过 OpenTelemetry 和任何其他符合 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"
请参阅 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": []
}
注意
关于 JSON 字符串中的引号和转义引号,Windows 命令处理程序和 Windows PowerShell 有不同的要求。有关详细信息,请参阅 用户指南中的为字符串加引号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 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 终端将分段文档发送给进程守护程序。将标头和分段文档保存到一个文本文件中,然后使用 /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)