使用 X-Ray API

如果 X-Ray SDK 不支持你的编程语言，你可以直接使用 X-Ray API 或 Amazon Command Line Interface (Amazon CLI) 来调用 X-Ray API 命令。使用以下指南来选择与 API 的交互方式：

使用 Amazon CLI 预先格式化的命令或请求中的选项来简化语法。
直接使用 X-Ray API，以最大限度地提高灵活性，并根据您向 X-Ray 提出的请求进行自定义。

如果您直接使用 X-Ray API 而不是 Amazon CLI，则必须以正确的数据格式对请求进行参数化，可能还必须配置身份验证和错误处理。

下图显示了选择如何与 X-Ray API 交互的指南：

使用 X-Ray API 将跟踪数据直接发送到 X-Ray。X-Ray API 支持 X-Ray SDK 中可用的所有功能，包括以下常见操作：

PutTraceSegments— 将分段文档上传到 X-Ray。
BatchGetTraces— 检索跟踪 ID 列表中的跟踪列表。检索到的每条跟踪都是来自单个请求的分段文档的集合。
GetTraceSummaries— 检索轨迹的 ID 和注释。您可以指定 a FilterExpression 来检索跟踪摘要的子集。
GetTraceGraph— 检索特定跟踪 ID 的服务图表。
GetServiceGraph— 检索JSON格式化文档，该文档描述了处理传入请求和调用下游请求的服务。

您还可以在应用程序代码中使用 Amazon Command Line Interface (Amazon CLI) 以编程方式与 X-Ray 进行交互。 Amazon CLI 支持 X-Ray SDK 中可用的所有功能，包括其他功能 Amazon Web Services。以下函数是前面列出的 API 操作的版本，格式更简单：

put-trace-segments— 将分段文档上传到 X-Ray。
batch-get-traces— 检索跟踪 ID 列表中的跟踪列表。检索到的每条跟踪都是来自单个请求的分段文档的集合。
get-trace-summaries— 检索轨迹的 ID 和注释。您可以指定 a FilterExpression 来检索跟踪摘要的子集。
get-trace-graph— 检索特定跟踪 ID 的服务图表。
get-service-graph— 检索JSON格式化文档，该文档描述了处理传入请求和调用下游请求的服务。

要开始使用，您必须Amazon CLI为自己的操作系统安装。 Amazon 支持LinuxmacOS和Windows操作系统。有关 X-Ray 命令列表的更多信息，请参阅 X-Ray Amazon CLI 命令参考指南。

探索 X-Ray API

X-Ray API 允许通过 Amazon SDK 或直接通过 HTTPS 访问所有 X-Ray 功能。 Amazon Command Line InterfaceX-Ray API 参考记录每个 API 操作的输入参数，以及返回的字段和数据类型。

您可以使用 Amazon SDK 开发使用 X-Ray API 的程序。X-Ray 控制台和 X-Ray 守护程序都使用 Amazon SDK 与 X-Ray 通信。每种语言的 Amazon SDK 都有对应到 X-Ray API 操作和类型的类和方法的参考文档。

Amazon SDK 参考资料

Java - Amazon SDK for Java
JavaScript – Amazon SDK for JavaScript
.NET – Amazon SDK for .NET
Ruby – Amazon SDK for Ruby
Go — 适用于 Go 的Amazon 开发工具包
PHP – Amazon SDK for PHP
Python – Amazon SDK for Python (Boto)

Amazon Command Line Interface 是一个命令行工具，它使用适用于 Python 的软件开发工具包来调用 Amazon API。当您第一次学习 Amazon API 时， Amazon CLI 提供了一种简单的方法来浏览可用参数并以 JSON 或文本形式查看服务输出。

有关aws xray子Amazon CLI 命令的详细信息，请参阅命令参考。

Amazon CLI 允许您直接访问 X-Ray 服务，并使用与 X-Ray 控制台用于检索服务图表和原始跟踪数据相同的 API。示例应用程序包括显示如何将这些 API 与 Amazon CLI 配合使用的脚本。

先决条件

本教程使用 Scorekeep 示例应用程序并包括了用于生成跟踪数据和服务地图的脚本。按照示例应用程序教程中的说明启动应用程序。

本教程使用 Amazon CLI 来演示 X-Ray API 的基本用法。适用于 Windows、Amazon L inux 和 OS-X 的 CLI 为所有人提供了对公共 API 的命令行访问权限。 Amazon Web Services

注意

您必须验证您的配置 Amazon CLI 是否与创建示例应用程序的区域相同。

其中包括测试示例应用程序的脚本，该脚本使用 cURL 发送流量到 API 和 jq 来解析输出。您可以从 jqstedolan.github.io 下载可执行文件，从 curl 下载 https://curl.haxx.se/download.html 可执行文件。大部分 Linux 和 OS X 安装包含 cURL。

生成跟踪数据

Web 应用程序在游戏进行中每几秒继续生成对 API 的流量，但仅生成一种类型的请求。在您测试 API 时，使用 test-api.sh 脚本运行端到端方案并生成更多样的跟踪数据。

使用 `test-api.sh` 脚本

打开 Elastic Beanstalk 控制台。
导航到您的环境的管理控制台。
从页面标题复制环境 URL。

打开 bin/test-api.sh 并使用您环境的 URL 替换 API 的值。


#!/bin/bash
API=scorekeep.9hbtbm23t2.us-west-2.elasticbeanstalk.com/api

运行脚本以生成对 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

Amazon CLI 为 X-Ray 提供的所有 API 操作提供命令，包括GetServiceGraph和GetTraceSummaries。有关所有支持的操作以及这些操作所使用数据类型的更多信息，请参阅 Amazon X-Ray API 参考。

例 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",
...

例 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"
]

例 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 环境

打开 Elastic Beanstalk 控制台。
导航到您的环境的管理控制台。
选择操作。
选择终止环境。
选择终止。

在 30 之后，跟踪数据自动从 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。

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

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

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

X-Ray 会处理您发送给它的跟踪数据，以生成 JSON 格式的完整跟踪、跟踪摘要和服务图。您可以使用 Amazon CLI 直接从 API 检索生成的数据。

您可以使用 GetServiceGraph API 来检索 JSON 服务图。该 API 需要开始时间和结束时间，您可以使用 date 命令从 Linux 终端计算这些时间。


$ date +%s
1499394617

date +%s 显示日期（秒数）。使用该数字作为结束时间，并从中减去一个时间可得到开始时间。

例用于检索最后 10 分钟的服务图的脚本


EPOCH=$(date +%s)
aws xray get-service-graph --start-time $(($EPOCH-600)) --end-time $EPOCH

以下示例显示了一个包含 4 个节点的服务图，其中包括一个客户端节点、一个 EC2 实例、一个 DynamoDB 表和一个 Amazon SNS 主题。

例 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”的组进行服务图调用。

例用于按组 Example1 的名称检索服务图的脚本


aws xray get-service-graph --group-name "Example1"

您可以使用 GetTraceSummaries API 获取跟踪摘要列表。跟踪摘要包括可用于完整标识要下载的跟踪的信息，包括注释、请求和响应信息以及 ID。

调用 aws xray get-trace-summaries 时可以使用两个 TimeRangeType 标志：

TraceId— 默认GetTraceSummaries搜索使用 TraceID 时间并返回在计算[start_time, end_time)范围内开始的轨迹。此时间戳范围是根据内时间戳的编码计算得出的 TraceId，也可以手动定义。
事件时间-要搜索一段时间内发生的事件， Amazon X-Ray 允许使用事件时间戳搜索跟踪。无论追踪何时开始，事件时间都会返回 [start_time, end_time) 范围内处于活动状态的跟踪。

使用 aws xray get-trace-summaries 命令获取跟踪摘要列表。以下命令使用默认 TraceId 时间获取过去 1 到 2 分钟的跟踪摘要列表。

例用于获取跟踪摘要的脚本


EPOCH=$(date +%s)
aws xray get-trace-summaries --start-time $(($EPOCH-120)) --end-time $(($EPOCH-60))

例 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 通过 BatchGetTraces API 来检索完整跟踪。

例 BatchGetTraces 命令


$ aws xray batch-get-traces --trace-ids 1-596025b4-7170afe49f7aa708b1dd4a6b

例 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 编译您的应用程序发送的分段文档，并删除不符合分段文档架构的数据，从而创建完整的跟踪文档。有关更多信息，请参阅 X-Ray 片段文档。

X-Ray 还会为自身不发送分段的服务的下游调用创建推断分段。例如，当您通过检测过的客户端调用 DynamoDB 时，X-Ray 开发工具包会从其视角记录包含调用详细信息的子分段。但是，DynamoDB 不发送相应的分段。X-Ray 使用子分段中的信息创建推断的区段，以表示追踪图中的 DynamoDB 资源，并将其添加到跟踪文档中。

要从 API 获得多个跟踪，您需要跟踪 ID 的列表，您可以使用 get-trace-summaries 查询Amazon CLI 从的输出中提取这些 ID。将该列表重定向到 batch-get-traces 的输入以获取特定时间段的完整跟踪。

例用于获取一分钟时间段内完整跟踪的脚本


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 生成跟踪摘要后，可以以 JSON 格式重复使用部分跟踪摘要，根据根本原因创建精细的筛选表达式。请参阅下面的示例了解细化步骤的演练。

例 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 中显示的任何一个候选字段都必须准确，否则将不会返回跟踪。删除的字段将成为通配符值，且采用可与筛选表达式查询结构兼容的格式。

例重新格式化的响应时间根本原因


{
  "Services": [
    {
      "Name": "GetWeatherData",
      "EntityPath": [
        {
          "Name": "GetWeatherData"
        },
        {
          "Name": "get_temperature"
        }
      ]
    },
    {
      "Name": "GetTemperature",
      "EntityPath": [
        {
          "Name": "GetTemperature"
        }
      ]
    }
  ]
}

随后通过调用 rootcause.json = #[{}] 将此 JSON 用作筛选表达式的一部分。有关使用筛选表达式进行查询的更多详细信息，请参阅探索 X-Ray 控制台中的 “使用筛选表达式” 部分。

例示例 JSON 筛选条件


rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }]

X-Ray 提供用于配置采样规则、组规则和加密设置的 API。

加密设置

PutEncryptionConfig用于指定用于加密的 Amazon Key Management Service (Amazon 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)。

使用 GetEncryptionConfig 获取当前配置。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 管理账户中的采样规则。有关采样的更多信息，请参阅配置采样规则。有关添加和管理标签的更多信息，请参阅标记 X-Ray 采样规则和组。

利用 GetSamplingRules 获取所有采样规则。


$ 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
        }
    ]
}

默认规则应用于所有与任何其他规则都不匹配的请求。这是优先级最低的规则，无法删除。但是，您可以使用 UpdateSamplingRule 更改速率和容器大小。

例 `UpdateSamplingRule` 的 API 输入 10000-default.json


{
    "SamplingRuleUpdate": {
        "RuleName": "Default",
        "FixedRate": 0.01,
        "ReservoirSize": 0
    }
}

以下示例使用前一个文件作为输入，将默认规则更改为没有容器的百分之一。标签是可选的。如果选择添加标签，则标签键是必填，标签值为选填。要从采样规则中移除现有标签，请使用UntagResource。


$ 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
        },

利用 CreateSamplingRule 创建更多采样规则。创建规则时，大多数规则字段都是必填字段。以下示例将创建两个规则。第一条规则为 Scorekeeep 示例应用程序设置了基本频率。它匹配 API 提供的所有不符合更高优先级规则的请求。

例 `UpdateSamplingRule` 的 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 请求，用于检查游戏状态是否发生变化。

例 `UpdateSamplingRule` 的 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
    }
}

要删除采样规则，请使用 DeleteSamplingRule。


$ 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 指标。请参阅从 X-Ray 获取数据，以了解有关通过 X-Ray API 使用服务图和指标的更多详细信息。有关组的更多信息，请参阅配置群组。有关添加和管理标签的更多信息，请参阅标记 X-Ray 采样规则和组。

使用 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。


$ 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 SDK 使用 X-Ray API 来获取采样规则、报告采样结果和获取配额。您可以使用这些 API 来更好地了解采样规则的工作方式或采用 X-Ray 开发工具包不支持的语言进行采样。

首先利用 GetSamplingRules 获取所有采样规则。


$ 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
        }
    ]
}

输出包括默认规则和自定义规则。如果还尚未创建采样规则，请参阅使用 X-Ray API 配置采样、分组和加密设置。

根据传入请求按优先级升序评估规则。当规则匹配时，使用固定速率和容器大小来制定采样决定。记录采样请求并忽略出于跟踪目的的未采样请求。制定采样决定时停止评估规则。

规则容器大小由指在应用固定速率之前，每秒要记录的跟踪目标数量。容器累积应用于所有服务，因此无法直接使用。但是，如果它是非零值，您可以每秒从容器借用一个跟踪，直到 X-Ray 分配配额。在收到配额之前，请每秒记录第一个请求，然后将固定速率应用于其他请求。固定速率是介于 0 和 1.00 之间的小数 (100%)。

以下示例显示了对 GetSamplingTargets 的调用以及有关在过去 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 的响应可能不包含您首次调用它时的配额。继续从容器借用，直到为您分配配额。

响应中的其他两个字段可能表示输入有问题。请针对上一次 GetSamplingRules 调用检查 LastRuleModification。如果较新，则获取相应规则的新副本。UnprocessedStatistics 可以包括指示规则已删除、输入中的统计文档太旧或权限错误的错误。

跟踪分段是应用程序提供服务的请求的 JSON 表示形式。跟踪分段将记录有关原始请求的信息、有关应用程序本地执行的工作的信息以及子分段，而子分段包含有关应用程序向 Amazon 资源、HTTP API 和 SQL 数据库发出的下游调用的信息。

分段文档将有关分段的信息传递给 X-Ray。分段文档最多可为 64KB，并且包含一个带子分段的完整分段、指示请求正在进行中的分段部分或一个单独发送的子分段。您可以使用 PutTraceSegments API 将分段文档直接发送到 X-Ray。

X-Ray 将编译和处理分段文档以生成可查询的跟踪摘要和完整跟踪，您可以分别使用 GetTraceSummaries 和 BatchGetTraces API 访问二者。除了您发送到 X-Ray 的分段和子分段之外，服务还使用子分段中的信息生成推断的分段并将其添加到完整跟踪。推断出的区段表示追踪地图中的下游服务和资源。

X-Ray 提供分段文档的 JSON 架构。你可以在这里下载架构：xray-segmentdocument-schema-v1.0.0。以下部分中更详细地描述了该架构中列出的字段和对象。

X-Ray 为分段字段的子集编制索引以用于筛选表达式。例如，如果您将分段上的 user 字段设置为唯一标识符，则可在 X-Ray 控制台中或使用 GetTraceSummaries API 搜索与特定用户关联的分段。有关更多信息，请参阅使用过滤器表达式。

在使用 X-Ray 开发工具包检测应用程序时，此开发工具包将为您生成分段文档。此开发工具包通过本地 UDP 端口将分段文档传输到 X-Ray 进程守护程序，而不是直接将分段文档发送到 X-Ray。有关更多信息，请参阅将分段文档发送到 X-Ray 进程守护程序。

分段记录有关应用程序提供服务的请求的跟踪信息。分段至少会记录请求的名称、ID、开始时间、跟踪 ID 和结束时间。

例最小完成分段


{
  "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 现在支持使用创建的跟踪 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 时，这不是必需的。

跟踪 ID 安全性
跟踪 ID 在响应标头中可见。使用安全的随机算法生成跟踪 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 应该与生成该分段的服务的域名或逻辑名称相匹配。但是，并未强制执行此规则。任何拥有 PutTraceSegments 权限的应用程序均可发送任何名称的分段。

以下字段是分段的可选字段。

可选分段字段

service - 一个包含应用程序的相关信息的对象。
- version - 一个标识为请求提供服务的应用程序版本的字符串。
user - 一个标识发送请求的用户的字符串。
origin— 运行应用程序的 Amazon 资源类型。
支持的值
- 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 开发工具包将父级子分段 ID 添加到下游 HTTP 调用的跟踪标头。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。
http - http 对象，包含原始 HTTP 请求的相关信息。
aws— 包含有关您的应用程序为请求提供服务的 Amazon 资源信息的aws对象。
error、throttle、fault 和 cause - 错误字段，指示出现错误并且包含有关导致错误的异常的信息。
annotations - annotations 对象，包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。
metadata - metadata 对象，包含要存储在分段中的任何附加数据。
subsegments - subsegment 对象数组。

您可以创建子分段来记录对 Amazon SDK 的调用 Amazon Web Services 和资源、对内部或外部 HTTP Web API 的调用或 SQL 数据库查询。您也可以创建子分段来调试应用程序中的代码块或为其添加注释。由于子分段可以包含其他子分段，因此，记录有关内部函数调用的元数据的自定义子分段可以包含其他自定义子分段和下游调用的子分段。

子分段从调用它的服务的角度，记录下游调用。X-Ray 使用子分段来确定未发送分段的下游服务，并在服务图上为其创建条目。

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

例带有嵌入式子分段的分段

独立子分段具有 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 已收到请求，然后在完成原始请求之前单独发送子分段来跟踪这些请求。

例正在进行分段


{
  "name" : "example.com",
  "id" : "70de5b6f19ff9a0b",
  "start_time" : 1.478293361271E9,
  "trace_id" : "1-581cf771-a006649127e371903a2de979",
  "in_progress": true
}

例独立子分段

独立子分段具有 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 现在支持使用创建的跟踪 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 时，这不是必需的。
parent_id - 子分段的父分段的分段 ID。仅在单独发送子分段时是必需的。对于嵌套子分段，一个子分段可以有一个分段或一个子分段作为其父级。
type - subsegment。仅在单独发送子分段时是必需的。

以下字段是子分段的可选字段。

可选子分段字段

namespace - 对于 AWS 开发工具包调用，为 aws；对于其他下游调用，为 remote。
http - http 对象，包含有关传出 HTTP 调用的信息。
aws— 包含有关您的应用程序调用的下游 Amazon 资源的信息的aws对象。
error、throttle、fault 和 cause - 错误字段，指示出现错误并且包含有关导致错误的异常的信息。
annotations - annotations 对象，包含您希望 X-Ray 为其编制索引以进行搜索的键-值对。
metadata - metadata 对象，包含要存储在分段中的任何附加数据。
subsegments - subsegment 对象数组。
precursor_ids - 子分段 ID 的数组，标识在此子分段之前完成的具有相同父级的子分段。

使用 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 生成推断分段。

例由 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
    }
  }

例下游 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
    }
  }
}

例下游 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 条注释编制索引。

例包含注释的 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)。您可以查看由 BatchGetTraces API 返回的完整分段文档中的元数据。以开头的字段密钥（debug在以下示例中）保留供 Amazon提供的软件开发工具包和客户端使用。AWS.

例包含元数据的自定义子分段


{
  "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 对象包含有关应用程序运行于的资源的信息。多个字段可应用于一个资源。例如，运行于 Elastic Beanstalk 上的多容器 Docker 环境中的应用程序包含有关 Amazon EC2 实例、该实例上运行的 Amazon EC2 容器和 Elastic Beanstalk 环境本身的信息。

`aws` (分段)

所有字段都是可选字段。

account_id - 如果您的应用程序将分段发送到其他 Amazon Web Services 账户，则记录运行应用程序的账户的 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 - 开发工具包类型。

例 Amazon 用插件屏蔽


"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"
   }
}

对于子分段，请记录有关您的应用程序访问的 Amazon Web Services 和资源的信息。X-Ray 使用此信息来创建推断分段，这些分段表示服务地图中的下游服务。

`aws` (子分段)

所有字段都是可选字段。

operation - 针对 Amazon Web Service 或资源调用的 API 操作的名称。
account_id— 如果您的应用程序访问其他账户中的资源，或者向其他账户发送分段，请记录拥有您的应用程序所访问 Amazon 资源的账户的 ID。
region - 如果资源所在的区域不同于应用程序所在的区域，则记录前者。例如，us-west-2。
request_id - 请求的唯一标识符。
queue_url - 对于 Amazon SQS 队列上的操作，为队列的 URL。
table_name - 对于 DynamoDB 表上的操作，为表的名称。

例对 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`

所有字段都是可选字段。

connection_string - 对于 SQL Server 连接或不使用 URL 连接字符串的其他数据库连接，记录连接字符串（不包括密码）。
url - 对于使用 URL 连接字符串的数据库连接，记录 URL（不包括密码）。
sanitized_query - 数据库查询，其任何用户提供的值已删除或由占位符替换。
database_type - 数据库引擎的名称。
database_version - 数据库引擎的版本号。
driver_version - 应用程序使用的数据库引擎驱动程序的名称和版本号。
user - 数据库用户名。
preparation - 如果查询使用了 PreparedCall，则为 call；如果查询使用了 PreparedStatement，则为 statement。

例具有 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=?;"
  }
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

使用软件开发工具包

X-Ray 进程守护程序

使用 X-Ray API

探索 X-Ray API

Amazon SDK 参考资料

先决条件

注意

生成跟踪数据

使用 test-api.sh 脚本

使用 X-Ray API

例 bin/service-graph.sh

例 bin/trace-urls.sh

例 bin/full-traces.sh

清理

终止 Elastic Beanstalk 环境

例 最小完成分段

例 正在进行分段

例 子分段

X-Ray 跟踪 ID 格式

注意

注意

注意

例 segment.txt

例 用于检索最后 10 分钟的服务图的脚本

例 GetServiceGraph 输出

例 用于按组 Example1 的名称检索服务图的脚本

例 用于获取跟踪摘要的脚本

例 GetTraceSummaries 输出

例 BatchGetTraces 命令

例 BatchGetTraces 输出

例 用于获取一分钟时间段内完整跟踪的脚本

例 GetTraceSummaries 输出示例-响应时间根本原因部分

例 重新格式化的响应时间根本原因

例 示例 JSON 筛选条件

加密设置

注意

例 UpdateSamplingRule 的 API 输入 10000-default.json

例 UpdateSamplingRule 的 API 输入 9000-base-scorekeep.json

例 UpdateSamplingRule 的 API 输入 5000-polling-scorekeep.json

注意

例 最小完成分段

注意

必填分段字段

X-Ray 跟踪 ID 格式

注意

跟踪 ID 安全性

服务名称

可选分段字段

支持的值

例 带有嵌入式子分段的分段

例 正在进行分段

例 独立子分段

注意

必填子分段字段

X-Ray 跟踪 ID 格式

注意

可选子分段字段

http

例 由 Amazon EC2 上运行的应用程序提供服务的 HTTP 调用的分段

例 下游 HTTP 调用的子分段

例 下游 HTTP 调用的推断分段

例 包含注释的 HTTP 调用的分段

例 包含元数据的自定义子分段

aws (分段)

例 Amazon 用插件屏蔽

aws (子分段)

例 对 DynamoDB 进行调用以保存项目的子分段

错误类型

cause

exception

stackFrame

sql

例 具有 SQL 查询的子分段

使用 `test-api.sh` 脚本

例最小完成分段

例正在进行分段

例子分段

例用于检索最后 10 分钟的服务图的脚本

例用于按组 Example1 的名称检索服务图的脚本

例用于获取跟踪摘要的脚本

例用于获取一分钟时间段内完整跟踪的脚本

例重新格式化的响应时间根本原因

例示例 JSON 筛选条件

例 `UpdateSamplingRule` 的 API 输入 10000-default.json

例 `UpdateSamplingRule` 的 API 输入 9000-base-scorekeep.json

例 `UpdateSamplingRule` 的 API 输入 5000-polling-scorekeep.json

例最小完成分段

例带有嵌入式子分段的分段

例正在进行分段

例独立子分段

`http`

例由 Amazon EC2 上运行的应用程序提供服务的 HTTP 调用的分段

例下游 HTTP 调用的子分段

例下游 HTTP 调用的推断分段

例包含注释的 HTTP 调用的分段

例包含元数据的自定义子分段

`aws` (分段)

`aws` (子分段)

例对 DynamoDB 进行调用以保存项目的子分段

`cause`

`exception`

`stackFrame`

`sql`

例具有 SQL 查询的子分段