本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 X-Ray API
如果 X-Ray SDK 不支持您的编程语言，可以直接使用 X-Ray API 或 AWS Command Line Interface（AWS CLI）来调用 X-Ray API 命令。使用以下指南来选择与 API 的交互方式：
+ 使用 AWS CLI，通过预先格式化的命令或请求中的选项来简化语法。
+ 直接使用 X-Ray API，以大幅提高灵活性，并根据您向 X-Ray 提出的请求进行自定义。
如果直接使用 [X-Ray API](https://docs.aws.amazon.com/xray/latest/api/Welcome.html) 而不使用 AWS CLI，则必须以正确的数据格式对请求进行参数化处理，可能还必须配置身份验证和错误处理方式。
下图显示了相关指南，可帮助您选择与 X-Ray API 的交互方式：
![\[X-Ray 显示有关应用程序请求的详细信息。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/api-vs-cli.png)
使用 X-Ray API 将跟踪数据直接发送到 X-Ray。X-Ray API 支持 X-Ray SDK 中提供的所有功能，包括以下常见操作：
+ [PutTraceSegments](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) - 将分段文档上传到 X-Ray。
+ [BatchGetTraces](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) - 检索跟踪 ID 列表中的跟踪列表。检索到的每个跟踪是一组来自单个请求的分段文档。
+ [GetTraceSummaries](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) - 检索跟踪的 ID 和注释。您可以指定 `FilterExpression` 来检索跟踪摘要的子集。
+ [GetTraceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceGraph.html) - 检索特定跟踪 ID 的服务图表。
+ [GetServiceGraph](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) - 检索 JSON 格式化文档，其中描述了处理传入请求和调用下游请求的服务。
您还可以在应用程序代码中使用 AWS Command Line Interface（AWS CLI），以编程方式与 X-Ray 进行交互。AWS CLI 支持 X-Ray SDK 中提供的所有功能，包括其他 AWS 服务功能。以下函数是前面列出的 API 操作的版本，格式更简单：
+ [put-trace-segments](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/put-trace-segments.html) - 将分段文档上传到 X-Ray。
+ [batch-get-traces](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/batch-get-traces.html) - 检索跟踪 ID 列表中的跟踪列表。检索到的每个跟踪是一组来自单个请求的分段文档。
+ [get-trace-summaries](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-summaries.html) - 检索跟踪的 ID 和注释。您可以指定 `FilterExpression` 来检索跟踪摘要的子集。
+ [get-trace-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-trace-graph.html) - 检索特定跟踪 ID 的服务图表。
+ [get-service-graph](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/get-service-graph.html) - 检索 `JSON` 格式化文档，其中描述了处理传入请求和调用下游请求的服务。
要开始使用，您必须为自己的操作系统安装 [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。AWS 支持 Linux、macOS 和 Windows 操作系统。有关 X-Ray 命令列表的更多信息，请参阅[针对 X-Ray 的 AWS CLI 命令参考指南](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/xray/index.html)。
**Topics**
+ [将 AWS X-Ray API 与 AWS CLI 配合使用](xray-api-tutorial.md)
+ [正在将跟踪数据发送到 AWS X-Ray](xray-api-sendingdata.md)
+ [从 AWS X-Ray 获取数据](xray-api-gettingdata.md)
+ [使用 AWS X-Ray API 配置采样、分组和加密设置](xray-api-configuration.md)
+ [通过 X-Ray API 使用采样规则](xray-api-sampling.md)
+ [AWS X-Ray 分段文档](xray-api-segmentdocuments.md)
# 将 AWS X-Ray API 与 AWS CLI 配合使用
AWS CLI 让您可以直接访问 X-Ray 服务，使用的是与 X-Ray 控制台检索服务图和原始跟踪数据相同的 API。示例应用程序包括展示如何将这些 API 用于 AWS CLI 的脚本。
## 先决条件
本教程使用 Scorekeep 示例应用程序并包括了用于生成跟踪数据和服务地图的脚本。按照[入门教程](xray-gettingstarted.md)中的说明启动应用程序。
本教程使用 AWS CLI CLI 显示 X-Ray API 的基本用法。AWS可用于 Windows、Linux 和 OS-X[ 的 ](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) CLI 为所有 AWS 服务 提供对公共 API 的命令行访问。
**注意**
必须验证是否将您的 AWS CLI 配置为 Scorekeep 示例应用程序的创建所在的同一区域。
其中包括测试示例应用程序的脚本，该脚本使用 `cURL` 发送流量到 API 和 `jq` 来解析输出。您可以从 `jq`stedolan.github.io[ 下载 ](https://stedolan.github.io/jq/) 可执行文件，从 `curl` 下载 [https://curl.haxx.se/download.html](https://curl.haxx.se/download.html) 可执行文件。大部分 Linux 和 OS X 安装包含 cURL。
## 生成跟踪数据
Web 应用程序在游戏进行中每几秒继续生成对 API 的流量，但仅生成一种类型的请求。在您测试 API 时，使用 `test-api.sh` 脚本运行端到端方案并生成更多样的跟踪数据。
**使用 `test-api.sh` 脚本**
1. 打开 [Elastic Beanstalk 控制台](https://console.aws.amazon.com/elasticbeanstalk)。
1. 导航到您的环境的[管理控制台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)。
1. 从页面标题复制环境 **URL**。
1. 打开 `bin/test-api.sh` 并使用您环境的 URL 替换 API 的值。
```
#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api
```
1. 运行脚本以生成对 API 的流量。
```
~/debugger-tutorial$ ./bin/test-api.sh
Creating users,
session,
game,
configuring game,
playing game,
ending game,
game complete.
{"id":"MTBP8BAS","session":"HUF6IT64","name":"tic-tac-toe-test","users":["QFF3HBGM","KL6JR98D"],"rules":"102","startTime":1476314241,"endTime":1476314245,"states":["JQVLEOM2","D67QLPIC","VF9BM9NC","OEAA6GK9","2A705O73","1U2LFTLJ","HUKIDD70","BAN1C8FI","G3UDJTUF","AB70HVEV"],"moves":["BS8F8LQ","4MTTSPKP","463OETES","SVEBCL3N","N7CQ1GHP","O84ONEPD","EG4BPROQ","V4BLIDJ3","9RL3NPMV"]}
```
## 使用 X-Ray API
AWS CLI 为 X-Ray 提供的所有 API 操作提供命令，包括 [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) 和 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html)。有关所有支持的操作以及这些操作所使用数据类型的更多信息，请参阅 [AWS X-Ray API 参考](https://docs.aws.amazon.com/xray/latest/api/Welcome.html)。
**Example bin/service-graph.sh**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
该脚本检索过去 10 分钟的服务图。
```
~/eb-java-scorekeep$ ./bin/service-graph.sh | less
{
"StartTime": 1479068648.0,
"Services": [
{
"StartTime": 1479068648.0,
"ReferenceId": 0,
"State": "unknown",
"EndTime": 1479068651.0,
"Type": "client",
"Edges": [
{
"StartTime": 1479068648.0,
"ReferenceId": 1,
"SummaryStatistics": {
"ErrorStatistics": {
"ThrottleCount": 0,
"TotalCount": 0,
"OtherCount": 0
},
"FaultStatistics": {
"TotalCount": 0,
"OtherCount": 0
},
"TotalCount": 2,
"OkCount": 2,
"TotalResponseTime": 0.054000139236450195
},
"EndTime": 1479068651.0,
"Aliases": []
}
]
},
{
"StartTime": 1479068648.0,
"Names": [
"scorekeep.elasticbeanstalk.com"
],
"ReferenceId": 1,
"State": "active",
"EndTime": 1479068651.0,
"Root": true,
"Name": "scorekeep.elasticbeanstalk.com",
...
```
**Example bin/trace-urls.sh**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Http.HttpURL'
```
该脚本检索在过去 1 到 2 分钟之间生成的跟踪的 URL。
```
~/eb-java-scorekeep$ ./bin/trace-urls.sh
[
"http://scorekeep.elasticbeanstalk.com/api/game/6Q0UE1DG/5FGLM9U3/endtime/1479069438",
"http://scorekeep.elasticbeanstalk.com/api/session/KH4341QH",
"http://scorekeep.elasticbeanstalk.com/api/game/GLQBJ3K5/153AHDIA",
"http://scorekeep.elasticbeanstalk.com/api/game/VPDL672J/G2V41HM6/endtime/1479069466"
]
```
**Example bin/full-traces.sh**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
该脚本检索在过去 1 到 2 分钟之间生成的完整跟踪。
```
~/eb-java-scorekeep$ ./bin/full-traces.sh | less
[
{
"Segments": [
{
"Id": "3f212bc237bafd5d",
"Document": "{\"id\":\"3f212bc237bafd5d\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242459E9,\"end_time\":1.479072242477E9,\"parent_id\":\"72a08dcf87991ca9\",\"http\":{\"response\":{\"content_length\":60,\"status\":200}},\"inferred\":true,\"aws\":{\"consistent_read\":false,\"table_name\":\"scorekeep-session-xray\",\"operation\":\"GetItem\",\"request_id\":\"QAKE0S8DD0LJM245KAOPMA746BVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-session-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
},
{
"Id": "309e355f1148347f",
"Document": "{\"id\":\"309e355f1148347f\",\"name\":\"DynamoDB\",\"trace_id\":\"1-5828d9f2-a90669393f4343211bc1cf75\",\"start_time\":1.479072242477E9,\"end_time\":1.479072242494E9,\"parent_id\":\"37f14ef837f00022\",\"http\":{\"response\":{\"content_length\":606,\"status\":200}},\"inferred\":true,\"aws\":{\"table_name\":\"scorekeep-game-xray\",\"operation\":\"UpdateItem\",\"request_id\":\"388GEROC4PCA6D59ED3CTI5EEJVV4KQNSO5AEMVJF66Q9ASUAAJG\",\"resource_names\":[\"scorekeep-game-xray\"]},\"origin\":\"AWS::DynamoDB::Table\"}"
}
],
"Id": "1-5828d9f2-a90669393f4343211bc1cf75",
"Duration": 0.05099987983703613
}
...
```
## 清理
终止 Elastic Beanstalk 环境以关闭 Amazon EC2 实例、DynamoDB 表和其他资源。
**终止 Elastic Beanstalk 环境**
1. 打开 [Elastic Beanstalk 控制台](https://console.aws.amazon.com/elasticbeanstalk)。
1. 导航到您的环境的[管理控制台](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environments-console.html)。
1. 选择**操作**。
1. 选择**终止环境**。
1. 选择**终止**。
在 30 之后，跟踪数据自动从 X-Ray 中删除。
# 正在将跟踪数据发送到 AWS X-Ray
您可以分段文档的形式将跟踪数据发送到 X-Ray。分段文档是 JSON 格式的字符串，其中包含有关您的应用程序在请求服务中所做工作的信息。您的应用程序可以将它自身所做工作的数据记录在分段中，将使用下游服务和资源的工作的数据记录在子分段中。
分段记录有关您的应用程序所做工作的信息。区段至少记录在一项任务上花费的时间、一个名称和两个 IDs。当请求在多个服务之间传输时，跟踪 ID 可对请求进行追踪。分段 ID 跟踪单个服务为请求所做的工作。
**Example 最小完成分段**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
当收到请求时，您可以发送正在运行的分段作为占位符，直到该请求完成。
**Example 正在进行分段**
```
{
"name" : "Scorekeep",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
“in_progress”: true
}
```
您可以使用 [`PutTraceSegments`](#xray-api-segments) 或[通过 X-Ray 进程守护程序](#xray-api-daemon)直接将分段发送给 X-Ray。
大多数应用程序使用 AWS SDK 调用其他服务或访问资源。在*子分段*中记录有关下游调用的信息。X-Ray 使用子分段来确定未发送分段的下游服务，并在服务图上为其创建条目。
子分段可以嵌入到完整分段文档或者单独发送。对于长时间运行的请求，单独发送子分段以异步跟踪下游调用，或者避免超过最大分段文档大小 (64KB)。
**Example 子分段**
子分段具有 `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 分段文档](xray-api-segmentdocuments.md)。
**Topics**
+ [正在生成跟踪 IDs](#xray-api-traceids)
+ [使用 PutTraceSegments](#xray-api-segments)
+ [将分段文档发送到 X-Ray 进程守护程序](#xray-api-daemon)
## 正在生成跟踪 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 跟踪上下文](https://www.w3.org/TR/trace-context/)规范的框架。发送到 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 示例应用程序。
+ Python – [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.py)
+ Bash - [https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh](https://github.com/awslabs/eb-java-scorekeep/blob/xray/bin/xray_start.sh)
## 使用 PutTraceSegments
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) 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 字符串中的引号和转义有不同的要求。有关详细信息，请参阅 [ 用户指南中的](https://docs.aws.amazon.com/cli/latest/userguide/cli-using-param.html#quoting-strings)为字符串加引号 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 进程守护程序](xray-daemon-local.md) 获得有关运行进程守护程序的说明。
通过 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
```
**Example 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"}
```
检查[进程守护程序日志](xray-daemon.md#xray-daemon-logging)，验证它是否已将分段发送到 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)
```
# 从 AWS X-Ray 获取数据
AWS X-Ray 处理您发送给它的跟踪数据，以在 JSON 中生成完整跟踪、跟踪摘要和服务图。可以使用 AWS CLI 直接从 API 中检索生成的数据。
**Topics**
+ [检索服务图](#xray-api-servicegraph)
+ [按组检索服务图](#xray-api-servicegraphgroup)
+ [检索跟踪](#xray-api-traces)
+ [检索和细化根本原因分析](#xray-api-analytics)
## 检索服务图
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html](https://docs.aws.amazon.com/xray/latest/api/API_GetServiceGraph.html) API 来检索 JSON 服务图。该 API 需要开始时间和结束时间，您可以使用 `date` 命令从 Linux 终端计算这些时间。
```
$ date +%s
1499394617
```
`date +%s` 显示日期（秒数）。使用该数字作为结束时间，并从中减去一个时间可得到开始时间。
**Example 用于检索最后 10 分钟的服务图的脚本**
```
EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH
```
以下示例显示了一个包含 4 个节点的服务图，其中包括一个客户端节点、一个 EC2 实例、一个 DynamoDB 表和一个 Amazon SNS 主题。
**Example GetServiceGraph 输出**
```
{
"Services": [
{
"ReferenceId": 0,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Type": "client",
"State": "unknown",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 2,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"Aliases": []
}
]
},
{
"ReferenceId": 1,
"Name": "awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA",
"Names": [
"awseb-e-dixzws4s9p-stack-StartupSignupsTable-4IMSMHAYX2BA"
],
"Type": "AWS::DynamoDB::Table",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"DurationHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
]
},
{
"ReferenceId": 2,
"Name": "xray-sample.elasticbeanstalk.com",
"Names": [
"xray-sample.elasticbeanstalk.com"
],
"Root": true,
"Type": "AWS::EC2::Instance",
"State": "active",
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"Edges": [
{
"ReferenceId": 1,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.12
},
"ResponseTimeHistogram": [
{
"Value": 0.076,
"Count": 1
},
{
"Value": 0.044,
"Count": 1
}
],
"Aliases": []
},
{
"ReferenceId": 3,
"StartTime": 1528317567.0,
"EndTime": 1528317589.0,
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"Aliases": []
}
],
"SummaryStatistics": {
"OkCount": 3,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 1,
"TotalCount": 1
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 4,
"TotalResponseTime": 0.273
},
"DurationHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.005,
"Count": 1
},
{
"Value": 0.015,
"Count": 1
},
{
"Value": 0.157,
"Count": 1
},
{
"Value": 0.096,
"Count": 1
}
]
},
{
"ReferenceId": 3,
"Name": "SNS",
"Names": [
"SNS"
],
"Type": "AWS::SNS",
"State": "unknown",
"StartTime": 1528317583.0,
"EndTime": 1528317589.0,
"Edges": [],
"SummaryStatistics": {
"OkCount": 2,
"ErrorStatistics": {
"ThrottleCount": 0,
"OtherCount": 0,
"TotalCount": 0
},
"FaultStatistics": {
"OtherCount": 0,
"TotalCount": 0
},
"TotalCount": 2,
"TotalResponseTime": 0.125
},
"DurationHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
],
"ResponseTimeHistogram": [
{
"Value": 0.049,
"Count": 1
},
{
"Value": 0.076,
"Count": 1
}
]
}
]
}
```
## 按组检索服务图
要根据组的内容调用服务图，请包括 `groupName` 或 `groupARN`。以下示例显示的是对一个名为“Example1”的组进行服务图调用。
**Example 用于按组 Example1 的名称检索服务图的脚本**
```
aws xray get-service-graph --group-name "Example1"
```
## 检索跟踪
您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) API 获取跟踪摘要列表。跟踪摘要包括可用于完整标识要下载的跟踪的信息，包括注释、请求和响应信息以及 ID。
调用 `aws xray get-trace-summaries` 时可以使用两个 `TimeRangeType` 标志：
+ **traceID** — 默认 `GetTraceSummaries` 搜索使用 TraceID 时间并返回在计算的 `[start_time, end_time)` 范围内开始的跟踪。此时间戳范围是根据 TraceID 中时间戳的编码计算得出的，也可以手动定义。
+ **事件时间** - 用于搜索随着时间发生的事件，XAWS-Ray 允许使用事件时间戳搜索跟踪。无论追踪何时开始，事件时间都会返回 `[start_time, end_time)` 范围内处于活动状态的跟踪。
使用 `aws xray get-trace-summaries` 命令获取跟踪摘要列表。以下命令使用默认的 TraceID 时间获取过去 1 到 2 分钟内的跟踪摘要列表。
**Example 用于获取跟踪摘要的脚本**
```
EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))
```
**Example GetTraceSummaries 输出**
```
{
"TraceSummaries": [
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/session",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [],
"HasFault": false,
"Annotations": {},
"ResponseTime": 0.084,
"Duration": 0.084,
"Id": "1-59602606-a43a1ac52fc7ee0eea12a82c",
"HasThrottle": false
},
{
"HasError": false,
"Http": {
"HttpStatus": 200,
"ClientIp": "205.255.255.183",
"HttpURL": "http://scorekeep.elasticbeanstalk.com/api/user",
"UserAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36",
"HttpMethod": "POST"
},
"Users": [
{
"UserName": "5M388M1E"
}
],
"HasFault": false,
"Annotations": {
"UserID": [
{
"AnnotationValue": {
"StringValue": "5M388M1E"
}
}
],
"Name": [
{
"AnnotationValue": {
"StringValue": "Ola"
}
}
]
},
"ResponseTime": 3.232,
"Duration": 3.232,
"Id": "1-59602603-23fc5b688855d396af79b496",
"HasThrottle": false
}
],
"ApproximateTime": 1499473304.0,
"TracesProcessedCount": 2
}
```
使用来自输出的跟踪 ID 通过 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API 来检索完整跟踪。
**Example BatchGetTraces 命令**
```
$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b
```
**Example BatchGetTraces 输出**
```
{
"Traces": [
{
"Duration": 3.232,
"Segments": [
{
"Document": "{\"id\":\"1fb07842d944e714\",\"name\":\"random-name\",\"start_time\":1.499473411677E9,\"end_time\":1.499473414572E9,\"parent_id\":\"0c544c1b1bbff948\",\"http\":{\"response\":{\"status\":200}},\"aws\":{\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda\",\"resource_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}",
"Id": "1fb07842d944e714"
},
{
"Document": "{\"id\":\"194fcc8747581230\",\"name\":\"Scorekeep\",\"start_time\":1.499473411562E9,\"end_time\":1.499473414794E9,\"http\":{\"request\":{\"url\":\"http://scorekeep.elasticbeanstalk.com/api/user\",\"method\":\"POST\",\"user_agent\":\"Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/59.0.3071.115 Safari/537.36\",\"client_ip\":\"205.251.233.183\"},\"response\":{\"status\":200}},\"aws\":{\"elastic_beanstalk\":{\"version_label\":\"app-abb9-170708_002045\",\"deployment_id\":406,\"environment_name\":\"scorekeep-dev\"},\"ec2\":{\"availability_zone\":\"us-west-2c\",\"instance_id\":\"i-0cd9e448944061b4a\"},\"xray\":{\"sdk_version\":\"1.1.2\",\"sdk\":\"X-Ray for Java\"}},\"service\":{},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"user\":\"5M388M1E\",\"origin\":\"AWS::ElasticBeanstalk::Environment\",\"subsegments\":[{\"id\":\"0c544c1b1bbff948\",\"name\":\"Lambda\",\"start_time\":1.499473411629E9,\"end_time\":1.499473414572E9,\"http\":{\"response\":{\"status\":200,\"content_length\":14}},\"aws\":{\"log_type\":\"None\",\"status_code\":200,\"function_name\":\"random-name\",\"invocation_type\":\"RequestResponse\",\"operation\":\"Invoke\",\"request_id\":\"ac086670-6373-11e7-a174-f31b3397f190\",\"resource_names\":[\"random-name\"]},\"namespace\":\"aws\"},{\"id\":\"071684f2e555e571\",\"name\":\"## UserModel.saveUser\",\"start_time\":1.499473414581E9,\"end_time\":1.499473414769E9,\"metadata\":{\"debug\":{\"test\":\"Metadata string from UserModel.saveUser\"}},\"subsegments\":[{\"id\":\"4cd3f10b76c624b4\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"namespace\":\"aws\"}]}]}",
"Id": "194fcc8747581230"
},
{
"Document": "{\"id\":\"00f91aa01f4984fd\",\"name\":\"random-name\",\"start_time\":1.49947341283E9,\"end_time\":1.49947341457E9,\"parent_id\":\"1fb07842d944e714\",\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\",\"resource_names\":[\"random-name\"],\"account_id\":\"123456789012\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::Lambda::Function\",\"subsegments\":[{\"id\":\"e6d2fe619f827804\",\"name\":\"annotations\",\"start_time\":1.499473413012E9,\"end_time\":1.499473413069E9,\"annotations\":{\"UserID\":\"5M388M1E\",\"Name\":\"Ola\"}},{\"id\":\"b29b548af4d54a0f\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"namespace\":\"aws\"},{\"id\":\"2279c0030c955e52\",\"name\":\"Initialization\",\"start_time\":1.499473412064E9,\"end_time\":1.499473412819E9,\"aws\":{\"function_arn\":\"arn:aws:lambda:us-west-2:123456789012:function:random-name\"}}]}",
"Id": "00f91aa01f4984fd"
},
{
"Document": "{\"id\":\"17ba309b32c7fbaf\",\"name\":\"DynamoDB\",\"start_time\":1.49947341469E9,\"end_time\":1.499473414769E9,\"parent_id\":\"4cd3f10b76c624b4\",\"inferred\":true,\"http\":{\"response\":{\"status\":200,\"content_length\":57}},\"aws\":{\"table_name\":\"scorekeep-user\",\"operation\":\"UpdateItem\",\"request_id\":\"MFQ8CGJ3JTDDVVVASUAAJGQ6NJ82F738BOB4KQNSO5AEMVJF66Q9\",\"resource_names\":[\"scorekeep-user\"]},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::DynamoDB::Table\"}",
"Id": "17ba309b32c7fbaf"
},
{
"Document": "{\"id\":\"1ee3c4a523f89ca5\",\"name\":\"SNS\",\"start_time\":1.499473413112E9,\"end_time\":1.499473414071E9,\"parent_id\":\"b29b548af4d54a0f\",\"inferred\":true,\"http\":{\"response\":{\"status\":200}},\"aws\":{\"operation\":\"Publish\",\"region\":\"us-west-2\",\"request_id\":\"a2137970-f6fc-5029-83e8-28aadeb99198\",\"retries\":0,\"topic_arn\":\"arn:aws:sns:us-west-2:123456789012:awseb-e-ruag3jyweb-stack-NotificationTopic-6B829NT9V5O9\"},\"trace_id\":\"1-59602603-23fc5b688855d396af79b496\",\"origin\":\"AWS::SNS\"}",
"Id": "1ee3c4a523f89ca5"
}
],
"Id": "1-59602603-23fc5b688855d396af79b496"
}
],
"UnprocessedTraceIds": []
}
```
完整跟踪为每个分段包括一个文档，该文档根据收到的具有相同跟踪 ID 的所有分段文档编译。这些文档并不等同于您的应用程序发送到 X-Ray 的原样数据。它们是 X-Ray 服务生成的、经过处理的文档。X-Ray 编译您的应用程序发送的分段文档，并删除不符合[分段文档架构](xray-api-segmentdocuments.md)的数据，从而创建完整的跟踪文档。
X-Ray 还会为自身不发送分段的服务的下游调用创建*推断分段*。例如，当您通过检测过的客户端调用 DynamoDB 时，X-Ray SDK 会从其视角记录包含调用详细信息的子分段。但是，DynamoDB 不发送相应的分段。X-Ray 会使用子分段中的信息创建推断分段，以表示跟踪地图中的 DynamoDB 资源，并将其添加到跟踪文档中。
要从 API 获得多个跟踪，您需要跟踪 ID 的列表，您可以使用 [AWS CLI 查询](https://docs.aws.amazon.com/cli/latest/userguide/controlling-output.html#controlling-output-filter)从 `get-trace-summaries` 输出中提取这些 ID。将该列表重定向到 `batch-get-traces` 的输入可获取特定时间段的完整跟踪。
**Example 用于获取一分钟时间段内完整跟踪的脚本**
```
EPOCH=$(date +%s)
TRACEIDS=$(aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60)) --query 'TraceSummaries[*].Id' --output text)
aws xray batch-get-traces --trace-ids $TRACEIDS --query 'Traces[*]'
```
## 检索和细化根本原因分析
在使用 [GetTraceSummaries API](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) 生成跟踪摘要后，可以采用 JSON 格式重用部分跟踪摘要，以创建基于根本原因的细化筛选表达式。请参阅下面的示例了解细化步骤的演练。
**Example 示例 GetTraceSummaries 输出 - 响应时间根本原因部分**
```
{
"Services": [
{
"Name": "GetWeatherData",
"Names": ["GetWeatherData"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetWeatherData",
"Coverage": 1.0,
'Remote": false
},
{
"Name": "get_temperature",
"Coverage": 0.8,
"Remote": false
}
]
},
{
"Name": "GetTemperature",
"Names": ["GetTemperature"],
"AccountId": 123456789012,
"Type": null,
"Inferred": false,
"EntityPath": [
{
"Name": "GetTemperature",
"Coverage": 0.7,
"Remote": false
}
]
}
]
}
```
通过编辑并忽略上述输出，此 JSON 可以成为匹配的根本原因实体的筛选条件。JSON 中显示的任何一个候选字段都必须准确，否则将不会返回跟踪。删除的字段将成为通配符值，且采用可与筛选表达式查询结构兼容的格式。
**Example 重新格式化的响应时间根本原因**
```
{
"Services": [
{
"Name": "GetWeatherData",
"EntityPath": [
{
"Name": "GetWeatherData"
},
{
"Name": "get_temperature"
}
]
},
{
"Name": "GetTemperature",
"EntityPath": [
{
"Name": "GetTemperature"
}
]
}
]
}
```
随后通过调用 `rootcause.json = #[{}]` 将此 JSON 用作筛选表达式的一部分。有关使用筛选表达式进行查询的更多详细信息，请参阅[筛选表达式](xray-console-filters.md)一章。
**Example JSON 筛选条件示例**
```
rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]
```
# 使用 AWS X-Ray API 配置采样、分组和加密设置
AWS X-Ray APIs 用于配置[采样规则](xray-console-sampling.md)、组规则和[加密设置](xray-console-encryption.md)。
**Topics**
+ [加密设置](#xray-api-configuration-encryption)
+ [采样规则](#xray-api-configuration-sampling)
+ [组](#xray-api-configuration-groups)
## 加密设置
[https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_PutEncryptionConfig.html)用于指定用于加密的 AWS Key Management Service (AWS KMS) 密钥。
**注意**
X-Ray 不支持非对称 KMS 密钥。
```
$ aws xray put-encryption-config --type KMS --key-id alias/aws/xray
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "UPDATING",
"Type": "KMS"
}
}
```
对于密钥 ID，您可以使用别名（如示例中所示）、密钥 ID 或 Amazon 资源名称 (ARN)。
使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html](https://docs.aws.amazon.com/xray/latest/api/API_GetEncryptionConfig.html) 获取当前配置。X-Ray 应用设置后，状态将从 `UPDATING` 变为 `ACTIVE`。
```
$ aws xray get-encryption-config
{
"EncryptionConfig": {
"KeyId": "arn:aws:kms:us-east-2:123456789012:key/c234g4e8-39e9-4gb0-84e2-b0ea215cbba5",
"Status": "ACTIVE",
"Type": "KMS"
}
}
```
要停止使用 KMS 密钥并使用默认加密，请将加密类型设置为 `NONE`。
```
$ aws xray put-encryption-config --type NONE
{
"EncryptionConfig": {
"Status": "UPDATING",
"Type": "NONE"
}
}
```
## 采样规则
您可以使用 X-Ray API 管理账户中的[采样规则](xray-console-sampling.md)。有关添加和管理标签的更多信息，请参阅[标记 X-Ray 采样规则和组](xray-tagging.md)。
利用 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 获取所有采样规则。
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.05,
"ReservoirSize": 1,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
}
]
}
```
默认规则应用于所有与任何其他规则都不匹配的请求。这是优先级最低的规则，无法删除。但是，您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) 更改速率和容器大小。
**Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) 的 API 输入 10000-default.json**
```
{
"SamplingRuleUpdate": {
"RuleName": "Default",
"FixedRate": 0.01,
"ReservoirSize": 0
}
}
```
以下示例使用前一个文件作为输入，将默认规则更改为没有容器的百分之一。标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。要从采样规则中移除现有标签，请使用 [UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)
```
$ aws xray update-sampling-rule --cli-input-json file://1000-default.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-2:123456789012:sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1529959993.0
},
```
利用 [https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_CreateSamplingRule.html) 创建更多采样规则。创建规则时，大多数规则字段都是必填字段。以下示例将创建两个规则。第一条规则为 Scorekeeep 示例应用程序设置了基本频率。它匹配 API 提供的所有不符合更高优先级规则的请求。
**Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) 的 API 输入 9000-base-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1
}
}
```
第二条规则也应用于 Scorekeeep，但它的优先级更高，也更具体。此规则为轮询请求设置了非常低的采样率。这些是客户端每隔几秒钟发出的 GET 请求，用于检查游戏状态是否发生变化。
**Example [https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_UpdateSamplingRule.html) 的 API 输入 5000-polling-scorekeep.json**
```
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1
}
}
```
标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。
```
$ aws xray create-sampling-rule --cli-input-json file://5000-polling-scorekeep.json --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
$ aws xray create-sampling-rule --cli-input-json file://9000-base-scorekeep.json
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 5,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574410.0,
"ModifiedAt": 1530574410.0
}
}
```
要删除采样规则，请使用 [https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html](https://docs.aws.amazon.com/xray/latest/api/API_DeleteSamplingRule.html)。
```
$ aws xray delete-sampling-rule --rule-name polling-scorekeep
{
"SamplingRuleRecord": {
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1:123456789012:sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530574399.0,
"ModifiedAt": 1530574399.0
}
}
```
## 组
您可以使用 X-Ray API 管理您账户中的组。组是由筛选条件表达式定义的跟踪的集合。您可以使用群组来生成其他服务图表并提供 Amazon CloudWatch 指标。请参阅 [从 AWS X-Ray 获取数据](xray-api-gettingdata.md)，以了解有关通过 X-Ray API 使用服务图和指标的更多详细信息。有关组的更多信息，请参阅 [配置组](xray-console-groups.md)。有关添加和管理标签的更多信息，请参阅[标记 X-Ray 采样规则和组](xray-tagging.md)。
使用 `CreateGroup` 创建一个组。标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。
```
$ aws xray create-group --group-name "TestGroup" --filter-expression "service(\"example.com\") {fault}" --tags [{"Key": "key_name","Value": "value"},{"Key": "key_name","Value": "value"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
获取所有包含 `GetGroups` 的现有组。
```
$ aws xray get-groups
{
"Groups": [
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
},
{
"GroupName": "TestGroup2",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup2/UniqueID",
"FilterExpression": "responsetime > 2"
}
],
"NextToken": "tokenstring"
}
```
更新包含 `UpdateGroup` 的组。标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。要从群组中移除现有标签，请使用[UntagResource](https://docs.aws.amazon.com/xray/latest/api/API_UntagResource.html)。
```
$ aws xray update-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID" --filter-expression "service(\"example.com\") {fault OR error}" --tags [{"Key": "Stage","Value": "Prod"},{"Key": "Department","Value": "QA"}]
{
"GroupName": "TestGroup",
"GroupARN": "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID",
"FilterExpression": "service(\"example.com\") {fault OR error}"
}
```
删除包含 `DeleteGroup` 的组。
```
$ aws xray delete-group --group-name "TestGroup" --group-arn "arn:aws:xray:us-east-2:123456789012:group/TestGroup/UniqueID"
{
}
```
# 通过 X-Ray API 使用采样规则
X-Ray 开发工具包使用 AWS X-Ray API 获取采样规则、报告采样结果并获取配额。您可以使用这些 API 来更好地了解采样规则的工作方式或采用 X-Ray 开发工具包不支持的语言进行采样。
首先利用 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 获取所有采样规则。
```
$ aws xray get-sampling-rules
{
"SamplingRuleRecords": [
{
"SamplingRule": {
"RuleName": "Default",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default",
"ResourceARN": "*",
"Priority": 10000,
"FixedRate": 0.01,
"ReservoirSize": 0,
"ServiceName": "*",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 0.0,
"ModifiedAt": 1530558121.0
},
{
"SamplingRule": {
"RuleName": "base-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep",
"ResourceARN": "*",
"Priority": 9000,
"FixedRate": 0.1,
"ReservoirSize": 2,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "*",
"URLPath": "*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530573954.0,
"ModifiedAt": 1530920505.0
},
{
"SamplingRule": {
"RuleName": "polling-scorekeep",
"RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep",
"ResourceARN": "*",
"Priority": 5000,
"FixedRate": 0.003,
"ReservoirSize": 0,
"ServiceName": "Scorekeep",
"ServiceType": "*",
"Host": "*",
"HTTPMethod": "GET",
"URLPath": "/api/state/*",
"Version": 1,
"Attributes": {}
},
"CreatedAt": 1530918163.0,
"ModifiedAt": 1530918163.0
}
]
}
```
输出包括默认规则和自定义规则。如果还尚未创建采样规则，请参阅 [采样规则](xray-api-configuration.md#xray-api-configuration-sampling)。
根据传入请求按优先级升序评估规则。当规则匹配时，使用固定速率和容器大小来制定采样决定。记录采样请求并忽略出于跟踪目的的未采样请求。制定采样决定时停止评估规则。
规则容器大小由指在应用固定速率之前，每秒要记录的跟踪目标数量。容器累积应用于所有服务，因此无法直接使用。但是，如果它是非零值，您可以每秒从容器借用一个跟踪，直到 X-Ray 分配配额。在收到配额之前，请每秒记录第一个请求，然后将固定速率应用于其他请求。固定速率是介于 0 和 1.00 之间的小数 (100%)。
以下示例显示了对 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) 的调用以及有关在过去 10 秒内所做的采样决定的详细信息。
```
$ aws xray get-sampling-targets --sampling-statistics-documents '[
{
"RuleName": "base-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 110,
"SampledCount": 20,
"BorrowCount": 10
},
{
"RuleName": "polling-scorekeep",
"ClientID": "ABCDEF1234567890ABCDEF10",
"Timestamp": "2018-07-07T00:20:06",
"RequestCount": 10500,
"SampledCount": 31,
"BorrowCount": 0
}
]'
{
"SamplingTargetDocuments": [
{
"RuleName": "base-scorekeep",
"FixedRate": 0.1,
"ReservoirQuota": 2,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
},
{
"RuleName": "polling-scorekeep",
"FixedRate": 0.003,
"ReservoirQuota": 0,
"ReservoirQuotaTTL": 1530923107.0,
"Interval": 10
}
],
"LastRuleModification": 1530920505.0,
"UnprocessedStatistics": []
}
```
来自 X-Ray 的响应包含要使用的配额（而不是从容器借用）。在此示例中，该服务在 10 秒钟内从容器借用了 10 条跟踪，并对其他 100 个请求应用了 10% 的固定速率，结果共有 20 个采样请求。配额有效期为五分钟（按生存时间表示），或者直到分配新的配额为止。X-Ray 也可能指定比默认报告间隔更长的间隔，尽管这里没有这样做。
**注意**
来自 X-Ray 的响应可能不包含您首次调用它时的配额。继续从容器借用，直到为您分配配额。
响应中的其他两个字段可能表示输入有问题。请针对上一次 `LastRuleModification` 调用检查 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html)。如果较新，则获取相应规则的新副本。`UnprocessedStatistics` 可以包括指示规则已删除、输入中的统计文档太旧或权限错误的错误。
# AWS X-Ray 分段文档
**跟踪分段**是应用程序提供服务的请求的 JSON 表示形式。跟踪分段将记录有关原始请求的信息、有关应用程序本地执行的工作的信息以及**子分段**，而子分段包含有关应用程序向 AWS 资源、HTTP API 和 SQL 数据库发出的下游调用的信息。
**分段文档**将有关分段的信息传递给 X-Ray。分段文档最多可为 64KB，并且包含一个带子分段的完整分段、指示请求正在进行中的分段部分或一个单独发送的子分段。您可以使用 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) API 将分段文档直接发送到 X-Ray。
X-Ray 将编译和处理分段文档以生成可查询的**跟踪摘要**和**完整跟踪**，您可以分别使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html](https://docs.aws.amazon.com/xray/latest/api/API_GetTraceSummaries.html) 和 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API 访问二者。除了您发送到 X-Ray 的分段和子分段之外，服务还使用子分段中的信息生成**推断分段**并将其添加到完整跟踪。推断分段表示跟踪地图中的下游服务和资源。
X-Ray 提供分段文档的 **JSON 架构**。您可以在此处下载该架构：[xray-segmentdocument-schema-v1.0.0](samples/xray-segmentdocument-schema-v1.0.0.zip)。以下部分中更详细地描述了该架构中列出的字段和对象。
X-Ray 为分段字段的子集编制索引以用于筛选表达式。例如，如果您将分段上的 `user` 字段设置为唯一标识符，则可在 X-Ray 控制台中或使用 `GetTraceSummaries` API 搜索与特定用户关联的分段。有关更多信息，请参阅 [使用筛选条件表达式](xray-console-filters.md)。
在使用 X-Ray SDK 检测应用程序时，此 SDK 将为您生成分段文档。此 SDK 通过本地 UDP 端口将分段文档传输到 [X-Ray 进程守护程序](xray-daemon.md)，而不是直接将分段文档发送到 X-Ray。有关更多信息，请参阅 [将分段文档发送到 X-Ray 进程守护程序](xray-api-sendingdata.md#xray-api-daemon)。
**Topics**
+ [分段字段](#api-segmentdocuments-fields)
+ [子分段](#api-segmentdocuments-subsegments)
+ [HTTP 请求数据](#api-segmentdocuments-http)
+ [注释](#api-segmentdocuments-annotations)
+ [元数据](#api-segmentdocuments-metadata)
+ [AWS 资源数据](#api-segmentdocuments-aws)
+ [错误和异常](#api-segmentdocuments-errors)
+ [SQL 查询](#api-segmentdocuments-sql)
## 分段字段
分段记录有关应用程序提供服务的请求的跟踪信息。分段至少会记录请求的名称、ID、开始时间、跟踪 ID 和结束时间。
**Example 最小完成分段**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0a",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"end_time" : 1.478293361449E9
}
```
分段需要或有条件地需要以下字段。
**注意**
除非另行说明，否则值必须是字符串（最多 250 个字符）。
**必填分段字段**
+ `name` - 处理了请求的服务的逻辑名称（最多 **200 个字符**）。例如，您的应用程序的名称或域名。名称可以包含 Unicode 字母、数字、空格和以下符号：`_`、`.`、`:`、`/`、`%`、`&`、`#`、`=`、`+`、`\`、`-`、`@`
+ `id` - 分段的 64 位标识符，在同一个跟踪中的分段之间唯一，使用 **16 位十六进制数**。
+ `trace_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 跟踪上下文规范](https://www.w3.org/TR/trace-context/)的框架创建的跟踪 ID。发送到 X-Ray 时，W3C 跟踪 ID 必须采用 X-Ray 跟踪 ID 的格式。例如，W3C 跟踪 ID `4efaaf4d1e8720b39541901950019ee5` 在发送到 X-Ray 时，应与 `1-4efaaf4d-1e8720b39541901950019ee5` 的格式相同。虽然 X-Ray 跟踪 ID 包含以 Unix 纪元时间为单位的原始请求时间戳，但在以 X-Ray 格式发送 W3C 跟踪 ID 时，这不是必需的。
**跟踪 ID 安全性**
跟踪 ID 显示在[响应标头](xray-concepts.md#xray-concepts-tracingheader)中。使用安全的随机算法生成跟踪 ID，确保攻击者无法计算未来的跟踪 ID 并使用这些 ID 向您的应用程序发送请求。
+ `start_time` - 表示分段的创建时间的**数字**，采用浮点秒数的纪元时间。例如，`1480615200.010` 或 `1.480615200010E9`。使用所需数量的小数位。建议使用微秒解析（如果可用）。
+ `end_time` - 表示分段的关闭时间的**数字**。例如，`1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` - ** **布尔值`true`，设置为 ，而不是指定 `end_time` 以记录分段已经启动但未完成。在您的应用程序接收到需要长时间提供服务的请求时发送进行中的分段，用于跟踪请求接收。发送了响应之后，发送完成分段以覆盖进行中分段。仅为每个请求发送一个完整分段，以及一个或零个进行中分段。
**服务名称**
分段的 `name` 应该与生成该分段的服务的域名或逻辑名称相匹配。但是，并未强制执行此规则。任何拥有 [https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html](https://docs.aws.amazon.com/xray/latest/api/API_PutTraceSegments.html) 权限的应用程序均可发送任何名称的分段。
以下字段是分段的可选字段。
**可选分段字段**
+ `service` - 一个包含应用程序的相关信息的对象。
+ `version` - 一个标识为请求提供服务的应用程序版本的字符串。
+ `user` - 一个标识发送请求的用户的字符串。
+ `origin` - 运行您的应用程序的 AWS 资源类型。
**支持的值**
+ `AWS::EC2::Instance` - 一个 Amazon EC2 实例。
+ `AWS::ECS::Container` — 一个 Amazon ECS 容器。
+ `AWS::ElasticBeanstalk::Environment` - 一个 Elastic Beanstalk 环境。
如果您的应用程序适用多个值，请使用最具体的值。例如，一个多容器 Docker Elastic Beanstalk 环境在一个 Amazon ECS 容器上运行您的应用程序，该容器反过来又在 Amazon ECS 实例上运行。在这种情况下，您应将源设为 `AWS::ElasticBeanstalk::Environment`，因为环境是另外两种资源的父级。
+ `parent_id` - 您在请求源自检测过的应用程序时指定的子分段 ID。X-Ray SDK 将父级子分段 ID 添加到下游 HTTP 调用的[跟踪标头](xray-concepts.md#xray-concepts-tracingheader)。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。
+ `http` - [`http`](#api-segmentdocuments-http) 对象，包含原始 HTTP 请求的相关信息。
+ `aws` - [`aws`](#api-segmentdocuments-aws) 对象包含有关应用程序为请求提供服务的 AWS 资源的信息。
+ `error`、`throttle`、`fault` 和 `cause` - [错误](#api-segmentdocuments-errors)字段，指示出现错误并且包含有关导致错误的异常的信息。
+ `annotations`：[`annotations`](#api-segmentdocuments-annotations) 对象，包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。
+ `metadata`：[`metadata`](#api-segmentdocuments-metadata) 对象，包含要存储在分段中的任何附加数据。
+ `subsegments` - [`subsegment`](#api-segmentdocuments-subsegments) 对象**数组**。
## 子分段
您可以创建子分段来记录您使用 AWS SDK 对 AWS 服务和资源发起的调用、对内部或外部 HTTP Web API 的调用或 SQL 数据库查询。您也可以创建子分段来调试应用程序中的代码块或为其添加注释。由于子分段可以包含其他子分段，因此，记录有关内部函数调用的元数据的自定义子分段可以包含其他自定义子分段和下游调用的子分段。
子分段从调用它的服务的角度，记录下游调用。X-Ray 使用子分段来确定未发送分段的下游服务，并在服务图上为其创建条目。
子分段可以嵌入到完整分段文档或者单独发送。对于长时间运行的请求，单独发送子分段以异步跟踪下游调用，或者避免超过最大分段文档大小。
**Example 带有嵌入式子分段的分段**
独立子分段具有 `type` 的 `subsegment` 以及标识父分段的 `parent_id`。
```
{
"trace_id" : "1-5759e988-bd862e3fe1be46a994272793",
"id" : "defdfd9912dc5a56",
"start_time" : 1461096053.37518,
"end_time" : 1461096053.4042,
"name" : "www.example.com",
"http" : {
"request" : {
"url" : "https://www.example.com/health",
"method" : "GET",
"user_agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/601.7.7",
"client_ip" : "11.0.3.111"
},
"response" : {
"status" : 200,
"content_length" : 86
}
},
"subsegments" : [
{
"id" : "53995c3f42cd8ad8",
"name" : "api.example.com",
"start_time" : 1461096053.37769,
"end_time" : 1461096053.40379,
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
]
}
```
对于长时间运行的请求，您可以发送进行中分段来告知 X-Ray 已收到请求，然后在完成原始请求之前单独发送子分段来跟踪这些请求。
**Example 正在进行分段**
```
{
"name" : "example.com",
"id" : "70de5b6f19ff9a0b",
"start_time" : 1.478293361271E9,
"trace_id" : "1-581cf771-a006649127e371903a2de979",
"in_progress": true
}
```
**Example 独立子分段**
独立子分段具有 `type` 的 `subsegment`，一个 `trace_id` 和一个标识父分段的 `parent_id`。
```
{
"name" : "api.example.com",
"id" : "53995c3f42cd8ad8",
"start_time" : 1.478293361271E9,
"end_time" : 1.478293361449E9,
"type" : "subsegment",
"trace_id" : "1-581cf771-a006649127e371903a2de979"
"parent_id" : "defdfd9912dc5a56",
"namespace" : "remote",
"http" : {
"request" : {
"url" : "https://api.example.com/health",
"method" : "POST",
"traced" : true
},
"response" : {
"status" : 200,
"content_length" : 861
}
}
}
```
在请求完成时，请使用 `end_time` 重新发送分段来关闭分段。完成分段将覆盖进行中分段。
您也可以为触发了异步工作流的已完成请求单独发送子分段。例如，在开始用户请求的工作之前，Web API 可能立即返回 `OK 200` 响应。您可以在发送响应后立即将完整分段发送到 X-Ray，然后为稍后完成的工作发送子分段。与分段一样，您还可以发送子分段片段来记录子分段已开始，然后在下游调用完成后用一个完整子分段覆盖此子分段。
子分段需要或有条件地需要以下字段。
**注意**
除非另行说明，否则值是字符串（最多 250 个字符）。
**必填子分段字段**
+ `id` - 子分段的 64 位标识符，在同一个跟踪中的分段之间唯一，使用 **16 位十六进制数**。
+ `name` - 子分段的逻辑名称。对于下游调用，命名调用的资源或服务后的子分段。对于自定义子分段，命名其检测的代码后的子分段（例如，函数名称）。
+ `start_time` - 表示创建子分段的时间的**数字**，采用浮点秒数的纪元时间，精确到毫秒。例如，`1480615200.010` 或 `1.480615200010E9`。
+ `end_time` - 表示子分段的关闭时间的**数字**。例如，`1480615200.090` 或 `1.480615200090E9`。指定 `end_time` 或 `in_progress`。
+ `in_progress` - 设置为 `true` 的**布尔值**，而不是指定 `end_time` 以记录子分段已经启动但未完成。仅为每个下游请求发送一个完整子分段，以及一个或零个进行中子分段。
+ `trace_id` - 子分段的父分段的跟踪 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 跟踪上下文规范](https://www.w3.org/TR/trace-context/)的框架创建的跟踪 ID。发送到 X-Ray 时，W3C 跟踪 ID 必须采用 X-Ray 跟踪 ID 的格式。例如，W3C 跟踪 ID `4efaaf4d1e8720b39541901950019ee5` 在发送到 X-Ray 时，应与 `1-4efaaf4d-1e8720b39541901950019ee5` 的格式相同。虽然 X-Ray 跟踪 ID 包含以 Unix 纪元时间为单位的原始请求时间戳，但在以 X-Ray 格式发送 W3C 跟踪 ID 时，这不是必需的。
+ `parent_id` - 子分段的父分段的分段 ID。仅在单独发送子分段时是必需的。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。
+ `type` - `subsegment`。仅在单独发送子分段时是必需的。
以下字段是子分段的可选字段。
**可选子分段字段**
+ `namespace` - 对于 AWS SDK 调用，为 `aws`；对于其他下游调用，为 `remote`。
+ `http` - [`http`](#api-segmentdocuments-http) 对象，包含有关传出 HTTP 调用的信息。
+ `aws` - [`aws`](#api-segmentdocuments-aws) 对象，包含有关应用程序调用的下游 AWS 资源的信息。
+ `error`、`throttle`、`fault` 和 `cause` - [错误](#api-segmentdocuments-errors)字段，指示出现错误并且包含有关导致错误的异常的信息。
+ `annotations` - [`annotations`](#api-segmentdocuments-annotations) 对象，包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。
+ `metadata` - [`metadata`](#api-segmentdocuments-metadata) 对象，包含要存储在分段中的任何附加数据。
+ `subsegments` - [`subsegment`](#api-segmentdocuments-subsegments) 对象**数组**。
+ `precursor_ids` - 子分段 ID 的**数组**，标识在此子分段之前完成的具有相同父级的子分段。
## HTTP 请求数据
使用 HTTP 数据块记录有关应用程序提供服务的 HTTP 请求（在分段中）或应用程序向下游 HTTP API 发出的 HTTP 请求（在子分段中）的详细信息。此对象中的大多数字段将映射到在 HTTP 请求和响应中找到的信息。
**`http`**
所有字段都是可选字段。
+ `request` - 有关请求的信息。
+ `method` - 请求方法。例如 `GET`。
+ `url` - 从请求的协议、主机名和路径编译的完整请求 URL。
+ `user_agent` - 来自请求者客户端的用户代理字符串。
+ `client_ip` - 请求者的 IP 地址。可从 IP 数据包的 `Source Address` 或（对于转发的请求）`X-Forwarded-For` 标头中检索。
+ `x_forwarded_for` - （仅分段）**布尔值**，指示已从 `X-Forwarded-For` 标头读取 `client_ip`，并且它不可靠，因为它可能是伪造的。
+ `traced` - （仅子分段）**布尔值**，指示下游调用针对的是另一个跟踪的服务。如果此字段设置为 `true`，则 X-Ray 会将跟踪视为已中断，直至下游服务上传一个分段，此分段的 `parent_id` 与包含此数据块的子分段的 `id` 匹配。
+ `response` - 有关响应的信息。
+ `status` - 指示响应的 HTTP 状态的**整数**。
+ `content_length` - 指示响应正文长度（以字节为单位）的**整数**。
在检测对下游 Web API 进行的调用时，记录包含有关 HTTP 请求和响应的信息的子分段。X-Ray 使用子分段为远程 API 生成推断分段。
**Example 由 Amazon EC2 上运行的应用程序提供服务的 HTTP 调用的分段**
```
{
"id": "6b55dcc497934f1a",
"start_time": 1484789387.126,
"end_time": 1484789387.535,
"trace_id": "1-5880168b-fd5158284b67678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
**Example 下游 HTTP 调用的子分段**
```
{
"id": "004f72be19cddc2a",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"name": "names.example.com",
"namespace": "remote",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
}
}
```
**Example 下游 HTTP 调用的推断分段**
```
{
"id": "168416dc2ea97781",
"name": "names.example.com",
"trace_id": "1-62be1272-1b71c4274f39f122afa64eab",
"start_time": 1484786387.131,
"end_time": 1484786387.501,
"parent_id": "004f72be19cddc2a",
"http": {
"request": {
"method": "GET",
"url": "https://names.example.com/"
},
"response": {
"content_length": -1,
"status": 200
}
},
"inferred": true
}
```
## 注释
分段和子分段可包含一个 `annotations` 对象，此对象包含一个或多个字段，X-Ray 将为这些字段编制索引以便用于筛选表达式。字段可以包含字符串、数字或布尔值（无对象或数组）。X-Ray 最多为每个跟踪的 50 条注释编制索引。
**Example 包含注释的 HTTP 调用的分段**
```
{
"id": "6b55dcc497932f1a",
"start_time": 1484789187.126,
"end_time": 1484789187.535,
"trace_id": "1-5880168b-fd515828bs07678a3bb5a78c",
"name": "www.example.com",
"origin": "AWS::EC2::Instance",
"aws": {
"ec2": {
"availability_zone": "us-west-2c",
"instance_id": "i-0b5a4678fc325bg98"
},
"xray": {
"sdk_version": "2.11.0 for Java"
},
},
"annotations": {
"customer_category" : 124,
"zip_code" : 98101,
"country" : "United States",
"internal" : false
},
"http": {
"request": {
"method": "POST",
"client_ip": "78.255.233.48",
"url": "http://www.example.com/api/user",
"user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0",
"x_forwarded_for": true
},
"response": {
"status": 200
}
}
```
键必须为字母数字才能用于筛选器。允许使用下划线。不允许使用其他符号和空格。
## 元数据
分段和子分段可包含一个 `metadata` 对象，此对象包含一个或多个字段，这些字段具有任何类型的值（包括对象和数组）。X-Ray 不会为元数据编制索引，并且值可以是任何大小，前提是分段文档不会超出最大大小 (64KB)。您可以查看由 [https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html](https://docs.aws.amazon.com/xray/latest/api/API_BatchGetTraces.html) API 返回的完整分段文档中的元数据。将保留以 `debug` 开头的字段键（以下示例中为 `AWS.`）以供 AWS 提供的 SDK 和客户端使用。
**Example 包含元数据的自定义子分段**
```
{
"id": "0e58d2918e9038e8",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "## UserModel.saveUser",
"metadata": {
"debug": {
"test": "Metadata string from UserModel.saveUser"
}
},
"subsegments": [
{
"id": "0f910026178b71eb",
"start_time": 1484789387.502,
"end_time": 1484789387.534,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 58,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "3AIENM5J4ELQ3SPODHKBIRVIC3VV4KQNSO5AEMVJF66Q9ASUAAJG",
"resource_names": [
"scorekeep-user"
]
}
}
]
}
```
## AWS 资源数据
对于分段，`aws` 对象包含有关应用程序运行于的资源的信息。多个字段可应用于一个资源。例如，运行于 Elastic Beanstalk 上的多容器 Docker 环境中的应用程序包含有关 Amazon EC2 实例、该实例上运行的 Amazon EC2 容器和 Elastic Beanstalk 环境本身的信息。
**`aws` (分段)**
所有字段都是可选字段。
+ `account_id` - 如果您的应用程序将分段发送到其他 AWS 账户，则记录运行应用程序的账户的 ID。
+ `cloudwatch_logs`— 描述单个 CloudWatch 日志组的对象数组。
+ `log_group` - CloudWatch 日志组名称。
+ `arn` - CloudWatch 日志组 ARN。
+ `ec2` - 有关 Amazon EC2 实例的信息。
+ `instance_id` - EC2 实例的实例 ID。
+ `instance_size` - EC2 实例的类型。
+ `ami_id`— Amazon 系统映像 ID。
+ `availability_zone` - 实例在其中运行的可用区。
+ `ecs` - 有关 Amazon ECS 实例的信息。
+ `container`— 您的容器的主机名。
+ `container_id`— 您的容器的完整容器 ID。
+ `container_arn` - 容器实例的 ARN。
+ `eks` - 有关 Amazon EKS 集群的信息。
+ `pod`— EKS 容器组的主机名。
+ `cluster_name` - EKS 集群名称。
+ `container_id`— 您的容器的完整容器 ID。
+ `elastic_beanstalk`— 有关 Elastic Beanstalk 环境的信息。您可以在最新 Elastic Beanstalk 平台上名为 `/var/elasticbeanstalk/xray/environment.conf` 的文件中找到该信息。
+ `environment_name` – 环境名称。
+ `version_label` - 当前部署到为请求提供服务的实例的应用程序版本的名称。
+ `deployment_id` - **数字**，指示针对为请求提供服务的实例的上次成功部署的 ID。
+ `xray` – 有关所使用检测的类型和版本的元数据。
+ `auto_instrumentation` – 布尔值，指示是否使用了自动检测（例如，Java 代理）。
+ `sdk_version` - 正在使用的 SDK 或代理的版本。
+ `sdk` - SDK 类型。
**Example 带有插件的 AWS 块**
```
"aws":{
"elastic_beanstalk":{
"version_label":"app-5a56-170119_190650-stage-170119_190650",
"deployment_id":32,
"environment_name":"scorekeep"
},
"ec2":{
"availability_zone":"us-west-2c",
"instance_id":"i-075ad396f12bc325a",
"ami_id":
},
"cloudwatch_logs":[
{
"log_group":"my-cw-log-group",
"arn":"arn:aws:logs:us-west-2:012345678912:log-group:my-cw-log-group"
}
],
"xray":{
"auto_instrumentation":false,
"sdk":"X-Ray for Java",
"sdk_version":"2.8.0"
}
}
```
对于子分段，记录有关应用程序访问的 AWS 服务和资源的信息。X-Ray 使用此信息来创建推断分段，这些分段表示服务地图中的下游服务。
**`aws` (子分段)**
所有字段都是可选字段。
+ `operation` - 针对 AWS 服务或资源调用的 API 操作的名称。
+ `account_id` - 如果应用程序访问其他账户中的资源，或将分段发送到其他账户，则记录拥有应用程序访问的 AWS 资源的账户的 ID。
+ `region` - 如果资源所在的区域不同于应用程序所在的区域，则记录前者。例如 `us-west-2`。
+ `request_id` - 请求的唯一标识符。
+ `queue_url` - 对于 Amazon SQS 队列上的操作，为队列的 URL。
+ `table_name` - 对于 DynamoDB 表上的操作，为表的名称。
**Example 对 DynamoDB 进行调用以保存项目的子分段**
```
{
"id": "24756640c0d0978a",
"start_time": 1.480305974194E9,
"end_time": 1.4803059742E9,
"name": "DynamoDB",
"namespace": "aws",
"http": {
"response": {
"content_length": 60,
"status": 200
}
},
"aws": {
"table_name": "scorekeep-user",
"operation": "UpdateItem",
"request_id": "UBQNSO5AEM8T4FDA4RQDEB94OVTDRVV4K4HIRGVJF66Q9ASUAAJG",
}
}
```
## 错误和异常
出错时，您可以记录有关该错误及其生成的异常的详细信息。当应用程序将错误返回给用户时，在分段中记录错误；当下游调用返回错误时，在子分段中记录错误。
**错误类型**
将以下一个或多个字段设置为 `true` 可指示已发生错误。如果出现复合错误，则多个类型适用。例如，来自下游调用的 `429 Too Many Requests` 错误可能会导致应用程序返回 `500 Internal Server Error`，在此情况下，所有三种类型将适用。
+ `error` - **布尔值**，指示出现客户端错误（响应状态代码为 4XX 客户端错误）。
+ `throttle` - **布尔值**，指示请求已受限（响应状态代码为 *429 请求过多*）。
+ `fault` - **布尔值**，指示出现服务器错误（响应状态代码为 5XX 服务器错误）。
通过在分段或子分段中包含 **cause** 对象来指示错误原因。
**`cause`**
原因可以是 **16 个字符**的异常 ID 或带以下字段的对象：
+ `working_directory` - 发生异常时的工作目录的完整路径。
+ `paths` - 发生异常时所使用的库或模块的路径的**数组**。
+ `exceptions` - **异常**对象的**数组**。
包含有关一个或多个 **exception** 对象中的错误的详细信息。
**`exception`**
所有字段都是可选字段。
+ `id` - 异常的 64 位标识符，在同一个跟踪中的分段之间唯一，使用 **16 位十六进制数**。
+ `message` - 异常消息。
+ `type` - 异常类型。
+ `remote` - **布尔值**，指示由下游服务返回的错误导致的异常。
+ `truncated` - **整数**，指示从 `stack` 中忽略的堆栈帧数。
+ `skipped` - **整数**，指示在此异常与其子异常（此异常导致的异常）之间跳过的异常数。
+ `cause` - 此异常的父级（导致此异常的异常）的异常 ID。
+ `stack` - **stackFrame** 对象的**数组**。
如果可用，则记录有关 **stackFrame** 对象中的调用堆栈的信息。
**`stackFrame`**
所有字段都是可选字段。
+ `path` - 文件的相对路径。
+ `line` - 文件中的行。
+ `label` - 函数或方法名称。
## SQL 查询
您可以为应用程序向 SQL 数据库发出的查询创建子分段。
**`sql`**
所有字段都是可选字段。
+ `connection_string` - 对于 SQL Server 连接或不使用 URL 连接字符串的其他数据库连接，记录连接字符串（不包括密码）。
+ `url` - 对于使用 URL 连接字符串的数据库连接，记录 URL（不包括密码）。
+ `sanitized_query` - 数据库查询，其任何用户提供的值已删除或由占位符替换。
+ `database_type` - 数据库引擎的名称。
+ `database_version` - 数据库引擎的版本号。
+ `driver_version` - 应用程序使用的数据库引擎驱动程序的名称和版本号。
+ `user` - 数据库用户名。
+ `preparation` - 如果查询使用了 `PreparedCall`，则为 `call`；如果查询使用了 `PreparedStatement`，则为 `statement`。
**Example 具有 SQL 查询的子分段**
```
{
"id": "3fd8634e78ca9560",
"start_time": 1484872218.696,
"end_time": 1484872218.697,
"name": "ebdb@aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com",
"namespace": "remote",
"sql" : {
"url": "jdbc:postgresql://aawijb5u25wdoy.cpamxznpdoq8.us-west-2.rds.amazonaws.com:5432/ebdb",
"preparation": "statement",
"database_type": "PostgreSQL",
"database_version": "9.5.4",
"driver_version": "PostgreSQL 9.4.1211.jre7",
"user" : "dbuser",
"sanitized_query" : "SELECT * FROM customers WHERE customer_id=?;"
}
}
```