将跟踪数据发送到 AWS X-Ray - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

将跟踪数据发送到 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 开发工具包调用其他服务或访问资源。在子分段 中记录有关下游调用的信息。X-Ray 使用子分段来确定未发送分段的下游服务,并在服务图上为其创建条目。

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

例 子分段

子分段具有 subsegmenttype 以及标识父分段的 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。跟踪 ID 必须满足以下要求。

跟踪 ID 格式

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

  • 版本号,即 1

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

    例如,2016 年 12 月 1 日上午 10:00 (太平洋标准时间) 采用纪元时间为 1480615200,或者是十六进制数字 58406520

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

您可以编写脚本以生成跟踪 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)))

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 守护程序的脚本。

使用 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 开发工具包将分段文档发送到守护程序以避免直接调用 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)