本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 选择界面 AWS X-Ray 可以深入了解您的应用程序的工作原理以及它与其他服务和资源的交互情况。在对应用程序进行检测或配置后，X-Ray 会在您的应用程序处理请求时收集跟踪数据。您可以分析这些跟踪数据，以识别性能问题、排查错误并优化资源。本指南向您展示如何使用以下指南与 X-Ray 进行交互： + AWS 管理控制台 如果您想快速入门，或者可以使用预先构建的可视化来执行基本任务，请使用。 + 选择 Amazon CloudWatch 控制台，获取包含 X-Ray 控制台所有功能的最新用户体验。 + 如果您想要更简单的界面或不想更改与 X-Ray 的交互方式，请使用 X-Ray 控制台。 + 如果您需要的自定义跟踪、监控或日志记录功能超出了其所 AWS 管理控制台 能提供的范围，请使用 SDK。 + 如果您想要基于开源 OpenTelemetry SDK、具有更多 AWS 安全层和优化层且与供应商无关的 SDK，请选择 ADOT SDK。 + 如果您想要更简单的 SDK 或不想更新应用程序代码，请选择 X-Ray SDK。 + 如果 SDK 不支持您的应用程序的编程语言，请使用 X-Ray API 操作。 下图可帮助您选择如何与 X-Ray 进行交互： ![\[X-Ray 显示有关应用程序请求的详细信息。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/xray-choose-interface.png) **Topics** + [使用 SDK](aws-xray-interface-sdk.md) + [使用控制台](aws-xray-interface-console.md) + [使用 X-Ray API](xray-api.md) # 使用 SDK **注意** X-Ray SDK/Daemon 维护通知 — 2026 年 2 月 25 日， AWS X-Ray SDKs/Daemon 将进入维护模式，在该模式下，X-Ray SDK 和 Daemon 的发布 AWS 将仅限于解决安全问题。有关支持时间表的更多信息，请参阅 [X-Ray SDK 和 Daemon Support 时间表](xray-sdk-daemon-timeline.md)。我们建议迁移到 OpenTelemetry。有关迁移到的更多信息 OpenTelemetry，请参阅[从 X-Ray 仪器迁移到 OpenTelemetry 仪器](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-migration.html)。 如果您想使用命令行界面，或者需要的自定义跟踪、监控或日志记录功能超出 AWS 管理控制台中提供的范围，请使用 SDK。您也可以使用 S AWS DK 开发使用 X-Ray 的程序 APIs。你可以使用 AWS Distro for OpenTelemetry (ADOT) SDK 或 X-Ray SDK。 如果您使用 SDK，则可以在检测应用程序和配置收集器或代理时为工作流添加自定义。您可以使用 SDK 来执行以下无法使用 AWS 管理控制台完成的任务： + 发布自定义指标 - 以低至 1 秒的高分辨率对指标采样，使用多个维度添加有关指标的信息，并将数据点聚合到统计数据集中。 + 自定义收集器 - 自定义收集器任何部分的配置，包括接收器、处理器、导出器和连接器。 + 自定义您的检测 - 自定义分段和子分段，将自定义键值对添加为属性，并创建自定义指标。 + 以编程方式创建和更新采样规则。 如果您想灵活地ADOT使用具有额外 AWS 安全性和优化层的标准化 OpenTelemetry SDK，请使用 SDK。 AWS Distro fo ADOT r OpenTelemetry () SDK 是一个与供应商无关的软件包，它允许与其他供应商和非AWS 服务的后端集成，而无需重新分析代码。 如果您已经在使用 X-Ray SDK，只与 AWS 后端集成，并且不想更改与 X-Ray 或应用程序代码的交互方式，请使用 X-Ray SDK。 有关每项特征的更多信息，请参阅[在 AWS Distro for 和 X-Ray OpenTelemetry 之间进行选择 SDKs](xray-instrumenting-your-app.md#xray-instrumenting-choosing)。 ## 使用 ADOT SDK S ADOT DK 是一组向后端服务发送数据的开源 APIs、库和代理。 ADOT由多个后端和代理支持 AWS，并与多个后端和代理集成，并提供大量由OpenTelemetry社区维护的开源库。使用 ADOT SDK 可检测您的应用程序并收集日志、元数据、指标和跟踪。您还可以ADOT使用监控服务并根据中的指标设置警报 CloudWatch。 如果您使用的是 ADOT SDK，则可以将以下选项与代理结合使用： + 将 ADOT SDK 与[CloudWatch 代理](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)一起使用 — 推荐。 + 将 ADOT SDK 与 [ADOTCollect](https://aws-otel.github.io/docs/getting-started/collector) or 配合使用 — 如果您想使用具有多 AWS 层安全性和优化的独立于供应商的软件，则建议您使用。 要使用 ADOT SDK，请执行以下操作： + 使用 ADOT SDK 检测您的应用程序。有关更多信息，请参阅 [ADOT 技术文档](https://aws-otel.github.io/docs/introduction)中适用于编程语言的文档。 + 配置 ADOT 收集器以告知其将收集的数据发送到何处。 ADOT收集器收到您的数据后，会将其发送到您在ADOT配置中指定的后端。 ADOT可以将数据发送到多个后端，包括外部的供应商 AWS，如下图所示： ![\[在检测应用程序并配置收集器时，可以自定义 ADOT 收集器。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/adot-sdk.png) AWS 定期更新ADOT以增加功能并与[OpenTelemetry](https://opentelemetry.io/docs/)框架保持一致。开发 ADOT 的更新和未来计划是向公众开放的[路线图](https://github.com/orgs/aws-observability/projects/4)的一部分。ADOT 支持多种编程语言，其中包括： + Go + Java + JavaScript + Python + .NET + Ruby + PHP 如果您使用的是 Python，则 ADOT 可以自动检测您的应用程序。要开始使用ADOT，请参阅 Collecto [ OpenTelemetry r AWS 发行版[简介](https://aws-otel.github.io/docs/introduction)和入门](https://aws-otel.github.io/docs/getting-started/collector)。 ## 使用 X-Ray SDK X-Ray SDK 是一组向 AWS 后端服务发送数据的 AWS APIs 和库。使用 X-Ray SDK 可检测您的应用程序并收集跟踪数据。您无法使用 X-Ray SDK 收集日志或指标数据。 如果您使用的是 X-Ray SDK，则可以将以下选项与代理结合使用： + 结合使用 X-Ray SDK 和 [AWS X-Ray 守护程序](xray-daemon.md) - 如果您不想更新应用程序代码，请使用此选项。 + 将 X-Ray SDK 与 CloudWatch 代理一起使用 —（推荐） CloudWatch 代理与 X-Ray SDK 兼容。 要使用 X-Ray SDK，请执行以下操作： + 使用 X-Ray SDK 检测您的应用程序。 + 配置收集器以告知其将收集到的数据发送到何处。您可以使用 CloudWatch 代理或 X-Ray 守护程序来收集您的跟踪信息。 收集器或代理收到您的数据后，它会将其发送到您在代理配置中指定的 AWS 后端。X-Ray SDK 只能向 AWS 后端发送数据，如下图所示： ![\[将 X-Ray SDK 与 CloudWatch 代理或 X-Ray 守护程序一起使用。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/xray-sdk.png) 如果您使用的是 Java，则可以使用 X-Ray SDK 自动检测您的应用程序。要开始使用 X-Ray SDK，请查看与以下编程语言相关的库： + [Go](xray-go.md) + [Java](xray-java.md) + [Node.js](xray-nodejs.md) + [Python](xray-python.md) + [.NET](xray-dotnet.md) + [Ruby](xray-ruby.md) # 使用控制台 如果您想要使用只需最少编码的图形用户界面（GUI），请使用控制台。不熟悉 X-Ray 的用户可以使用预先构建的可视化效果快速入门，并执行基本任务。您可以直接从控制台执行以下操作： + 启用 X-Ray。 + 查看应用程序性能的简单摘要。 + 检查应用程序的运行状况。 + 识别高级别错误。 + 查看基本跟踪摘要。 要与 X-Ray 进行交互，您可以使用 Amazon CloudWatch 控制台（网址为：[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）或 X-Ray 控制台（网址为：[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)）。 ## 使用 Amazon CloudWatch 控制台 CloudWatch 控制台包含新的 X-Ray 功能，这些功能是从 X-Ray 控制台重新设计的，使其更易于使用。如果您使用 CloudWatch 控制台，则可以查看 CloudWatch 日志和指标以及 X-Ray 跟踪数据。可使用 CloudWatch 控制台查看和分析包括以下内容在内的数据： + X-Ray 跟踪 - 在应用程序处理请求时查看、分析和筛选与其关联的跟踪。使用这些跟踪可查找高延迟、调试错误并优化您的应用程序工作流。查看跟踪地图和服务地图，以查看应用程序工作流的可视化形式。 + 日志 - 查看、分析和筛选应用程序生成的日志。使用日志可排查错误，并根据特定的日志值设置监控。 + 指标 - 使用您的资源发出的指标或创建您自己的指标，来衡量和监控您的应用程序性能。以图形和图表的形式来查看这些指标。 + 监控网络和基础设施 - 监控主要网络的中断情况以及基础结构（包括容器化应用程序、其他 AWS 服务和客户端）的运行状况和性能。 + 下面的**使用 X-Ray 控制台**一节列出了 X-Ray 控制台中的所有功能。 有关 CloudWatch 控制台的更多信息，请参阅 [Amazon CloudWatch 入门](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/GettingStarted.html)。 访问 [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)，登录 Amazon CloudWatch 控制台。 ## 使用 X-Ray 控制台 X-Ray 控制台为应用程序请求提供分布式跟踪。如果您想要更简单的控制台体验或不想更新应用程序代码，可使用 X-Ray 控制台。AWS 不再开发 X-Ray 控制台。X-Ray 控制台包含以下用于检测应用程序的特征： + [见解](xray-console-insights.md) - 自动检测应用程序性能中的异常并找出根本原因。见解包含在 CloudWatch 控制台的**见解**下方。有关更多信息，请参阅[使用 X-Ray 控制台](#xray-console)中的**使用 X-Ray Insights**。 + 服务地图 - 查看应用程序的图形结构及其与客户端、资源、服务和依赖项的连接。 + 跟踪 - 查看应用程序在处理请求时生成的跟踪的概述。使用跟踪数据可了解您的应用程序在 HTTP 响应和响应时间等基本指标方面的表现。 + 分析 - 使用图表解释、浏览和分析跟踪数据，以了解响应时间分布。 + 配置 - 创建自定义跟踪以更改以下各项的默认配置： + 采样 - 创建规则，以定义对应用程序采样以获取跟踪信息的频率。有关更多信息，请参阅[使用 X-Ray 控制台](#xray-console)中的**配置采样规则**。 + [加密](xray-console-encryption.md) - 使用密钥对静态数据加密，您可以使用 AWS Key Management Service 对该密钥进行审核或禁用。 + 分组 - 使用筛选条件表达式来定义一组具有共同特征（例如 URL 名称或响应时间）的跟踪。有关更多信息，请参阅[配置分组](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray-interface-console.html#xray-console-groups)。 要登录 X-Ray 控制台，请访问 [https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)。 ## 深入了解 X-Ray 控制台 使用 X-Ray 控制台可查看您的应用程序提供服务的请求的服务和关联跟踪的地图，并配置影响将跟踪发送到 X-Ray 的方式的分组和采样规则。 **注意** X-Ray 服务地图和 CloudWatch ServiceLens 地图已合并为 Amazon CloudWatch 控制台中的 X-Ray 跟踪地图。打开 [CloudWatch 控制台](https://console.aws.amazon.com/cloudwatch/)，然后在左侧导航窗格的 **X-Ray 跟踪**下选择**跟踪地图**。 CloudWatch 现在包括 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)，可以发现和监控您的应用程序服务、客户端、Synthetics Canary 和服务依赖项。使用 Application Signals 查看您的服务列表或可视地图，根据您的服务级别目标（SLO）查看运行状况指标，并深入查看关联 X-Ray 跟踪以便更详细地进行问题排查。 主 X-Ray 控制台页面是跟踪地图，是 JSON 服务图的可视化形式，由 X-Ray 从您的应用程序生成的跟踪数据生成。该地图包含您账户中为请求提供服务的每个应用程序的服务节点，表示请求来源的上游客户端节点以及表示应用程序在处理请求时使用的 Web 服务和资源的下游服务节点。此外，还提供其他页面来查看跟踪和跟踪详情，以及配置组和采样规则。 在以下各节中查看 X-Ray 控制台体验，并与 CloudWatch 控制台进行比较。 **Topics** + [使用 Amazon CloudWatch 控制台](#aws-xray-interface-console-cw) + [使用 X-Ray 控制台](#xray-console) + [深入了解 X-Ray 控制台](#xray-console-explore) + [使用 X-Ray 跟踪地图](xray-console-servicemap.md) + [查看跟踪和跟踪详情](xray-console-traces.md) + [使用筛选条件表达式](xray-console-filters.md) + [跨账户跟踪](xray-console-crossaccount.md) + [跟踪事件驱动型应用程序](xray-tracelinking.md) + [使用延迟直方图](xray-console-histograms.md) + [使用 X-Ray 见解](xray-console-insights.md) + [与 Analytics 控制台交互](xray-console-analytics.md) + [配置组](xray-console-groups.md) + [配置采样规则](xray-console-sampling.md) + [配置自适应采样](xray-adaptive-sampling.md) + [控制台深层链接](xray-console-deeplinks.md) # 使用 X-Ray 跟踪地图 查看 X-Ray 跟踪地图来识别出现错误的服务、具有高延迟的连接或针对不成功请求的跟踪。 **注意** CloudWatch 现在包括 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html)，可以发现和监控您的应用程序服务、客户端、Synthetics Canary 和服务依赖项。使用 Application Signals 查看您的服务列表或可视地图，根据您的服务级别目标（SLO）查看运行状况指标，并深入查看关联 X-Ray 跟踪以便更详细地进行问题排查。 X-Ray 服务地图和 CloudWatch ServiceLens 地图合并为 Amazon CloudWatch 控制台中的 X-Ray 跟踪地图。打开 [CloudWatch 控制台](https://console.aws.amazon.com/cloudwatch/)，然后在左侧导航窗格的 **X-Ray 跟踪**下选择**跟踪地图**。 ## 查看跟踪映射 跟踪地图是跟踪数据的可视化形式，此类数据由您的应用程序生成。地图显示为请求提供服务的服务节点，表示请求来源的上游客户端节点以及表示应用程序在处理请求时使用的 Web 服务和资源的下游服务节点。 跟踪地图显示使用 Amazon SQS 和 Lambda 的不同事件驱动型应用程序中跟踪的互联视图。有关更多信息，请参阅[跟踪事件驱动型应用程序](xray-tracelinking.md)。跟踪地图还支持[跨账户跟踪](xray-console-crossaccount.md)，在一张地图中显示多个账户中的节点。 ------ #### [ CloudWatch console ] **如何在 CloudWatch 控制台中查看跟踪地图** 1. [打开 CloudWatch 控制台](https://console.aws.amazon.com/cloudwatch/)。在左侧导航窗格的 **X-Ray 跟踪**部分下选择**跟踪地图**。 ![\[CloudWatch 控制台跟踪地图页面\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-servicemap-cw.png) 1. 选择一个服务节点来查看该节点的请求，或选择两个节点之间的边缘来查看经过该连接的请求。 1. 其他信息显示在跟踪地图下方，其中包括指标、警报以及响应时间分布的选项卡。在**指标**选项卡上，选择每张图的范围以深入查看更多详情，或选择**故障**或**错误**选项以筛选跟踪。在**呼应时间分布**选项卡上，选择在图内的一个范围以按照呼应时间来筛选跟踪。 ![\[Dashboard showing latency, requests, and faults metrics for an ElasticBeanstalk environment.\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-cw-servicemap-node-detail.png) 1. 选择**查看跟踪**查看跟踪，或者如果已应用筛选条件，请选择**查看经过筛选的跟踪**。 1. 选择**查看日志**以查看与所选节点有关联的 CloudWatch 节点。并非所有跟踪地图节点都支持查看日志。有关更多信息，请参阅[排查 CloudWatch 日志问题](xray-troubleshooting.md#xray-troubleshooting-Nologs)。 跟踪地图通过用颜色概述每个节点来表示每个节点存在的问题： + **红色**表示服务器故障（500 系列错误） + **黄色**表示客户端错误（400 系列错误） + **紫色**表示限制错误（429 请求过多） 如果您的跟踪地图较大，请使用屏幕上的控件或鼠标放大、缩小和移动地图。 ------ #### [ X-Ray console ] **查看服务地图** 1. 打开 [X-Ray 控制台](https://console.aws.amazon.com/xray/home#)。默认情况下，将显示服务地图。也可以从左侧导航窗格中选择**服务地图**。 ![\[X-Ray 控制台服务地图页\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-servicemap-xray.png) 1. 选择一个服务节点来查看该节点的请求，或选择两个节点之间的边缘来查看经过该连接的请求。 1. 使用呼应分布[直方图](xray-console-histograms.md)按持续时间筛选跟踪，并选择要查看其跟踪的状态代码。然后选择**查看跟踪**打开应用筛选条件表达式后的跟踪列表。 ![\[Response distribution graph showing latency peaks and service details for Scorekeep AWS ECS container.\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-servicemap-nodedetail-xray.png) 服务地图根据成功调用与错误和故障的比率为每个节点显示颜色，从而指示节点的运行状况： + **绿色**表示成功调用 + **红色**表示服务器故障（500 系列错误） + **黄色**表示客户端错误（400 系列错误） + **紫色**表示限制错误（429 请求过多） 如果您的服务地图较大，则使用屏幕上的控件或鼠标可放大、缩小和移动该图像。 ------ **注意** X-Ray 跟踪地图最多可以显示 10,000 个节点。极少数情况下，当服务节点总数超出此上限时，会收到错误消息并且无法在控制台中显示完整的跟踪地图。 ## 按组筛选跟踪地图 通过使用[筛选条件表达式](xray-console-filters.md)，您可以定义某个组中要包含哪些跟踪的标准。然后，使用以下步骤在跟踪地图中显示该特定组。 ------ #### [ CloudWatch console ] 从跟踪地图左上角的组筛选器中选择组名称。 ![\[Search bar for filtering by X-Ray group, with "TestGroup" displayed as an option.\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-servicemap-groups-cw.png) ------ #### [ X-Ray console ] 从搜索栏左侧的下拉菜单中选择一个组名称。 ![\[Drop-down menu showing Default, TestGroup, Create group, and Learn more options.\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-select-console.png) ------ 现在，将会对服务地图进行筛选以显示与所选组的筛选条件表达式匹配的跟踪。 ## 跟踪地图图例和选项 跟踪地图包含图例和多个选项用于自定义地图显示。 ------ #### [ CloudWatch console ] 选择地图右上角的**图例和选项**下拉列表。选择节点内显示的内容，其中包括： + **指标**显示所选时间范围内的平均响应时间和每分钟发送的跟踪数量。 + **节点**显示每个节点内的服务图标。 从**首选项**窗格中选择更多地图设置，可通过点击地图右上角的齿轮图标访问。这些设置包括选择使用哪个指标来确定每个节点的大小，以及应在地图上显示哪些 Canary。 ------ #### [ X-Ray console ] 在地图右上角选择**地图图例**链接，显示服务地图图例。可以在跟踪地图的右下角选择服务地图选项，包括： + 每人节点内显示的**服务图标**切换，用于切换是显示服务图标，还是平均呼应时间以及在所选时间范围内每分钟的跟踪数量。 + **节点大小：None** 将所有节点设置为相同大小。 + **节点大小：运行状况**按受影响的请求数量确定节点大小，其中包括错误、故障或受限制的请求。 + **节点大小：流量**按请求总数确定节点大小。 ------ # 查看跟踪和跟踪详情 使用 X-Ray 控制台中的**跟踪**页面根据 URL、响应代码或跟踪摘要中的其他数据查找跟踪。从跟踪列表中选择跟踪后，**跟踪详情**页面会显示与所选跟踪关联的服务节点的地图，以及跟踪分段的时间表。 ## 查看跟踪 ------ #### [ CloudWatch console ] **在 CloudWatch 控制台中查看跟踪** 1. 登录 AWS 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）。 1. 在左侧导航窗格中，依次选择 **X-Ray 跟踪**和**跟踪**。您可以按组筛选或输入[筛选条件表达式](xray-console-filters.md)。这将筛选出显示在页面底部**跟踪**部分中的跟踪。 或者，也可以使用服务地图导航到某个具体的服务节点，然后查看跟踪。这将打开已应用查询的**跟踪**页面。 1. 在**查询优化**部分中优化您的查询。要按常用属性筛选跟踪，请从**按条件优化查询**旁边的向下箭头中选择一个选项。这些选项包括以下内容： + 节点 - 按服务节点筛选跟踪。 + 资源 ARN - 按与跟踪关联的资源筛选跟踪。这些资源的示例包括 Amazon Elastic Compute Cloud（Amazon EC2）实例、AWS Lambda 函数或 Amazon DynamoDB 表。 + 用户 - 按用户 ID 筛选跟踪。 + 错误根本原因消息 - 按错误根本原因筛选跟踪。 + URL - 按应用程序使用的 URL 路径筛选跟踪。 + HTTP 状态码 - 按应用程序返回的 HTTP 状态码筛选跟踪。您可以指定自定义响应代码或从以下代码中进行选择： + `200` - 请求成功。 + `401` - 请求缺少有效的身份验证凭证。 + `403` - 请求缺少有效权限。 + `404` - 服务器找不到请求的资源。 + `500` - 服务器遇到了意外情况并生成了内部错误。 选择一个或多个条目，然后选择**添加到查询**，将所选条目添加到页面顶部的筛选条件表达式中。 1. 要查找单个跟踪，请直接在查询字段中输入[跟踪 ID](xray-api-sendingdata.md#xray-api-traceids)。可以使用 X-Ray 格式或 World Wide Web Consortium（W3C）格式。例如，使用[适用于 OpenTelemetry 的 AWS Distro](xray-instrumenting-your-app.md#xray-instrumenting-opentel) 创建的跟踪采用 W3C 格式。 **注意** 当您查询采用 W3C 格式跟踪 ID 创建的跟踪时，控制台会显示 X-Ray 格式的匹配跟踪。例如，如果您以 W3C 格式查询 `4efaaf4d1e8720b39541901950019ee5`，控制台会显示等效的 X-Ray：`1-4efaaf4d-1e8720b39541901950019ee5`。 1. 随时选择**运行查询**，可以在页面底部的**跟踪**部分中匹配的跟踪列表。 1. 要显示单个跟踪的**跟踪详情**，请从列表中选择一个跟踪 ID。 下图所示的**跟踪地图**包含与跟踪关联的服务节点，以及代表构成跟踪的分段所采用路径的节点之间的边缘。**跟踪摘要**之后是**跟踪地图**。摘要包含有关 `GET` 操作示例、其**响应代码**、跟踪运行**持续时间**以及请求**时限**的信息。**分段时间线**之后是**跟踪摘要**，该摘要显示跟踪分段和子分段的持续时间。 ![\[跟踪地图、摘要和分段时间线详细介绍有关服务节点和跟踪中分段的信息。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/xray-trace-details-cw.png) 如果您有一个使用 Amazon SQS 和 Lambda 的事件驱动型应用程序，则可以在**跟踪地图**中看到每个请求的关联跟踪视图。在地图中，来自消息创建者的跟踪链接到来自 AWS Lambda 使用者的跟踪，并显示为虚线边缘。有关事件驱动型应用程序的更多信息，请参阅[跟踪事件驱动型应用程序](xray-tracelinking.md)。 **跟踪**和**跟踪详情**页面还支持[跨账户跟踪](xray-console-crossaccount.md)，其中会列出跟踪列表中和单个跟踪地图中多个账户内的跟踪。 ------ #### [ X-Ray console ] **如何在 X-Ray 控制台中查看跟踪** 1. 在 X-Ray 控制台中打开[跟踪](https://console.aws.amazon.com/xray/home#/traces)页面。**跟踪概述**面板显示按常用特征分组的跟踪列表，包括**错误根本原因**、**ResourceARN** 和 **InstanceId**。 1. 要选择常用特征来查看分组的跟踪集，请展开**分组依据**旁边的向下箭头。下图显示了按 [AWS X-Ray 示例应用程序](xray-scorekeep.md) URL 分组的跟踪的跟踪概述以及关联跟踪的列表。 ![\[按 URL 分组的跟踪概述示例，然后是跟踪列表，其详细信息包括 ID、方法和响应。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/scorekeep-traces.png) 1. 选择跟踪的 **ID** 以在**跟踪列表**下查看。您也可以在导航窗格中选择**服务地图**，来查看特定服务节点的跟踪。然后，您可以查看与该节点关联的跟踪。 **时间线**选项卡显示跟踪的请求流，包括以下内容： + 跟踪中每个分段的路径地图。 + 分段到达跟踪地图中的节点花了多长时间。 + 在跟踪地图中向该节点发出了多少个请求。 下图显示了与向应用程序示例发出的 `GET` 请求关联的**跟踪地图**示例。箭头显示每个分段完成请求所采用的路径。服务节点显示在 `GET` 请求期间发出的请求数。 ![\[跟踪地图，然后是时间线，其中包含各个分段、其持续时间、起点和彼此的终点。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/xray-trace-details.png) 有关**时间线**选项卡的更多信息，请参阅下面的**深入了解跟踪时间线**一节。 **原始数据**选项卡以 `JSON` 格式显示有关跟踪以及构成该跟踪的分段和子分段的信息。此类信息可能包含以下内容： + 时间戳 + 唯一 ID + 与分段或子分段关联的资源 + 分段或子分段的源或起源 + 有关对您的应用程序发出的请求的其他信息，例如 HTTP 请求的响应 ------ ## 深入了解跟踪时间线 **时间线**部分在水平条旁边显示分段和子分段的层次结构，该水平条与其完成任务所用的时间相对应。列表中的第一个条目为分段，表示服务为单个请求记录的所有数据。子分段以缩进形式列出，并在分段后面列出。各列包含有关每个分段的信息。 ------ #### [ CloudWatch console ] 在 CloudWatch 控制台中，**分段时间线**提供以下信息： + 第一列：列出所选跟踪中的分段和子分段。 + **分段状态**列：列出每个分段和子分段的状态结果。 + **响应代码**列：列出对分段或子分段发出的浏览器请求的 HTTP 响应状态代码（如果有）。 + **持续时间**列：列出分段或子分段的运行时长。 + **托管位置**列：列出运行分段或子分段的命名空间或环境（如果适用）。有关更多信息，请参阅[收集的维度和维度组合](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AppSignals-StandardMetrics.html#AppSignals-StandardMetrics-Dimensions)。 + 最后一列：显示与分段或子分段运行的持续时间相对应的水平条（相对于时间线中的其他分段或子分段）。 要按服务节点对分段和子分段列表进行分组，请打开**按节点分组**。 ------ #### [ X-Ray console ] 在跟踪详情页面中，选择**时间线**选项卡，以查看构成跟踪的每个分段和子分段的时间线。 在 X-Ray 控制台中，**时间线**提供以下信息： + **名称**列：列出跟踪中分段和子分段的名称。 + **响应**列：列出针对分段或子分段发出的浏览器请求的 HTTP 响应状态代码（如果有）。 + **持续时间**列：列出分段或子分段的运行时长。 + **状态**列：列出分段或子分段状态的结果。 + 最后一列：显示与分段或子分段运行的持续时间相对应的水平条（相对于时间线中的其他分段或子分段）。 要查看控制台用来生成时间线的原始跟踪数据，请选择**原始数据**选项卡。原始数据以 `JSON` 格式显示有关跟踪以及构成该跟踪的分段和子分段的信息。此类信息可能包含以下内容： + 时间戳 + 唯一 ID + 与分段或子分段关联的资源 + 分段或子分段的源或起源 + 有关对您的应用程序发出的请求的其他信息，例如 HTTP 请求的响应。 ------ 当您使用检测的 SDKAWS、HTTP 或 SQL 客户端调用外部资源时，X-Ray SDK 会自动记录子分段。也可以使用 X-Ray SDK 记录任何函数或代码块的自定义子分段。自定义子分段在打开时记录的其他子分段将成为自定义子分段的子级。 ## 查看分段详细信息 在跟踪**时间线**中选择某分段的名称，可以查看其详细信息。 **分段详细信息**面板显示**概述**、**资源**、**注释**、**元数据**、**异常**以及 **SQL** 选项卡。以下选项卡将适用： + **概述**选项卡显示有关请求和响应的信息。信息包括名称、开始时间、结束时间、持续时间、请求 URL、请求操作、请求响应代码以及任何错误和故障。 + 分段的**资源**选项卡显示有关 X-Ray SDK 以及运行您的应用程序的 AWS 资源的信息。使用 X-Ray SDK 的 Amazon EC2、AWS Elastic Beanstalk 或 Amazon ECS 插件记录特定于服务的资源信息。有关插件的更多信息，请参阅[配置 X-Ray SDK for Java](xray-sdk-java-configuration.md)中的**服务插件**部分。 + 其余的选项卡显示为分段记录的**注释**、**元数据**和**异常**。当所检测的请求生成异常时，会自动捕获这些异常。注释和元数据包含您使用 X-Ray SDK 提供的操作记录的附加信息。要将注释或元数据添加到分段，请使用 X-Ray SDK。有关更多信息，请参阅[正在对您的应用程序进行检测 AWS X-Ray](xray-instrumenting-your-app.md)中“使用 SDKAWS X-Ray 检测应用程序”下方列出的特定于语言的链接。 ## 查看子分段详细信息 在跟踪时间线中选择某个子分段的名称，可以查看其详细信息。 + **概述**选项卡包含有关请求和响应的信息。其中包括名称、开始时间、结束时间、持续时间、请求 URL、请求操作、请求响应代码以及任何错误和故障。对于使用已检测客户端生成的子分段，**概述**选项卡包含从您的应用程序角度来看的请求和响应信息。 + 子分段的**资源**选项卡显示有关用于运行子分段的 AWS 资源的详细信息。例如，资源选项卡可能包含 AWS Lambda 函数 ARN、有关 DynamoDB 表的信息、调用的任何操作以及请求 ID。 + 其余的选项卡显示子分段上记录的**注释**、**元数据**和**异常**。当所检测的请求生成异常时，会自动捕获这些异常。注释和元数据包含您使用 X-Ray SDK 提供的操作记录的附加信息。使用 X-Ray SDK，将注释或元数据添加到分段。有关更多信息，请参阅[正在对您的应用程序进行检测 AWS X-Ray](xray-instrumenting-your-app.md)中**使用 SDKAWS X-Ray 检测应用程序**下方列出的特定于语言的链接。 对于自定义子分段，**概述**选项卡显示子分段的名称，您可以设置该名称来指定它所记录的代码或函数区域。有关更多信息，请参阅[使用适用于 Java 的 X-Ray 开发工具包生成自定义子分段](xray-sdk-java-subsegments.md)中**使用 SDKAWS X-Ray 检测应用程序**下方列出的特定于语言的链接。 下图显示了自定义子分段的**概述**选项卡。概述包含子分段 ID、父级 ID、名称、开始和结束时间、持续时间、状态以及错误或故障。 ![\[有关子分段的概述信息，包括 ID、父级 ID、名称、时间、错误和故障。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/scorekeep-PUTrules-customsubsegment-overview.png) 自定义子分段的**元数据**选项卡包含有关该子分段使用的资源的信息（采用 JSON 格式）。 # 使用筛选条件表达式 使用*筛选条件表达式* 查看特定请求、服务、两个服务之间的连接（边缘）或满足某个条件的请求的跟踪地图或跟踪。X-Ray 提供筛选表达式语言，根据原始段上请求标头、响应状态和索引字段中的数据筛选请求、服务和边缘。 当您选择某个跟踪时间段以在 X-Ray 控制台中查看时，您获得的结果可能会超出可在控制台中显示的内容。在右上角，控制台显示其扫描的跟踪数量，以及是否有更多跟踪可用。您可以使用筛选条件表达式缩小结果范围，以仅限于您要查找的跟踪。 **Topics** + [筛选条件表达式详细信息](#xray-console-filters-details) + [将筛选条件表达式与组一起使用](#groups) + [筛选条件表达式语法](#console-filters-syntax) + [布尔值关键字](#console-filters-boolean) + [数字关键字](#console-filters-number) + [字符串关键字](#console-filters-string) + [复杂关键字](#console-filters-complex) + [id 函数](#console-filters-functions) ## 筛选条件表达式详细信息 当您[选择跟踪地图中的节点](xray-console-servicemap.md)时，控制台会基于该节点的服务名称以及您的选择中提供的错误类型，来构建筛选条件表达式。要查找显示性能问题的跟踪或与特定请求相关的跟踪，可以调整控制台提供的表达式，或创建您自己的表达式。如果您使用 X-Ray SDK 添加注释，您还可以根据是否存在注释键或根据键值进行筛选。 **注意** 如果您在跟踪地图中选择相对时间范围并选择一个节点，则控制台会将时间范围转换为绝对开始和结束时间。为了确保节点的跟踪显示在搜索结果中，并避免扫描时间在该节点未处于活动状态的期间内，时间范围只应包含该节点发送跟踪的时间。若要相对于当前时间进行搜索，您可以在跟踪页面中切换回相对时间范围，并重新扫描。 如果结果仍超过控制台可显示的内容，控制台会显示有多少个跟踪匹配，以及扫描的跟踪数。显示的百分比是已扫描选定时间范围的百分比。为确保您会看到在结果中提供所有匹配的跟踪，进一步缩小筛选条件表达式的范围，或选择一个更短的时间范围。 为了先获取最新结果，控制台会从时间范围结尾开始反向扫描。如果有大量的跟踪，但结果很少，控制台会将时间范围分为多个分块并执行并行扫描。进度条显示已扫描的时间范围部分。 ![\[Progress bar showing 52% of time range scanned, with 49 matching traces found.\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-tracescan-parallel.png) ## 将筛选条件表达式与组一起使用 组是由筛选条件表达式定义的跟踪的集合。您可以使用群组来生成其他服务图表并提供 Amazon CloudWatch 指标。 组由其名称或 Amazon 资源名称（ARN）标识，并包含筛选条件表达式。此服务将比较传入到表达式的跟踪并相应地存储它们。 您可以使用筛选条件表达式搜索栏左侧的下拉菜单创建和修改组。 **注意** 如果服务在限定组时遇到错误，则在处理传入跟踪时不再包含该组，并记录错误指标。 有关组的更多信息，请参阅 [配置组](xray-console-groups.md)。 ## 筛选条件表达式语法 筛选条件表达式可以包含一个*关键字*、一个一元或二元*运算符* 和一个*值* 用于比较。 ``` keyword operator value ``` 不同的运算符可用于不同类型的关键字。例如，`responsetime` 是一个数字关键字，可与数字相关运算符进行比较。 **Example - 响应时间超过 5 秒的请求** ``` responsetime > 5 ``` 您可以使用 `AND` 或 `OR` 运算符将多个表达式组合成一个复合表达式。 **Example - 总时长在 5-8 秒之间的请求** ``` duration >= 5 AND duration <= 8 ``` 简单的关键字和运算符只在跟踪级别查找问题。如果下游发生了错误，但被您的应用程序处理了而未返回给用户，则搜索 `error` 将找不到它。 要查找下游问题的跟踪，可以使用[复杂关键字](#console-filters-complex) `service()` 和 `edge()`。这些关键字允许您将筛选条件表达式应用于所有下游节点、单个下游节点或两个节点之间的边缘。要想获得更细的粒度，您可以使用 [id() 函数](#console-filters-functions)按类型筛选服务和边缘。 ## 布尔值关键字 布尔关键字值可为 true 或 false。使用这些关键字查找导致错误的跟踪。 **布尔值关键字** + `ok` - 响应状态代码为 2XX，成功。 + `error` - 响应状态代码为 4XX，客户端错误。 + `throttle` - 响应状态代码为“429 请求过多”。 + `fault` - 响应状态代码为 5XX，服务器错误。 + `partial` - 请求包含未完成的分段。 + `inferred` - 请求具有推断分段。 + `first` - 元素是枚举列表中的第一个元素。 + `last` - 元素是枚举列表中的最后一个元素。 + `remote` - 根本原因实体是远程的。 + `root` - 服务是跟踪的入口点或根分段。 布尔运算符查找指定键为 `true` 或 `false` 的分段。 **布尔运算符** + none - 如果关键字为 true，则表达式为 true。 + `!` - 如果关键字为 false，则表达式为 true。 + `=`、`!=` - 将关键字的值与字符串 `true` 或 `false` 进行比较。这些运算符与其他运算符的行为相同，但更加明确。 **Example - 响应状态为 2XX OK** ``` ok ``` **Example - 响应状态不为 2XX OK** ``` !ok ``` **Example - 响应状态不为 2XX OK** ``` ok = false ``` **Example - 上次枚举的错误跟踪具有错误名称“deserialize”** ``` rootcause.fault.entity { last and name = "deserialize" } ``` **Example - 包含远程分段的请求，其覆盖率大于 0.7 且服务名称为“traces”** ``` rootcause.responsetime.entity { remote and coverage > 0.7 and name = "traces" } ``` **Example - 具有推断分段（其中，服务类型为“AWS:DynamoDB”）的请求** ``` rootcause.fault.service { inferred and name = traces and type = "AWS::DynamoDB" } ``` **Example - 将名称为“data-plane”的分段用作根的请求** ``` service("data-plane") {root = true and fault = true} ``` ## 数字关键字 使用数字关键字可以搜索具有特定响应时间、持续时间或响应状态的请求。 **数字关键字** + `responsetime` - 服务器发送响应所用的时间。 + `duration` - 包括所有下游调用的请求总时长。 + `http.status` - 响应（状态代码）。 + `index` - 元素在枚举列表中的位置。 + `coverage` - 实体响应时间占根分段响应时间的小数百分比。仅适用于响应时间根本原因实体。 **数字运算符** 数字关键字使用标准相等运算符和比较运算符。 + `=`、`!=` - 关键字等于或不等于某个数值。 + `<`、`<=`、`>`、`>=` - 关键字小于或大于某个数值。 **Example - 响应状态不为 200 OK** ``` http.status != 200 ``` **Example - 总时长在 5-8 秒之间的请求** ``` duration >= 5 AND duration <= 8 ``` **Example - 在 3 秒内成功完成的请求，包括所有下游调用** ``` ok !partial duration <3 ``` **Example - 索引大于 5 的枚举列表实体** ``` rootcause.fault.service { index > 5 } ``` **Example - 其最后一个实体覆盖率大于 0.8 的请求** ``` rootcause.responsetime.entity { last and coverage > 0.8 } ``` ## 字符串关键字 使用字符串关键字查找请求标头中包含特定文本或特定用户的跟踪 IDs。 **字符串关键字** + `http.url` - 请求 URL。 + `http.method` - 请求方法。 + `http.useragent` - 请求的用户代理字符串。 + `http.clientip` - 请求者 IP 地址。 + `user` - 跟踪中任意分段的用户字段的值。 + `name` - 服务或异常的名称。 + `type` - 服务类型。 + `message` - 异常消息。 + `availabilityzone` - 跟踪中任意分段上可用区字段的值。 + `instance.id` - 跟踪中任意分段上的实例 ID 字段的值。 + `resource.arn` - 跟踪中任何分段上的资源 ARN 字段的值。 字符串运算符查找等于或包含特定文本的值。必须始终在引号中指定值。 **字符串运算符** + `=`、`!=` - 关键字等于或不等于某个数值。 + `CONTAINS` - 关键字包含特定字符串。 + `BEGINSWITH`、`ENDSWITH` - 关键字以特定字符串开头或结尾。 **Example - http.url 筛选器** ``` http.url CONTAINS "/api/game/" ``` 要测试跟踪中是否存在某个字段而不考虑其值，可检查它是否包含空字符串。 **Example - 用户筛选器** 与用户一起查找所有痕迹 IDs。 ``` user CONTAINS "" ``` **Example - 选择跟踪，跟踪所具有的故障根本原因包含名为“Auth”的服务** ``` rootcause.fault.service { name = "Auth" } ``` **Example - 选择跟踪，跟踪所具有的响应时间根本原因的最后一个服务的类型为 DynamoDB** ``` rootcause.responsetime.service { last and type = "AWS::DynamoDB" } ``` **Example - 选择跟踪，跟踪所具有的故障根本原因的最后一个异常具有消息“拒绝 account\$1id 访问：1234567890”** ``` rootcause.fault.exception { last and message = "Access Denied for account_id: 1234567890" ``` ## 复杂关键字 使用复杂关键字可根据服务名称、边缘节点名称或注释值查找请求。对于服务和边缘节点，您可以指定应用于服务或边缘节点的附加筛选条件表达式。对于注释，您可以使用布尔值、数字或字符串运算符筛选具有特定键的注释的值。 **复杂关键字** + `annotation[key]`-带字段的注释的值*key*。注释的值可以是布尔值、数字或字符串，因此您可以使用任意这些类型的比较运算符。此关键字可以与 `service` 或 `edge` 关键字组合使用。包含点（句点）的注释键必须用方括号（**[]**）括住。 + `edge(source, destination) {filter}`—服务*source*与之间的连接*destination*. 可选的大括号中可以包含应用于此连接上的分段的筛选条件表达式。 + `group.name / group.arn` — 组的筛选条件表达式的值，被组名称或组 ARN 所引用。 + `json` - JSON 根本原因对象。有关以编程方式创建 JSON 实体的步骤，请参阅[从 AWS X-Ray 获取数据](xray-api-gettingdata.md)。 + `service(name) {filter}`— 带有名称的服务*name*。可选的大括号中可以包含应用于服务所创建的分段的筛选条件表达式。 使用服务关键字查找命中跟踪地图上特定节点的请求的跟踪。 复杂关键字运算符可查找其中的指定键已经设置或未设置的分段。 **复杂关键字运算符** + none - 如果关键字已经设置，则表达式为 true。如果关键字为布尔类型，则其计算结果将为布尔值。 + `!` - 如果关键字未设置，则表达式为 true。如果关键字为布尔类型，则其计算结果将为布尔值。 + `=`、`!=` — 比较关键字的值。 + `edge(source, destination) {filter}`—服务*source*与之间的连接*destination*. 可选的大括号中可以包含应用于此连接上的分段的筛选条件表达式。 + `annotation[key]`-带字段的注释的值*key*。注释的值可以是布尔值、数字或字符串，因此您可以使用任意这些类型的比较运算符。此关键字可以与 `service` 或 `edge` 关键字组合使用。 + `json` - JSON 根本原因对象。有关以编程方式创建 JSON 实体的步骤，请参阅[从 AWS X-Ray 获取数据](xray-api-gettingdata.md)。 使用服务关键字查找命中跟踪地图上特定节点的请求的跟踪。 **Example - 服务筛选器** 包括对 `api.example.com` 调用的请求出错 (500 系列错误)。 ``` service("api.example.com") { fault } ``` 您可以排除服务名称，而将筛选条件表达式应用于服务地图上的所有节点。 **Example - 服务筛选器** 在跟踪地图上的任意位置导致故障的请求。 ``` service() { fault } ``` 边缘关键字将筛选条件表达式应用于两个节点之间的连接。 **Example - 边缘筛选器** 服务 `api.example.com` 对 `backend.example.com` 进行调用的请求因出现错误而失败。 ``` edge("api.example.com", "backend.example.com") { error } ``` 您也可以将 `!` 运算符与服务和边缘关键字结合使用来从另一个筛选条件表达式的结果中排除某个服务或边缘。 **Example - 服务和请求筛选器** 请求的 URL 以 `http://api.example.com/` 开头且包含 `/v2/`，但并未到达名为 `api.example.com` 的服务。 ``` http.url BEGINSWITH "http://api.example.com/" AND http.url CONTAINS "/v2/" AND !service("api.example.com") ``` **Example — 服务和响应时间筛选器** 查找已设置 `http url` 且呼应时间大于 2 秒的跟踪。 ``` http.url AND responseTime > 2 ``` 对于注释，您可以调用设置了 `annotation[key]` 的所有跟踪，或使用对应于值的类型的比较运算符。 **Example - 带字符串值的注释** 请求的注释名为 `gameid`，字符串值为 `"817DL6VO"`。 ``` annotation[gameid] = "817DL6VO" ``` **Example — 注释已设置** 带有名称设置为 `age` 的注释的请求。 ``` annotation[age] ``` **Example — 注释未设置** 不带有名称设置为 `age` 的注释的请求。 ``` !annotation[age] ``` **Example - 带数字值的注释** 请求的注释期限数值大于 29。 ``` annotation[age] > 29 ``` **Example — 注释与服务或边缘相结合** ``` service { annotation[request.id] = "917DL6VO" } ``` ``` edge { source.annotation[request.id] = "916DL6VO" } ``` ``` edge { destination.annotation[request.id] = "918DL6VO" } ``` **Example — 带有用户的组** 其的跟踪满足 `high_response_time` 组筛选条件（例如，`responseTime > 3`），且用户名为“Alice”的请求。 ``` group.name = "high_response_time" AND user = "alice" ``` **Example - 具有根本原因实体的 JSON** 具有匹配的根本原因实体的请求。 ``` rootcause.json = #[{ "Services": [ { "Name": "GetWeatherData", "EntityPath": [{ "Name": "GetWeatherData" }, { "Name": "get_temperature" } ] }, { "Name": "GetTemperature", "EntityPath": [ { "Name": "GetTemperature" } ] } ] }] ``` ## id 函数 当您为 `service` 或 `edge` 关键字提供服务名称时，您将得到具有该名称的所有节点的结果。要进行更精确的筛选，可以使用 `id` 函数在名称之外再指定一个服务类型，以区分同名节点。 在监控账户中查看多个账户中的跟踪时，使用 `account.id` 函数为服务指定一个具体账户。 ``` id(name: "service-name", type:"service::type", account.id:"account-ID") ``` 您可以在服务和边缘节点筛选条件中使用 `id` 函数来代替服务名称。 ``` service(id(name: "service-name", type:"service::type")) { filter } ``` ``` edge(id(name: "service-one", type:"service::type"), id(name: "service-two", type:"service::type")) { filter } ``` 例如， AWS Lambda 函数会在跟踪映射中生成两个节点；一个用于函数调用，另一个用于 Lambda 服务。两个节点的名称相同，但类型不同。标准服务筛选器将查找这两个节点的跟踪。 **Example - 服务筛选器** 在任何名为 `random-name`的服务上包含错误的请求。 ``` service("random-name") { error } ``` 使用 `id` 函数将搜索范围缩小到函数本身的错误，排除服务的错误。 **Example - 使用 id 函数的服务筛选器** 名为 `random-name`、类型为 `AWS::Lambda::Function` 的服务中有错误的请求。 ``` service(id(name: "random-name", type: "AWS::Lambda::Function")) { error } ``` 要按类型搜索节点，您还可以完全排除名称。 **Example — 具有 id 函数和服务类型的服务筛选器** 类型为 `AWS::Lambda::Function` 的服务中有错误的请求。 ``` service(id(type: "AWS::Lambda::Function")) { error } ``` 要搜索特定节点 AWS 账户，请指定账户 ID。 **Example - 具有 id 函数和账户 ID 的服务筛选器** 包含某个特定账户 ID `AWS::Lambda::Function` 中某项服务的请求。 ``` service(id(account.id: "account-id")) ``` # 跨账户跟踪 AWS X-Ray 支持*跨账户可观测性*，让您可以监控跨越一个AWS 区域内多个账户的应用程序并对其进行故障排除。您可以如同在一个账户中进行操作那样，无缝搜索、可视化和分析任何关联账户中的指标、日志和跟踪。这样可提供在多个账户之间移动的请求的完整视图。您可以在 [CloudWatch 控制台](https://console.aws.amazon.com/cloudwatch/)中的 X-Ray 跟踪地图和跟踪页面上查看跨账户跟踪。 共享的可观测性数据可以包括以下任意类型的遥测数据： + Amazon CloudWatch 中的指标 + 在 Amazon CloudWatch Logs 中记录组 + AWS X-Ray 中的跟踪记录 + Amazon CloudWatch Application Insights 中的应用程序 ## 配置跨账户可观测性 若要启用跨账户可观测性，请设置一个或多个 AWS *监控*账户，并将它们与多个*源*账户相关联。监控账户是一个中央 AWS 账户，可以查看源账户生成的可观测性数据并与之交互。源账户是一个单独的 AWS 账户，可为其包含的资源生成可观测性数据。 源账户与监控账户共享其可观测性数据。最多可将每个源账户中的跟踪复制到 5 个监控账户。将源账户中的跟踪副本到第一个监控账户免费。发送到更多监控账户的副本根据标准定价，向每个源账户收费。请参阅 [AWS X-Ray 定价](https://aws.amazon.com/xray/pricing/)和 [Amazon CloudWatch 定价](https://aws.amazon.com/cloudwatch/pricing/)，了解更多信息。 若要在监控账户和源账户之间创建关联，请使用 CloudWatch 控制台或 AWS CLI 中新推出的“可预测性访问管理器”命令以及 API。有关更多信息，请参阅 [CloudWatch 跨账户可观察性](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)。 **注意** X-Ray 跟踪对接收它们的 AWS 账户 收费。如果[采样的](xray-concepts.md#xray-concepts-sampling)请求跨超过一个 AWS 账户 的服务，则每个账户都会记录单独的跟踪，且所有跟踪共享同一跟踪 ID。请参阅 [AWS X-Ray 定价](https://aws.amazon.com/xray/pricing/)和 [Amazon CloudWatch 定价](https://aws.amazon.com/cloudwatch/pricing/)，了解有关跨账户可观测性定价的更多信息。 ## 查看跨账户跟踪 跨账户跟踪显示在监控账户中。每个源账户仅显示该特定账户的本地跟踪。以下各节假设您已登录监控账户并已打开 Amazon CloudWatch 控制台。在跟踪地图和跟踪页面上，监控账户徽章都显示在右上角。 ![\[监控账户徽章\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/crossaccount-monitoring-account.png) ### 跟踪地图 在 CloudWatch 控制台中左侧导航窗格的 **X-Ray 跟踪**下，选择**跟踪地图**。默认情况下，跟踪地图显示将跟踪发送到监控账户的所有源账户的节点，以及监控账户本身的节点。在跟踪地图上，选择左上角的**筛选条件**，使用**账户**下拉列表筛选跟踪地图。应用账户筛选条件后，与当前筛选条件不匹配的账户的服务节点将显示为灰色。 ![\[筛选后的跟踪地图\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/crossaccount-servicemap-account-filter.png) 选择服务节点时，节点详细信息窗格将包含该服务的账户 ID 和标签。 ![\[节点详细信息窗格\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/crossaccount-servicemap-node-detail.png) 在跟踪地图的右上角，选择**列表视图**以查看服务节点列表。服务节点列表包括来自监控账户的服务以及所有已配置的源帐户。从**节点**筛选条件中进行选择，按 **Account label** 或 **Account id** 筛选节点列表。 ![\[筛选后的服务列表\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/crossaccount-servicelist-account-filter.png) ### 跟踪 从监控账户打开 CloudWatch 控制台，并在左侧导航窗格中的 **X-Ray 跟踪**下选择**跟踪**，即可查看跨多个账户的跟踪的详细信息。也可以通过在 X-Ray **跟踪地图**中选择一个节点，然后从节点详细信息窗格中选择**查看跟踪**来打开此页面。 **跟踪**页面支持按账户 ID 进行查询。首先，请[输入](xray-console-filters.md)包含一个或多个账户 ID 的查询。以下示例查询通过账户 ID X* *或 *Y* 的跟踪： ``` service(id(account.id:"X")) OR service(id(account.id:"Y")) ``` ![\[按账户查询跟踪\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/crossaccount-traces-query-by-account.png) 按**账户**优化查询。从列表中选择一个或多个账户，然后选择**添加到查询**。 ![\[按账户优化跟踪查询\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/crossaccount-traces-refine-by-account.png) ### 跟踪详情 从**跟踪**页面底部的**跟踪**列表中选择相应跟踪，可查看该跟踪的详细信息。会显示**跟踪详情**，其中包括一张跟踪详情地图，其中包含相应跟踪通过的所有账户中的服务节点。选择某个具体的服务节点查看其相应的账户。 **分段时间线**一节按照时间线显示每个分段的账户详细信息。 ![\[分段时间线\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/crossaccount-traces-segment-timeline.png) # 跟踪事件驱动型应用程序 AWS X-Ray 支持跟踪使用 Amazon SQS 和 AWS Lambda 的事件驱动型应用程序。使用 CloudWatch 控制台查看使用 Amazon SQS 排队并由一个或多个 Lambda 函数处理的每个请求的互联视图。上游消息创建者的跟踪会自动链接到下游 Lambda 使用器节点的跟踪，从而创建应用程序的端到端视图。 **注意** 每个跟踪分段最多可以链接到 20 个跟踪，每个跟踪最多可包含 100 个链接。某些情况下，链接更多跟踪可能会导致超出[最大的跟踪文档大小](https://docs.aws.amazon.com/general/latest/gr/xray.html#limits_xray)，可能会造成跟踪不完整。例如，当启用了跟踪的 Lambda 函数在一次调用中将许多 SQS 消息发送到一个队列会发生这种情况。如果您遇到此问题，可以使用 X-Ray SDK 作为缓解措施。有关更多信息，请参阅适用于 [Java](https://github.com/aws/aws-xray-sdk-java#oversampling-mitigation)、[Node.js](https://github.com/aws/aws-xray-sdk-node/tree/master/packages/core#oversampling-mitigation)、[Python](https://github.com/aws/aws-xray-sdk-python#oversampling-mitigation)、[Go](https://github.com/aws/aws-xray-sdk-go#oversampling-mitigation) 或 [.NET](https://github.com/aws/aws-xray-sdk-dotnet#oversampling-mitigation) 的 X-Ray SDK。 ## 在跟踪地图中查看链接的跟踪 使用 [CloudWatch 控制台](https://console.aws.amazon.com/cloudwatch/)内的**跟踪地图**页面查看跟踪地图，其中包含链接到 Lambda 使用者的跟踪的消息创建者的跟踪。这些链接以虚线边缘显示，连接到 Amazon SQS 节点和下游 Lambda 使用器节点。 ![\[Amazon SQS 和 Lambda 节点之间的边缘。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-batch-servicemap-linkededge.png) 选择虚线边缘以显示*收到的事件期限*直方图，图中显示了使用器收到时事件年限的分布情况。每次收到事件时都会计算期限。 ![\[带有收到的事件期限直方图的边缘。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-servicemap-linkededgedetails-cw.png) ## 查看链接的跟踪详情 **查看消息创建者、Amazon SQS 队列或 Lambda 使用器发送的跟踪详情：** 1. 使用**跟踪地图**选择消息创建者、Amazon SQS 或 Lambda 使用者节点。 1. 从节点详情中选择**查看跟踪**以显示跟踪列表。您也可以直接导航到 CloudWatch 控制台中的**跟踪**页面。 1. 从列表中选择特定跟踪以打开跟踪详情页面。跟踪详情页面显示所选跟踪是链接的跟踪集合的一部分时的消息。 ![\[链接的跟踪详情\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-batch-tracedetails-header.png) 跟踪详情地图显示当前跟踪以及上下游链接的跟踪，其中每个跟踪都包含在指示每个跟踪边界的框中。如果当前选择的跟踪链接到多个上游或下游跟踪，则上游或下游链接的跟踪的节点会堆叠在一起，并会显示**选择跟踪**按钮。 ![\[多个链接的上游跟踪\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-batch-tracedetails-tracemap.png) 在跟踪详情地图下方显示跟踪分段的时间表，其中包含上下游链接的跟踪。如果有多个上游或下游链接的中，则不会显示它们的分段详情。若要查看链接的跟踪集合中某一个跟踪的分段详情，[选择单一跟踪](#xray-tracelinking-filterbatch)，如下所述。 ![\[显示链接的跟踪的分段时间表\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-batch-tracedetails-timeline.png) ## 选择链接的跟踪集合中的某一个跟踪 **将链接的跟踪集合筛选到只有一个跟踪，以时间表的形式查看分段详情。** 1. 在跟踪详情地图中链接的跟踪下方，选择**选择跟踪**。将会显示跟踪列表。 ![\[链接的跟踪列表\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-batch-tracedetails-tracelist.png) 1. 选中跟踪旁边的单选按钮，在跟踪详情地图里查看它。 1. 选择**取消跟踪选择**以查看链接的跟踪的整个集合。 ![\[单个链接的跟踪\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-batch-tracedetails-filteredbatch.png) # 使用延迟直方图 当您在 AWS X-Ray [跟踪地图](xray-console-servicemap.md)上选择一个节点或边缘时，X-Ray 控制台会显示一个延迟分布直方图。 ## 延迟 延迟是指请求从开始到完成所用的时间。直方图显示延迟分布。它的 x 轴显示持续时间，y 轴显示与每个持续时间匹配的请求百分比。 该直方图显示服务在不到 300 ms 的时间内完成大多数请求。一小部分请求用时多达 2 秒，而一些异常项用了更多时间。 ![\[延迟直方图，其中 x 轴显示持续时间，y 轴显示对应每个持续时间的请求百分比\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/scorekeep-servicemap-histogram.png) ## 解释服务详细信息 服务直方图和边缘直方图提供了从服务或请求者角度看的延迟的可视化表示形式。 + 通过单击圆圈选择*服务节点*。X-Ray 显示服务所完成的请求的直方图。延迟是服务记录的延迟，不包括服务和请求者之间的任何网络延迟。 + 通过单击两个服务之间边缘的线条或箭头尖端来选择*边缘*。X-Ray 显示来自请求者的、由下游服务所完成的请求的直方图。延迟是服务记录的延迟，且包括两个服务之间的网络连接延迟。 要解释**服务详细信息**面板直方图，您可以查找偏离直方图中大多数值最大的值。可以将这些*异常值* 视为直方图中的高峰或峰值，并且您可以查看特定区域的跟踪以调查发生了什么情况。 要查看按延迟筛选的跟踪，请在直方图上选择一个范围。单击要开始选择的位置，然后从左向右拖动，突出显示一个要包括在跟踪筛选条件中的延迟范围。 ![\[选择一个范围来查看跟踪，方法是单击要开始的位置，然后从向左向右拖动，画出跟踪筛选器的范围\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-selection.png) 选择范围后，您可以选择 **Zoom**，只查看该部分的直方图并细化您的选择。 ![\[选择 Zoom 以查看直方图中的选定范围\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-zoom.png) 将焦点设置为感兴趣的区域后，选择 **View traces**。 # 使用 X-Ray 见解 AWS X-Ray 会持续分析您账户中的跟踪数据，以识别应用程序中出现的紧急问题。当错误率超出预期范围时，它会创建*见解*来记录问题并跟踪问题产生的影响，直到问题被解决。借助见解，您可以： + 确定应用程序哪里出现了问题，问题的根本原因，以及关联的影响。您可以从见解提供的影响分析中获取到某个问题的严重性和优先级。 + 随着时间推移，当问题发生变化时收到通知。见解通知可以与使用 Amazon EventBridge 的监控和警报解决方案相集成。这种集成让您可以根据问题的严重性发送自动化电子邮件或警报。 X-Ray 控制台可识别跟踪地图中正在发生事件的节点。若要查看见解摘要，请选择受影响的节点。还可以从左侧导航窗格中选择**见解**，查看和筛选见解。 ![\[带有见解摘要的跟踪地图节点。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-insights-servicemap.png) 当 X-Ray 在服务地图的一个或多个节点中检测到*异常*时，便会创建见解。该服务使用统计建模来预测应用程序中服务的预期故障率。前述示例中存在的异常为 AWS Elastic Beanstalk 中的故障数量增多。Elastic Beanstalk 服务器经历了多次 API 调用超时，导致下游节点出现异常。 ## 在 X-Ray 控制台中启用见解 必须为希望使用见解功能的每个组都启用见解。可以从**组**页面启用见解。 1. 打开 [X-Ray 控制台](https://console.aws.amazon.com/xray/home#)。 1. 选择现有组或通过选择**创建组**创建一个新组，然后选择**启用见解**。有关如何在 X-Ray 控制台中配置组的更多信息，请参阅[配置组](xray-console-groups.md)。 1. 在左侧导航窗格中选择**见解**，然后选择要查看的见解。 ![\[X-Ray 控制台中的见解列表。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-insights.png) **注意** X-Ray 使用 GetInsightSummarts、GetInsightEvents 和 GetInsightImpactGraph API 操作从见解中检索数据。 有关更多信息，请参阅 [如何 AWS X-Ray 与 IAM 配合使用](security_iam_service-with-iam.md)。 ## 启用见解通知 可以使用见解通知为每个见解事件创建一则通知，例如，当创建见解、发生重大更改，或关闭见解时。客户可以通过 Amazon EventBridge 接收此类通知，并使用条件规则采取行动，例如 SNS 通知、Lambda 调用、将消息发布到 SQS 队列，或任意的目标 EventBridge 支持。我们会尽可能发送见解通知，但并不保证。有关目标的更多信息，请参阅 [Amazon EventBridge 目标](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-targets.html)。 您可以从**组**页面为任意已启用见解的组启用见解通知。 **为 X-Ray 组启用通知** 1. 打开 [X-Ray 控制台](https://console.aws.amazon.com/xray/home#)。 1. 选择现有组或通过选择**创建组**创建一个新组，确保选中**启用见解**，然后选择**启用通知**。有关如何在 X-Ray 控制台中配置组的更多信息，请参阅[配置组](xray-console-groups.md)。 **配置 Amazon EventBridge 条件规则** 1. 打开 [Amazon EventBridge 控制台](https://console.aws.amazon.com/events/home)。 1. 导航到左侧导航栏中的**规则**，然后选择**创建规则**。 1. 提供规则的名称和描述。 1. 选择**事件模式**，然后选择**自定义模式**。提供一个包含 `"source": [ "aws.xray" ]` 和 `"detail-type": [ "AWS X-Ray Insight Update" ]` 的模式。以下是可能的一些示例模式。 + 事件模式要匹配 X-Ray 见解中的所有传入事件： ``` { "source": [ "aws.xray" ], "detail-type": [ "AWS X-Ray Insight Update" ] } ``` + 事件模式要匹配指定的 **state** 和 **category**： ``` { "source": [ "aws.xray" ], "detail-type": [ "AWS X-Ray Insight Update" ], "detail": { "State": [ "ACTIVE" ], "Category": [ "FAULT" ] } } ``` 1. 选择并配置当某个事件匹配此规则时，您想要调用的目标。 1. （可选）提供标签以便更轻松地识别和选择此规则。 1. 选择**创建**。 **注意** X-Ray 见解通知将事件发送到 Amazon EventBridge，后者暂不支持客户托管密钥。有关更多信息，请参阅 [AWS X-Ray 中的数据保护](xray-console-encryption.md)。 ## 见解 见解概述页面试图回答以下三个关键问题： + 什么是潜在问题？ + 什么是根本原因？ + 什么是影响？ **异常服务**一节介绍了每个服务的时间表，展示了事件过程中故障率的变化情况。时间表显示了出现故障的跟踪数量，根据记录的流量，以实心条带指明预计的故障数量。*事件窗口*将见解的持续时间可视化。当 X-Ray 观察到指标出现异常并且启用见解后依旧存在的时候，事件窗口启动。 以下示例显示的是导致某个事件的故障出现增加： ![\[X-Ray 见解的概述页面。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-insights-overview.png) **根本原因**一节显示了聚焦根本原因服务和受影响路径的跟踪地图。可以选择根本原因地图右上角的眼睛图标，以隐藏未受影响的节点。根本原因服务是 X-Ray 识别到异常的最远的下游节点。它可以代表您检测的某项服务，或是您服务使用检测客户端调用过的外部服务。例如，如果您调用带有检测的 AWS SDK 客户端的 Amazon DynamoDB，DynamoDB 中的故障数量会增强，从而导致将 DynamoDB 作为根本原因的见解。 若要进一步调查根本原因，请在根本原因图上选择**查看根本原因详情**。您可以使用**分析**页面来调查根本原因以及相关消息。有关更多信息，请参阅 [与 Analytics 控制台交互](xray-console-analytics.md)。 ![\[X-Ray 见解的概述页面。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-insights-root-cause.png) 在地图中继续上游的故障会影响多个节点，并会导致多种异常。如果某个故障一直传回到发出请求的用户，就会出现*客户端故障*。这是跟踪地图的根节点的一个故障。**影响**示意图为整个组的客户端体验提供了时间表。根据以下状态的比例来计算此体验：**故障**、**错误**、**瓶颈**和**没错**。 ![\[X-Ray 事件的影响图。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-insights-impact.png) 此示例显示在事件发生过程中，在顶部节点带有故障的跟踪增加了。下游服务中的事件并不总是与客户端错误的增加相对应。 选择**分析见解**会在窗口中打开 X-Ray Analytics 控制台，您可以在其中深入研究产生见解的跟踪集。有关更多信息，请参阅 [与 Analytics 控制台交互](xray-console-analytics.md)。 **了解影响** AWS X-Ray 会衡量某个持续问题造成的影响，并作为一部分生成见解和通知。有两种方法来衡量影响： + 对 X-Ray [组](xray-console-groups.md)的影响 + 对根本原因服务的影响 此影响由在给定时间内发生故障或造成错误的请求比例决定。通过这种影响分析，您可以根据自己的特定情况得出问题的严重性和优先级。除了见解通知以外，影响还是控制台体验的一部分。 **重复数据删除** AWS X-Ray 见解会重复去除多个微服务中存在的重复问题。它使用异常检测来确定是某个问题根本原因的服务，确定其他相关服务是否由于同一根本原因展现出异常行为，并将结果记录为单个见解。 ## 查看见解的进展 X-Ray 会定期重新评估见解直到问题得到解决，并将每个显著的中间变化记录为[通知](#xray-console-insight-notifications)，可以作为 Amazon EventBridge 事件发送。这让您能够构建流程和工作流以确定问题随时间推移如何变化，并采取适当操作，例如发送电子邮件，或与使用 EventBridge 的警报系统相集成。 您可以在**影响**页面上的**影响时间表**中查看事件活动。默认情况下，时间表会显示最受影响的服务，直到您选择另一项服务。 ![\[检查包含影响时间表的页面。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-insights-inspect.png) 要查看某个事件的跟踪地图和示意图，请从影响时间表中选择该事件。跟踪地图显示应用程序中受事件影响的服务。在“**影响分析**”下，图表显示选定节点和组中客户端的故障时间表。 ![\[X-Ray 见解的影响分析图。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/console-insights-inspect-analysis.png) 若要更加深入地了解某个事件中涉及的跟踪，请在**检查**页面上选择**分析事件**。可以使用**分析**页面来优化跟踪列表并确定受影响的用户。有关更多信息，请参阅 [与 Analytics 控制台交互](xray-console-analytics.md)。 # 与 Analytics 控制台交互 AWS X-Ray Analytics 控制台是一个交互式工具，用于解释跟踪数据，以快速了解您的应用程序及其底层服务的运行情况。借助该控制台，您可以通过交互式响应时间图表和时间序列图表探索、分析和直观地显示跟踪。 当在 Analytics 控制台中进行选择时，控制台构造筛选条件以反映所有跟踪的所选子集。您可以通过单击与当前跟踪集关联的指标和字段的图表和面板，使用越来越精细的筛选条件细化活动的数据集。 **Topics** + [控制台功能](#xray-console-analytics-features) + [响应时间分配](#xray-console-analytics-response) + [时间序列活动](#xray-console-analytics-time) + [工作流程示例](#xray-console-analytics-workflows) + [在服务图表上观察故障](#xray-console-analytics-observe-faults) + [确定高峰响应时间](#xray-console-analytics-response-peaks) + [查看所有标有状态代码的跟踪](#xray-console-analytics-response-peaks) + [查看子组中与用户关联的所有项目](#xray-console-analytics-subgroups) + [比较具有不同标准的两组跟踪](#xray-console-analytics-compare) + [确定感兴趣的跟踪并查看其详细信息](#xray-console-analytics-identify) ## 控制台功能 X-Ray Analytics 使用以下关键功能对跟踪数据进行分组、筛选、比较和量化。 ### 特征 | 特征 | 描述 | | --- | --- | | **组** | 初始选定的组为 `Default`。要更改检索的组，请从主要筛选表达式搜索栏右侧的菜单中选择不同的组。要了解有关组的更多信息，请参阅[将筛选表达式与组结合使用](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-filters.html#groups)。 | | **已检索跟踪** | 默认情况下，Analytics 控制台根据所选组中的所有跟踪生成图表。检索的跟踪表示您工作集中的所有跟踪。您可以在此平铺中找到跟踪计数。您应用于主搜索栏的筛选表达式可以细化和更新检索的跟踪。 | | **显示在图表中/从图表中隐藏** | 一个开关，用于对照检索的跟踪比较活动的组。要对照任何活动的筛选条件比较与组相关的数据，请选择**显示在图表中**。要从图表中删除此视图，请选择**从图表中隐藏**。 | | **已筛选跟踪集 A** | 通过与图表和表进行交互，应用筛选条件来创建**筛选跟踪集 A** 的条件。应用筛选条件后，可以在此平铺内计算适用跟踪的数量以及跟踪占所检索总数的百分比。筛选条件作为标签填充到**筛选跟踪集 A** 磁贴中，也可以将其从此磁贴中删除。 | | **细化** | 此函数根据应用到跟踪集 A 的筛选条件更新已检索的跟踪集。细化已检索的跟踪集会根据跟踪集 A 的筛选条件刷新所有已检索的跟踪的工作集。已检索的跟踪的工作集是组中所有跟踪的采样子集。 | | **筛选跟踪集 B** | 创建后，**筛选跟踪集 B** 是**筛选跟踪集 A** 的副本。若要比较这两个跟踪集，请选择将会应用于跟踪集 B 的筛选，而跟踪集 A 则保持不变。应用筛选条件后，可以在此平铺内计算适用跟踪的数量以及跟踪占所检索总数的百分比。筛选条件作为标签填充到**已筛选跟踪集 B** 磁贴中，也可以将其从此磁贴中删除。 | | **响应时间根本原因实体路径** | 记录的实体路径表。X-Ray 确定跟踪中的哪个路径是响应时间的最可能原因。格式指示所遇到的实体的层次结构，结尾是响应时间根本原因。使用这些行来筛选周期性的响应时间故障。有关通过 API 自定义根本原因筛选条件和获取数据的更多信息，请参阅[检索和细化根本原因分析](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-gettingdata.html#xray-api-analytics)。 | | **增量 (**�**)** | 在跟踪集 A 和 B 都处于活动状态时添加到指标表中的列。增量列计算跟踪集 A 和跟踪集 B 之间的跟踪百分比差异。 | ## 响应时间分配 X-Ray Analytics 控制台生成两个主要图表以帮助您直观显示跟踪：**响应时间分配**和**时间序列活动**。本节和下面的内容提供有关每个图表的示例，并说明有关如何阅读这些图表的基本知识。 以下是与响应时间线状图关联的颜色（时间序列图使用相同的颜色方案）： + **组中的所有跟踪** - 灰色 + **已检索跟踪** - 橙色 + **已筛选跟踪集 A** - 绿色 + **已筛选跟踪集 B** - 蓝色 **Example - 响应时间分配** 响应时间分配是一个图表，用于显示给定响应时间内的跟踪数量。单击并拖动以在响应时间分配内进行选择。这会针对特定响应时间内的所有跟踪的工作跟踪集，选择和创建一个名为 `responseTime` 的筛选条件。 ![\[显示跟踪响应时间分布的图表。\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/analytics-responseTime.png) ## 时间序列活动 时间序列活动图表显示给定时间段的跟踪数量。颜色指示反映响应时间分配的线图颜色。活动序列中的颜色块越深越饱满，则表示给定时间的跟踪数越多。 **Example - 时间序列活动** 单击并拖动以在时间序列活动图表内进行选择。这会针对特定时间范围内的所有跟踪的工作跟踪集，选择和创建一个名为 `timerange` 的筛选条件。 ![\[进行选择并创建筛选条件\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/analytics-timeSeries.png) ## 工作流程示例 下面的示例说明 X-Ray Analytics 控制台的常见使用案例。每个示例演示控制台体验的一个关键功能。这些示例作为一个组遵循基本的疑难排查工作流。这些步骤介绍了如何先发现运行状况不佳的节点，以及如何与 Analytics 控制台交互以自动生成比较查询。通过查询缩小范围后，您就可以查看感兴趣的跟踪的详细信息，以确定是什么问题影响了服务的健康运行。 ## 在服务图表上观察故障 跟踪地图根据成功调用与错误和故障的比率为每个节点配置颜色，从而指示这些节点的运行状况。当您在节点上看到红色百分比时，这指示一个故障。使用 X-Ray Analytics 控制台调查此故障。 有关如何解读跟踪地图的更多信息，请参阅[查看跟踪地图](https://docs.aws.amazon.com/xray/latest/devguide/xray-console.html#xray-console-servicemap)。 ![\[观察故障\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-2021.png) ## 确定高峰响应时间 使用响应时间分配，您可以观察高峰响应时间。通过选择高峰响应时间，图表下方的各个表格将会更新，以显示所有关联的指标，如状态代码。 您可以通过单击并拖动 X-Ray 来选择和创建筛选条件。筛选条件会以灰色阴影的形式显示在线状图顶部。现在，您可以沿着分配左右拖动阴影区以更新您的选择和筛选条件。 ![\[进行选择并创建筛选条件\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/analytics-showFilterf.png) ## 查看所有标有状态代码的跟踪 您可以使用图表下方的指标表钻取所选峰值内的跟踪。通过单击**HTTP 状态代码**表中的行，您可以自动对工作数据集创建筛选条件。例如，您可以查看状态代码为 500 的所有跟踪。这会在跟踪集平铺中创建一个名为 `http.status` 的筛选条件标签。 ## 查看子组中与用户关联的所有项目 根据用户、URL、响应时间根本原因或其他预定义的属性钻取错误集。例如，要额外筛选状态代码为 500 的跟踪集，请从 **USERS** 表中选择一行。这会导致在跟踪集平铺中产生两个筛选条件标签：`http.status`（如前面指定）和 `user`。 ## 比较具有不同标准的两组跟踪 跨不同用户及其 POST 请求进行比较，以查找其他差异和关联。应用您的第一个筛选条件集。它们通过响应时间分配中的蓝线定义。然后，选择**比较**。最初，这会对跟踪集 A 创建筛选器的副本。 要继续，请定义要应用于跟踪集 B 的新的筛选条件集。这第二个集合由绿线表示。以下示例根据蓝色和绿色颜色方案显示不同的行。 ![\[线图比较\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/analytics-compareLines.png) ## 确定感兴趣的跟踪并查看其详细信息 当您使用控制台筛选条件缩小范围时，指标表下方的跟踪列表将变得更有意义。跟踪列表将有关 **URL**、**用户**和**状态代码**的信息合并显示在一个视图中。如需更多见解，请从此表中选择一行，以打开跟踪的详细信息页面并查看其时间线和原始数据。 # 配置组 组是由筛选条件表达式定义的跟踪的集合。您可以使用组生成其他服务图并提供 Amazon CloudWatch 指标。您可以使用 AWS X-Ray 控制台或 X-Ray API 为服务创建组并进行管理。本主题介绍如何使用 X-Ray 控制台来创建和管理组。请参阅[组](xray-api-configuration.md#xray-api-configuration-groups)，了解如何使用 X-Ray API 管理组。 您可以为跟踪地图、跟踪或分析创建跟踪组。创建组后，该组会在以下全部三个页面上的组下拉菜单中变为一个可用的筛选条件：**跟踪地图**、**跟踪**和**分析**。 ![\[组菜单\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-menu.png) 组由其名称或 Amazon 资源名称（ARN）标识，并包含筛选条件表达式。此服务将比较传入到表达式的跟踪并相应地存储它们。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。 更新组的筛选条件表达式不会更改已记录的数据。更新仅应用于后续跟踪。这可能会生成新旧表达式的合并图。为避免发生这种情况，请删除当前群组并创建一个新的组。 **注意** 群组按检索到的符合筛选条件表达式的追踪数量计费。有关更多信息，请参阅[AWS X-Ray定价](https://aws.amazon.com/xray/pricing/)。 **Topics** + [创建组](#xray-console-group-create-console) + [应用组](#xray-console-group-apply) + [编辑组](#xray-console-group-edit) + [克隆组](#xray-console-group-clone) + [删除组](#xray-console-group-delete) + [在 Amazon CloudWatch 中查看组指标](#xray-console-group-cloudwatch) ## 创建组 **注意** 现在，您可以在 Amazon CloudWatch 控制台中配置 X-Ray 组。也可以继续使用 X-Ray 控制台。 ------ #### [ CloudWatch console ] 1. 登录 AWS 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）。 1. 在左侧导航窗格中，选择**设置**。 1. 在 **X-Ray 跟踪**部分中的**组**下，选择**查看设置**。 1. 在组列表上，选择**创建组**。 1. 在**创建组**页面上，输入组的名称。组名称最多可包含 32 个字符，可包含字母数字字符和破折号。组名称区分大小写。 1. 输入筛选条件表达式。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。在以下示例中，组筛选服务 `api.example.com` 中的错误跟踪以及发送到该服务的请求，其中呼应时间大于或等于 5 秒的情况。 ``` fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5 ``` 1. 在**见解**中，启用或禁用组的见解访问。有关见解的更多信息，请参阅 [使用 X-Ray 见解](xray-console-insights.md)。 ![\[“组”页面上的“见解”复选框\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-insights-cw.png) 1. 在**标签**中，选择**添加新标签**以输入标签键，以及选填的标签值。根据需要继续添加其他标签。标签键必须是唯一的。要删除标签，请选择每个标签下方的**删除**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-tags-cw.png) 1. 选择**创建群组**。 ------ #### [ X-Ray console ] 1. 登录到 AWS 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)。 1. 在左侧导航窗格中的**组**页面中，或是从以下任意页面中的组菜单中，打开**创建组**页面：**跟踪地图**、**跟踪**和**分析**。 1. 在**创建组**页面上，输入组的名称。组名称最多可包含 32 个字符，可包含字母数字字符和破折号。组名称区分大小写。 1. 输入筛选条件表达式。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。在以下示例中，组筛选服务 `api.example.com` 中的错误跟踪以及发送到该服务的请求，其中呼应时间大于或等于 5 秒的情况。 ``` fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5 ``` 1. 在**见解**中，启用或禁用组的见解访问。有关见解的更多信息，请参阅 [使用 X-Ray 见解](xray-console-insights.md)。 ![\[“组”页面上的“见解”复选框\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-insights.png) 1. 在**标签**中，输入一个标签键和可选的标签值。添加标签时会出现一个新行，供您添加另一个标签。标签键必须是唯一的。若要删除标签，请选择标签行末的 **X**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-tags.png) 1. 选择**创建群组**。 ------ ## 应用组 ------ #### [ CloudWatch console ] 1. 登录 AWS 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）。 1. 从 **X-Ray 跟踪**下的导航窗格中打开以下任意一个页面： + **跟踪地图** + **跟踪** 1. 在**按 X-Ray 组筛选**筛选条件中输入组名称。页面上显示的数据会发生变化，以匹配组中设置的筛选条件表达式。 ------ #### [ X-Ray console ] 1. 登录到 AWS 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)。 1. 从导航窗格中打开以下任意一个页面： + **跟踪地图** + **跟踪** + **Analytics** 1. 在组菜单中，选择在 [创建组](#xray-console-group-create-console) 中创建的组。页面上显示的数据会发生变化，以匹配组中设置的筛选条件表达式。 ------ ## 编辑组 ------ #### [ CloudWatch console ] 1. 登录 AWS 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）。 1. 在左侧导航窗格中，选择**设置**。 1. 在 **X-Ray 跟踪**部分中的**组**下，选择**查看设置**。 1. 从**组**部分中选择一个组，然后选择**编辑**。 1. 尽管您无法重命名组，但可以更新筛选条件表达式。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。在以下示例中，组筛选服务 `api.example.com` 中的错误跟踪，其中请求 URL 地址包含 `example/game`，以及呼应时间大于或等于 5 秒的情况。 ``` fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5 ``` 1. 在**见解**中，启用或禁用组的见解访问。有关见解的更多信息，请参阅 [使用 X-Ray 见解](xray-console-insights.md)。 ![\[“组”页面上的“见解”复选框\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-insights-cw.png) 1. 在**标签**中，选择**添加新标签**以输入标签键，以及选填的标签值。根据需要继续添加其他标签。标签键必须是唯一的。要删除标签，请选择每个标签下方的**删除**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-tags-cw.png) 1. 更新完组后，选择**更新组**。 ------ #### [ X-Ray console ] 1. 登录到 AWS 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)。 1. 执行以下其中一个操作以打开**编辑组**页面。 1. 在**群**页面上，选择某个组的名称进行编辑。 1. 在以下任意页面之一上的组菜单上，指向某个组，然后选择**编辑**。 + **跟踪地图** + **跟踪** + **Analytics** 1. 尽管您无法重命名组，但可以更新筛选条件表达式。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。在以下示例中，组筛选服务 `api.example.com` 中的错误跟踪，其中请求 URL 地址包含 `example/game`，以及呼应时间大于或等于 5 秒的情况。 ``` fault = true AND http.url CONTAINS "example/game" AND responsetime >= 5 ``` 1. 在**见解**中，启用或禁用组的见解和见解通知。有关见解的更多信息，请参阅 [使用 X-Ray 见解](xray-console-insights.md)。 ![\[“组”页面上的“见解”复选框\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-insights.png) 1. 在**标签**中，编辑标签键和值。标签键必须是唯一的。标签值是选填，如果需要可以删除。若要删除标签，请选择标签行末的 **X**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/group-tags.png) 1. 更新完组后，选择**更新组**。 ------ ## 克隆组 克隆组会创建具有现有组的筛选条件表达式和标签的新组。克隆组时，新组具有被克隆组的同一名称，名称后附加 `-clone`。 ------ #### [ CloudWatch console ] 1. 登录 AWS 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）。 1. 在左侧导航窗格中，选择**设置**。 1. 在 **X-Ray 跟踪**部分中的**组**下，选择**查看设置**。 1. 从**组**部分中选择一个组，然后选择**克隆**。 1. 在**创建组**页面上，组的名称为 *group-name*`-clone`。（可选）输入组的新名称。组名称最多可包含 32 个字符，可包含字母数字字符和破折号。组名称区分大小写。 1. 您可以保留现有组中的筛选条件表达式，也可以选择输入新的筛选条件表达式。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。在以下示例中，组筛选服务 `api.example.com` 中的错误跟踪以及发送到该服务的请求，其中呼应时间大于或等于 5 秒的情况。 ``` service("api.example.com") { fault = true OR responsetime >= 5 } ``` 1. 如果需要，可在**标签**中编辑标签键和值。标签键必须是唯一的。标签值是选填，如果需要可以删除。若要删除标签，请选择标签行末的 **X**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 1. 选择**创建群组**。 ------ #### [ X-Ray console ] 1. 登录到 AWS 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)。 1. 从左侧导航窗格中打开**组**页面，然后选择想要克隆的组的名称。 1. 从**操作**菜单中选择**克隆组**。 1. 在**创建组**页面上，组的名称为 *group-name*`-clone`。（可选）输入组的新名称。组名称最多可包含 32 个字符，可包含字母数字字符和破折号。组名称区分大小写。 1. 您可以保留现有组中的筛选条件表达式，也可以选择输入新的筛选条件表达式。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。在以下示例中，组筛选服务 `api.example.com` 中的错误跟踪以及发送到该服务的请求，其中呼应时间大于或等于 5 秒的情况。 ``` service("api.example.com") { fault = true OR responsetime >= 5 } ``` 1. 如果需要，可在**标签**中编辑标签键和值。标签键必须是唯一的。标签值是选填，如果需要可以删除。若要删除标签，请选择标签行末的 **X**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 1. 选择**创建群组**。 ------ ## 删除组 按照本节中的步骤删除组。您不能删除**默认**组。 ------ #### [ CloudWatch console ] 1. 登录 AWS 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）。 1. 在左侧导航窗格中，选择**设置**。 1. 在 **X-Ray 跟踪**部分中的**组**下，选择**查看设置**。 1. 从**组**部分中选择一个组，然后选择**删除**。 1. 请在提示您进行确认时选择**删除**。 ------ #### [ X-Ray console ] 1. 登录到 AWS 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)。 1. 从左侧导航窗格中打开**组**页面，然后选择想要删除的组的名称。 1. 在**操作**菜单上，选择**删除组**。 1. 请在提示您进行确认时选择**删除**。 ------ ## 在 Amazon CloudWatch 中查看组指标 创建组后，将根据组的筛选条件表达式检查传入跟踪，因为它们存储在 X-Ray 服务中。匹配每个标准的跟踪数量的指标每分钟都会发布到 Amazon CloudWatch。在**编辑组**页面上选择**查看指标**以打开 CloudWatch 控制台，转到**指标**页面。有关如何使用 CloudWatch 指标的更多信息，请参阅 *Amazon CloudWatch 用户指南* 中的[使用 Amazon CloudWatch 指标](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)。 ------ #### [ CloudWatch console ] 1. 登录 AWS 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)）。 1. 在左侧导航窗格中，选择**设置**。 1. 在 **X-Ray 跟踪**部分中的**组**下，选择**查看设置**。 1. 从**组**部分中选择一个组，然后选择**编辑**。 1. 在**编辑组**页面上，选择**查看指标**。 此操作在新选项卡中打开 CloudWatch 控制台**指标**页面。 ------ #### [ X-Ray console ] 1. 登录到 AWS 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.aws.amazon.com/xray/home)。 1. 从左侧导航窗格中打开**组**页面，然后选择想要查看其指标的组的名称。 1. 在**编辑组**页面上，选择**查看指标**。 此操作在新选项卡中打开 CloudWatch 控制台**指标**页面。 ------ # 配置采样规则 您可以使用 AWS X-Ray 控制台为您的服务配置采样规则。支持带采样配置[的主动跟踪 AWS 服务](xray-services.md)的 X-Ray SDK AWS 发行版使用采样规则来确定要记录哪些请求。 OpenTelemetry **Topics** + [配置采样规则](#xray-console-config) + [自定义抽样规则](#xray-console-custom) + [采样规则选项](#xray-console-sampling-options) + [采样规则示例](#xray-console-sampling-examples) + [将服务配置为使用采样规则](#xray-console-sampling-service) + [查看采样结果](#xray-console-sampling-results) + [后续步骤](#xray-console-sampling-nextsteps) ## 配置采样规则 您可以为以下使用案例配置采样： + **API 网关加密** - API 网关支持采样和活动跟踪。要在 API 阶段启用活动跟踪，请参阅[Amazon API Gateway 主动追踪支持 AWS X-Ray](xray-services-apigateway.md)。 + **AWS AppSync**— AWS AppSync 支持采样和主动跟踪。要启用对 AWS AppSync 请求的主动跟踪，请参阅[使用 AWS X-Ray 进行跟踪](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html)。 + **AWS Step Functions**— AWS Step Functions 支持采样和主动跟踪。要在 AWS Step Functions 状态机上启用主动跟踪，请参阅 Ste [p Functions 中的 X-Ray 跟踪](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html)。 + **适用于 OpenTelemetry 计算平台的 In AWS strument Distro** — 当使用诸如 Amazon EC2、Amazon ECS 或之类的计算平台时 AWS Elastic Beanstalk，如果应用程序已使用最新的 AWS Distro for 或 OpenTelemetry X-Ray SDK 进行检测，则支持采样。 ## 自定义抽样规则 您可以通过自定义采样规则来控制记录的数据量。也可以修改采样行为，而无需修改或重新部署代码。采样规则告诉 AWS Distro fo OpenTelemetry r (ADOT) 或 X-Ray SDK 根据一组标准需要记录多少请求。默认情况下，SDK 每秒记录第一个请求，以及任何其他请求的百分之五。每秒一个请求是*容器*。这可确保只要服务正在处理请求，就会每秒至少记录一个跟踪。5% 是对超出容器尺寸的额外请求进行采样的*比率*。 您可以将 X-Ray SDK 配置为从您包含在代码中的 JSON 文档读取采样规则。但是，当您运行服务的多个实例时，每个实例都会单独执行采样。这会导致采样的请求的总体比例升高，因为所有实例的容器都会被有效地一起添加。此外，要更新本地采样规则，则必须重新部署您的代码。 通过在 X-Ray 控制台中定义采样规则，然后[配置 SDK](#xray-console-sampling-service) 以从 X-Ray 服务读取规则，您可以避免这两个问题。该服务将管理每条规则的容器，并向您的服务的每个实例分配配额以基于正在运行的实例数均匀地分配容器。容器限制是根据您设置的规则计算的。由于规则是在服务中配置的，您可以管理规则而不进行额外的部署。 **注意** 配置采样规则时，必须明白 X-Ray 采样是 “基于父的”。这意味着采样决策只能做出一次，通常由处理请求的第一个 X-Ray-enabled服务（“根” 服务）做出。 如果下游服务收到的请求已经有来自上游父级的抽样决策，则无论它自己的匹配采样规则如何，它都将遵守该决定。 何时适用规则：您的自定义抽样规则仅对尚未做出抽样决定的服务生效。这通常适用于： 您的应用程序的入口点（例如，API Gateway、Load Balancer 或第一个经过检测的微服务）。 启动全新跟踪的异步进程或工作程序。 常见陷阱：如果您为 “服务 B” 创建了严格的采样规则，但 “服务 B” 始终由 “服务 A” 调用，则服务 B 的规则可能永远不会被应用，因为它只是遵循服务 A 传递的决定。要更改此工作流的跟踪采样，必须将采样规则配置为根服务（服务 A）。 **注意** X-Ray 会尽力应用采样规则，在某些情况下，有效采样率可能并不与配置的采样规则完全匹配。但是，随着时间推移，采样的请求数量应接近配置的百分比。 现在，您可以在亚马逊 CloudWatch 控制台中配置 X-Ray 采样规则。 **在 CloudWatch 控制台中配置采样规则** 1. 登录 AWS 管理控制台 并打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/)。 1. 在左侧导航窗格中选择 “**设置**” 下方的**设置**。 1. 在 **X-Ray 跟踪**部分中的**采样规则**下，选择**查看设置**。 1. 要创建规则，请选择**创建采样规则**。 要编辑规则，请选择该规则，然后选择**编辑**即可进行编辑。 要删除规则，请选择该规则，然后选择**删除**即可将其删除。 ## 采样规则选项 以下选项可用于每条规则。字符串值可以使用通配符来匹配单个字符 (`?`) 或零或多个字符 (`*`)。 **采样规则选项** + **规则名称**（字符串） — 一个唯一的规则名称。 + **优先级**（1 和 9999 之间的整数）— 采样规则的优先级。服务按优先级的上升顺序评估规则，并与匹配的第一条规则进行抽样决策。 + **容器**（非负整数）- 在应用固定比率之前，每秒与检测匹配的固定请求数。该容器不由服务直接使用，但适用于所有使用该规则的服务。 + **速率**（0 到 100 之间的整数）– 容器耗尽后，要检测的匹配请求的百分比。在控制台中配置采样规则时，请选择 0 到 100 之间的百分比。使用 JSON 文档在客户端 SDK 中配置采样时，请提供介于 0 和 1 之间的一个百分比。 + **服务名称**（字符串）- 检测过的服务在跟踪地图中显示的名称。 + X-Ray SDK - 您在记录器上配置的服务名称。 + Amazon API Gateway - `api-name/stage`。 + **服务类型**（字符串）- 在跟踪地图中显示的服务类型。对于 X-Ray SDK，请通过应用合适的插件来设置服务类型： + `AWS::ElasticBeanstalk::Environment`— AWS Elastic Beanstalk 环境（插件）。 + `AWS::EC2::Instance`— 亚马逊 EC2 实例（插件）。 + `AWS::ECS::Container` — Amazon ECS 容器（插件）。 + `AWS::EKS::Container`— 亚马逊 EKS 容器（插件）。 + `AWS::APIGateway::Stage` - Amazon API Gateway 阶段。 + `AWS::AppSync::GraphQLAPI `— 一个 AWS AppSync API 请求。 + `AWS::StepFunctions::StateMachine`— AWS Step Functions 状态机。 + **主机**（字符串）— HTTP 主机标头中的主机名。 + **HTTP 方法** - 字符串 HTTP 请求的方法。 + **URL 路径**（字符串） — 请求的 URL 路径。 + X-Ray SDK – HTTP 请求 URL 的路径部分。 + **资源 ARN**（字符串）-运行服务的 AWS 资源的 ARN。 + X-Ray 开发工具包 — 不支持。SDK 只能使用**资源 ARN** 设置为 `*` 的规则。 + Amazon API Gateway - 阶段 ARN。 + （可选）**属性**（键和值） - 在做出采样决定时已知的片段属性。 + X-Ray 开发工具包 — 不支持。该 SDK 将忽略指定属性的规则。 + AmazonAPI Gateway - 来自原始 HTTP 请求的标头。 + （可选）**SamplingRateBoost**（对象）-控制异常驱动的采样增强行为。 + MaxRate （0 到 100 之间的整数）— 最大采样率 (0.0—1.0) X-Ray 可能会在异常期间增加到 + CooldownWindowMinutes （大于 0 的整数）— 只能触发一次提升的时间窗口（分钟），从而阻止持续提升 ## 采样规则示例 **Example - 没有容器和低比率的默认规则** 您可以修改默认规则的容器和比率。默认规则应用于与任何其他规则都不匹配的请求。 + **容器**：**0** + **速率**：**5**（使用是使用的 JSON 文档配置的 **0.05**） **Example - 调试规则以跟踪对有问题的路由的所有请求** 一个临时应用的用于调试的高优先级规则。 + **规则名称**：**DEBUG – history updates** + **优先级**：**1** + **容器**：**1** + **速率**：**100**（使用是使用的 JSON 文档配置的 **1**） + **服务名称**：**Scorekeep** + **服务类型**：**\$1** + **主机**：**\$1** + **HTTP 方法**：**PUT** + **URL 路径**：**/history/\$1** + **资源 ARN**：**\$1** **Example — 更高的最低费率 POSTs** + **规则名称**：**POST minimum** + **优先级**：**100** + **容器**：**10** + **速率**：**10**（使用是使用的 JSON 文档配置的 **.1**） + **服务名称**：**\$1** + **服务类型**：**\$1** + **主机**：**\$1** + **HTTP 方法**：**POST** + **URL 路径**：**\$1** + **资源 ARN**：**\$1** **Example 启用异常驱动型提升** 配置一条规则，在异常期间触发最多 50% 的采样提升，冷却时间为 10 分钟。 + **规则名称**：**MyAdaptiveRule** + **优先级**：**100** + **容器**：**1** + **FixedRate**: **0.0510** + **服务名称**：**\$1** + **服务类型**：**\$1** + **主机**：**\$1** + **HTTP 方法**：**POST** + **URL 路径**：**\$1** + **maxRate**：**0.5** + **cooldownWindowMinutes**: **10** ## 将服务配置为使用采样规则 AWS Distro fo OpenTelemetry r (ADOT) 和 X-Ray SDK 需要额外的配置才能使用您在控制台中配置的采样规则。有关更多信息，请参阅采用您的语言的配置主题中有关配置采样策略的详细信息： + Java：在 ADOT Java 中[使用 X-Ray 远程采样](https://aws-otel.github.io/docs/getting-started/java-sdk/auto-instr#using-x-ray-remote-sampling) + Go：[使用 ADOT Go 配置采样](https://aws-otel.github.io/docs/getting-started/go-sdk/manual-instr#configuring-sampling) + Node.js：在 ADOT 中[使用 X-Ray 远程采样](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr#using-x-ray-remote-sampling) JavaScript + Python：在 ADOT Python 中[使用 X-Ray 远程采样](https://aws-otel.github.io/docs/getting-started/python-sdk/auto-instr#using-x-ray-remote-sampling) + Ruby：[采样规则](xray-sdk-ruby-configuration.md#xray-sdk-ruby-configuration-sampling) + .NET：[使用 X-Ray 远程采样和](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr#using-x-ray-remote-sampling) ADOT .NET 对于 API 网关，请参阅[Amazon API Gateway 主动追踪支持 AWS X-Ray](xray-services-apigateway.md)。 ## 查看采样结果 X-Ray 控制台**采样**页显示了有关您的服务如何使用每个采样规则的详细信息。 **趋势**列显示了在前几分钟如何使用了规则。每个列显示了 10 秒时段的统计数据。 **采样统计数据** + **匹配的总规则数**：与此规则匹配的请求数。此数字不包含可能与此规则匹配但先与优先级更高的规则匹配的请求。 + **总采样数**：已记录的请求数。 + **以固定比率采样**：通过应用规则的固定比率采样的请求数。 + **在容器限制下采样**：使用由 X-Ray 分配的配额采样的请求数。 + **已从容器借用**:通过从容器借用来采样的请求数。当某个服务首次将请求与规则匹配时，X-Ray 尚未向它分配配额。但是，如果容器至少为 1，该服务会每秒借用一个跟踪，直到 X-Ray 分配一个配额。 有关采样统计数据以及服务采样规则的方式的更多信息，请参阅[通过 X-Ray API 使用采样规则](xray-api-sampling.md)。 ## 后续步骤 您可以使用 X-Ray API 管理采样规则。利用 API，您可以按计划以编程方式创建和更新规则，也可以作为对警报或通知的响应执行此操作。有关说明和其他规则示例，请参阅[使用 AWS X-Ray API 配置采样、分组和加密设置](xray-api-configuration.md)。 适用于 X-Ray SDK 的 AWS 发行版 OpenTelemetry， AWS 服务 还使用 X-Ray API 来读取采样规则、报告采样结果和获取采样目标。服务必须跟踪它们应用每个规则的频率，根据优先级评估规则，并在某个请求与 X-Ray 尚未针对其向服务分配配额的规则匹配时从容器中借用。有关服务如何使用 API 进行采样的更多详细信息，请参阅[通过 X-Ray API 使用采样规则](xray-api-sampling.md)。 当 AWS Distro OpenTelemetry 或 X-Ray SDK 调用采样时 APIs，它们会使用 CloudWatch 代理作为代理。如果您已经在使用 TCP 端口 2000，则可以将代理配置为在其他端口上运行代理。有关详细信息，请参阅[CloudWatch 代理安装指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。 # 配置自适应采样 在异常峰值期间缺少关键跟踪会导致根本原因分析困难。但是，保持高采样率的成本很高。X-Ray 自适应采样让您可以在正常运行的同时全面了解异常情况并控制成本。使用自适应采样，您可以设置最大采样率，然后 X-Ray 会自动在该限制范围内进行调整。X-Ray 会计算捕获错误跟踪所需的最小提升。如果您的基准速率捕获了足够的数据，则不会进行提升。您仅需在需要时为额外采样付费。 使用自适应采样的优势： + 全面的事件可见性：无需人工干预即可在事件发生期间获得完整跟踪。X-Ray 会自动调整采样率以捕获错误跟踪，然后恢复到正常速率。 + 根本原因可见性：始终了解问题的源头。即使未触发完整跟踪采样，X-Ray 也能捕获关键错误数据。 + 优化成本：短暂的采样提升（最多 1 分钟）和自动冷却时间可防止过度采样。您只需为诊断问题所需的数据付费。 **Topics** + [支持的 SDK 和平台](#adaptive-sampling-supported-sdks) + [选择您的自适应采样方法](#adaptive-sampling-features) + [本地 SDK 配置](#local-sdk-configuration) ## 支持的 SDK 和平台 **支持的 SDK**：自适应采样需要使用最新版本的 ADOT SDK。 **支持的语言**：Java（版本 [v2.11.5](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5) 或更高版本） 您的应用程序必须使用支持的 ADOT SDK 进行检测，并与 Amazon CloudWatch 代理或 OpenTelemetry 收集器一起执行。 例如，Amazon EC2、Amazon ECS 和 Amazon EKS 是常见的平台，AWS Application Signals 为启用 ADOT SDK 和 Amazon CloudWatch 代理提供指导。 ## 选择您的自适应采样方法 自适应采样支持两种方法，即采样提升和异常跨度捕获。它们可以单独使用，也可以组合使用。 ### 采样提升 自适应采样提升基于采样规则，可与现有的基于 X-Ray 头部的采样模型配合使用。基于头部的采样意味着采样决策是在根服务上做出的，采样标志会传递到下游的调用链中的所有服务。 + **基于规则的提升**：提升始终与特定的 X-Ray 采样规则相关联。每条规则都可以定义自己的最大提升速率和冷却行为。 + **基于头部的采样**：采样决策是在根服务上做出的，采样标志会传递到下游的调用链中的所有服务。 + **异常驱动**：X-Ray 依靠 SDK 来报告异常统计信息。当 X-Ray 检测到错误或高延迟等异常情况时，它会使用这些统计信息来计算适当的提升速率（不超过配置的最大值）。 **异常报告** 调用链中的每个应用程序服务都可以通过所需的 SDK 发出异常统计信息： + **根服务**：必须在支持的 SDK 和平台上运行才能启用采样提升。如果不支持根服务，则不会进行提升。 + **下游服务**：下游服务仅报告异常；它们无法做出采样决策。当下游服务运行受支持的 SDK 时，检测到的异常可能会触发采样提升。当下游服务（例如，运行较旧的 SDK）不受支持时，该服务的异常不会触发提升。当这些服务遵循标准上下文传播（例如 W3C 跟踪上下文和 Baggage）时，它们仍然可以向下游传播上下文。这样可以确保其他下游服务中支持的 SDK 可以报告触发提升的异常情况。 **提升时间和范围** + **触发延迟**：在 X-Ray 检测到异常后，采样提升最快可在 10 秒内启动。 + **提升时间段**：在 X-Ray 触发提升后，它会持续最多 1 分钟，然后恢复到基准采样率。 + **提升冷却**：提升发生后，X-Ray 不会触发符合相同规则的另一次提升，直至冷却时间结束。 例如，将 `cooldown` 设为 10 分钟时，一旦提升结束，那么在接下来的 10 分钟内都无法触发新的提升。 特殊情况：将 `cooldown` 设为 1 分钟时，由于提升本身可以持续最多 1 分钟，因此如果异常持续存在，则可以有效地持续触发提升。 **注意** 为根服务使用支持的 SDK 和平台。采样提升仅适用于支持的 SDK 和平台。虽然采样提升捕获异常跟踪的可能性很高，但它可能无法捕获所有异常跟踪。 **提升可见度** 当采样规则配置了自适应采样提升功能时，X-Ray 会自动发出支持您监控提升活动的预设指标。 + **指标名称**：`SamplingRate` + **维度**：`RuleName`（设置为实际规则名称） 每条启用 `SamplingRateBoost` 的规则都将公布其有效采样率，包括基准速率和任何临时提升。从而让您能够实现以下目的： + 追踪触发提升的时间 + 监控每条规则的有效采样率 + 将提升与应用程序异常（例如错误峰值或延迟事件）关联起来 您可以在 **AWS/X-Ray 命名空间下的 Amazon CloudWatch 指标中查看这些指标。该指标值是一个介于 0 和 1 之间的浮点数，表示有效采样率**。 **使用 X-Ray 采样规则配置采样提升** 通过添加新 `SamplingRateBoost` 字段，您可以直接在现有 X-Ray 采样规则中启用自适应采样。有关更多信息，请参阅[配置采样规则](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom)。这提供了一种集中式方法，无需修改应用程序代码或应用应用程序部署即可启用自适应采样。启用自适应采样后，X-Ray 会在出现异常情况（例如错误峰值或延迟异常值）期间自动增加采样，同时将采样率保持在配置的最大值之内。`SamplingRateBoost` 可以应用于除 `Default` 采样规则之外的任何自定义采样规则。 `SamplingRateBoost` 字段定义了异常驱动型采样的上限和行为。 ``` "SamplingRateBoost": { "MaxRate": 0.25, "CooldownWindowMinutes": 10 } ``` `MaxRate` 定义了 X-Ray 在检测到异常时将应用的最大采样率。值范围是 `0.0` 到 `1.0`。例如，`"MaxRate": 0.25` 允许采样在异常时段内最多增加 25% 的请求。X-Ray 根据异常活动在基准值和最大值之间确定适当速率。 `CooldownWindowMinutes` 定义了只能触发一次采样率提升的时间窗口（以分钟为单位）。提升发生后，在下一个窗口之前不允许再次提升。值类型为*整数（分钟）*。 **自适应采样规则示例** ``` { "RuleName": "MyAdaptiveRule", "Priority": 1, "ReservoirSize": 1, "FixedRate": 0.05, "ServiceName": "*", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "SamplingRateBoost": { "MaxRate": 0.25, "CooldownWindowMinutes": 10 } } ``` 在此示例中，基准采样为 5%（`FixedRate: 0.05`）。在异常期间，X-Ray 可以将采样率增加多达 25%（`MaxRate: 0.25`）。每 10 分钟只能提升一次。 **异常条件配置** 如果未提供异常条件配置，ADOT SDK 会使用 **HTTP 5xx 错误代码**作为默认异常条件来触发采样提升。 您还可以在支持的 ADOT SDK 中使用环境变量在本地微调异常条件。有关更多信息，请参阅 [本地 SDK 配置](#local-sdk-configuration)。 ### 捕获异常跨度 异常跨度捕获可确保始终记录表示异常的临界跨度，即使未对完整跟踪进行采样也是如此。此功能通过专注于捕获异常本身来补充采样提升，而不是增加未来的跟踪采样。 当 ADOT SDK 检测到异常时，无论采样决策如何，它都会立即发出该跨度。由于 SDK 仅发出与异常相关的跨度，因此这些跟踪是部分跟踪，而不是完整的端到端交易。 一旦 ADOT SDK 检测到异常跨度，它就会尝试从同一条跟踪中发出尽可能多的跨度。在此功能下发出的所有跨度都使用属性 `aws.trace.flag.sampled = 0` 进行标记。这使您能够在交易搜索和分析中轻松区分部分跟踪（异常捕获）和完整跟踪（正常采样）。 我们建议您采用 [Transaction Search](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html) 以查看和查询部分跟踪。以下示例显示了 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) 控制台中的“服务”页面。ServiceC 配置了异常跨度捕获，它是应用采样提升的调用链的一部分。此配置会生成完整和部分跟踪。您可以使用 `aws.trace.flag.sampled` 属性来区分跟踪类型。 ![\[捕获异常跨度\]](http://docs.aws.amazon.com/zh_cn/xray/latest/devguide/images/adaptive-sampling.png) 只能通过 [本地 SDK 配置](#local-sdk-configuration) 启用或自定义异常跨度捕获。 ## 本地 SDK 配置 您可以通过环境变量提供 YAML 配置，从而在 ADOT SDK 中配置自适应采样功能。本地配置提供了对异常条件（阈值）的精细控制。 这对于*异常跨度捕获*是必需的，对于自定义*采样提升*条件则是可选的。以下是配置示例： ``` version: 1.0 anomalyConditions: - errorCodeRegex: "^5\\d\\d$" usage: both - operations: - "/api" errorCodeRegex: "^429|5\\d\\d$" highLatencyMs: 300 usage: sampling-boost - highLatencyMs: 1000 usage: anomaly-span-capture anomalyCaptureLimit: anomalyTracesPerSecond: 1 ``` 字段定义如下： + `version`：配置文件的架构版本 + `anomalyConditions`：定义检测异常的条件以及使用方式 + `errorCodeRegex`：定义哪些 HTTP 状态码被视为异常的正则表达式 + `operations`：条件适用的操作或端点列表 + `highLatencyMs`：延迟阈值（以毫秒为单位），超过该阈值的跨度将被视为异常 + `usage`：定义条件适用的功能： + `both`：适用于**采样提升**和**异常跨度捕获**（如果未指定用法，则为默认值） + `sampling-boost`：仅用于触发采样提升 + `anomaly-span-capture`：仅用于异常跨度捕获 + `anomalyCaptureLimit`：定义了包含异常跨度的跟踪的输出数量限制。 `anomalyTracesPerSecond`：每秒捕获包含异常跨度的跟踪的最大数量，用于防止跨度过大（若未设置 anomalyCaptureLimit，则默认值为 1）。 **注意** `AnomalyConditions` **覆盖**采样提升（HTTP 5xx）的默认异常条件。如果要在使用本地配置时保留默认条件，则必须将其明确包含在任意 `AnomalyConditions` 项目中。 对于每个 `anomalyConditions` 项目： **省略** `operations` 字段时，条件适用于**所有操作**（服务级别） 当 `operations` 字段存在但设置为**空列表**时，条件不适用于**任何操作**，从而使该项目成为无操作 当同时省略 `errorCodeRegex` 和 `highLatencyMs` 时，条件没有异常标准可供评估，从而使该项目成为无操作 逻辑关系： `anomalyConditions` 中的项目之间的关系为 **OR**。 在单个项目中，多个字段（例如 `errorCodeRegex` 和 `highLatencyMs`）用 **AND** 组合。 例如： ``` errorCodeRegex: "^429|5\\d\\d$" highLatencyMs: 300 ``` 该条件意味着，**状态码匹配 429 或 5xx 并且（AND）延迟 ≥ 300 毫秒**。 ### 将本地配置应用于 ADOT SDK 您可以通过设置环境变量 `AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG` 将本地配置应用于 ADOT SDK。该值必须是有效的 YAML 文档（内联或嵌套）。 例如，Amazon EC2 和 Amazon ECS，直接设置环境变量： ``` AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG="{version: 1.0, anomalyConditions: [{errorCodeRegex: \"^500$\", usage: \"sampling-boost\"}, {errorCodeRegex: \"^501$\", usage: \"anomaly-trace-capture\"}], anomalyCaptureLimit: {anomalyTracesPerSecond: 10}}" ``` 对于 Amazon EKS，请将容器组（pod）规范中的环境变量定义为嵌套的 YAML： ``` apiVersion: v1 kind: Pod metadata: name: adot-sample spec: containers: - name: adot-app image: my-app:latest env: - name: AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG value: | version: 1.0 anomalyConditions: - errorCodeRegex: "^500$" usage: sampling-boost - errorCodeRegex: "^501$" usage: anomaly-trace-capture anomalyCaptureLimit: anomalyTracesPerSecond: 10 ``` # 控制台深层链接 可以使用路由和查询深层链接到特定跟踪，或者筛选跟踪和跟踪地图的视图。 **控制台页面** + 欢迎页面 - [xray/home\$1/welcome](https://console.aws.amazon.com/xray/home#/welcome) + 入门 - [xray/home\$1/getting-started](https://console.aws.amazon.com/xray/home#/getting-started) + 跟踪地图 - [xray/home\$1/service-map](https://console.aws.amazon.com/xray/home#/service-map) + 跟踪 - [xray/home\$1/traces](https://console.aws.amazon.com/xray/home#/traces) ## 跟踪 您可以针对每个跟踪的时间线、原始和映射视图生成链接。 **跟踪时间线** - `xray/home#/traces/trace-id` **原始跟踪数据** - `xray/home#/traces/trace-id/raw` **Example - 原始跟踪数据** ``` https://console.aws.amazon.com/xray/home#/traces/1-57f5498f-d91047849216d0f2ea3b6442/raw ``` ## 筛选条件表达式 链接到筛选的跟踪列表。 **筛选的跟踪视图** - `xray/home#/traces?filter=filter-expression` **Example - 筛选表达式** ``` https://console.aws.amazon.com/xray/home#/traces?filter=service("api.amazon.com") { fault = true OR responsetime > 2.5 } AND annotation.foo = "bar" ``` **Example - 筛选条件表达式（URL 编码）** ``` https://console.aws.amazon.com/xray/home#/traces?filter=service(%22api.amazon.com%22)%20%7B%20fault%20%3D%20true%20OR%20responsetime%20%3E%202.5%20%7D%20AND%20annotation.foo%20%3D%20%22bar%22 ``` 有关筛选条件表达式的更多信息，请参阅[使用筛选条件表达式](xray-console-filters.md)。 ## 时间范围 以 ISO8601 格式指定时间长度或开始时间和结束时间。时间范围采用 UTC，最长可达 6 小时。 **时间长度** - `xray/home#/page?timeRange=range-in-minutes` **Example - 最近 1 小时的跟踪地图** ``` https://console.aws.amazon.com/xray/home#/service-map?timeRange=PT1H ``` **开始和结束时间** - `xray/home#/page?timeRange=start~end` **Example - 时间范围精确到秒** ``` https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00:00~2023-7-01T22:00:00 ``` **Example - 时间范围精确到分钟** ``` https://console.aws.amazon.com/xray/home#/traces?timeRange=2023-7-01T16:00~2023-7-01T22:00 ``` ## 区域 指定一个 AWS 区域 以链接到该区域的页面。如果您未指定区域，则控制台会将您重定向到最近访问过的区域。 **区域** ‐ `xray/home?region=region#/page` **Example - 美国西部（俄勒冈州）（us-west-2）的跟踪地图** ``` https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map ``` 当您随其他查询参数一起提供区域时，区域查询在前，哈希在后，同时页面名称在前，X-Ray 特定查询在后。 **Example - 美国西部（俄勒冈州）（us-west-2）最近 1 小时的跟踪地图** ``` https://console.aws.amazon.com/xray/home?region=us-west-2#/service-map?timeRange=PT1H ``` ## 组合 **Example - 使用持续时间筛选条件的最近跟踪** ``` https://console.aws.amazon.com/xray/home#/traces?timeRange=PT15M&filter=duration%20%3E%3D%205%20AND%20duration%20%3C%3D%208 ``` **输出** + 页面 - 跟踪 + 时间范围 - 过去 15 分钟 + 筛选条件 - duration >= 5 AND duration <= 8 # 使用 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=?;" } } ```