本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用控制台 如果您想要使用只需最少编码的图形用户界面（GUI），请使用控制台。不熟悉 X-Ray 的用户可以使用预先构建的可视化效果快速入门，并执行基本任务。您可以直接从控制台执行以下操作： + 启用 X-Ray。 + 查看应用程序性能的简单摘要。 + 检查应用程序的运行状况。 + 识别高级别错误。 + 查看基本跟踪摘要。 要与 X-Ray 进行交互，您可以使用 Amazon CloudWatch 控制台（网址为：[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)）或 X-Ray 控制台（网址为：[https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/xray/home)）。 ## 使用 Amazon CloudWatch 控制台 CloudWatch 控制台包含新的 X-Ray 功能，这些功能是从 X-Ray 控制台重新设计的，使其更易于使用。如果您使用 CloudWatch 控制台，则可以查看 CloudWatch 日志和指标以及 X-Ray 跟踪数据。可使用 CloudWatch 控制台查看和分析包括以下内容在内的数据： + X-Ray 跟踪 - 在应用程序处理请求时查看、分析和筛选与其关联的跟踪。使用这些跟踪可查找高延迟、调试错误并优化您的应用程序工作流。查看跟踪地图和服务地图，以查看应用程序工作流的可视化形式。 + 日志 - 查看、分析和筛选应用程序生成的日志。使用日志可排查错误，并根据特定的日志值设置监控。 + 指标 - 使用您的资源发出的指标或创建您自己的指标，来衡量和监控您的应用程序性能。以图形和图表的形式来查看这些指标。 + 监控网络和基础设施 - 监控主要网络的中断情况以及基础结构（包括容器化应用程序、其他 Amazon 服务和客户端）的运行状况和性能。 + 下面的**使用 X-Ray 控制台**一节列出了 X-Ray 控制台中的所有功能。 有关 CloudWatch 控制台的更多信息，请参阅 [Amazon CloudWatch 入门](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/GettingStarted.html)。 访问 [https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)，登录 Amazon CloudWatch 控制台。 ## 使用 X-Ray 控制台 X-Ray 控制台为应用程序请求提供分布式跟踪。如果您想要更简单的控制台体验或不想更新应用程序代码，可使用 X-Ray 控制台。Amazon 不再开发 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) - 使用密钥对静态数据加密，您可以使用 Amazon Key Management Service 对该密钥进行审核或禁用。 + 分组 - 使用筛选条件表达式来定义一组具有共同特征（例如 URL 名称或响应时间）的跟踪。有关更多信息，请参阅[配置分组](https://docs.amazonaws.cn/xray/latest/devguide/aws-xray-interface-console.html#xray-console-groups)。 要登录 X-Ray 控制台，请访问 [https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/xray/home)。 ## 深入了解 X-Ray 控制台 深入了解 X-Ray 控制台 使用 X-Ray 控制台可查看您的应用程序提供服务的请求的服务和关联跟踪的地图，并配置影响将跟踪发送到 X-Ray 的方式的分组和采样规则。 **注意** X-Ray 服务地图和 CloudWatch ServiceLens 地图已合并为 Amazon CloudWatch 控制台中的 X-Ray 跟踪地图。打开 [CloudWatch 控制台](https://console.amazonaws.cn/cloudwatch/)，然后在左侧导航窗格的 **X-Ray 跟踪**下选择**跟踪地图**。 CloudWatch 现在包括 [Application Signals](https://docs.amazonaws.cn/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.amazonaws.cn/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.amazonaws.cn/cloudwatch/)，然后在左侧导航窗格的 **X-Ray 跟踪**下选择**跟踪地图**。 ## 查看跟踪映射 跟踪地图是跟踪数据的可视化形式，此类数据由您的应用程序生成。地图显示为请求提供服务的服务节点，表示请求来源的上游客户端节点以及表示应用程序在处理请求时使用的 Web 服务和资源的下游服务节点。 跟踪地图显示使用 Amazon SQS 和 Lambda 的不同事件驱动型应用程序中跟踪的互联视图。有关更多信息，请参阅[跟踪事件驱动型应用程序](xray-tracelinking.md)。跟踪地图还支持[跨账户跟踪](xray-console-crossaccount.md)，在一张地图中显示多个账户中的节点。 ------ #### [ CloudWatch console ] **如何在 CloudWatch 控制台中查看跟踪地图** 1. [打开 CloudWatch 控制台](https://console.amazonaws.cn/cloudwatch/)。在左侧导航窗格的 **X-Ray 跟踪**部分下选择**跟踪地图**。 ![\[CloudWatch 控制台跟踪地图页面\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-servicemap-cw.png) 1. 选择一个服务节点来查看该节点的请求，或选择两个节点之间的边缘来查看经过该连接的请求。 1. 其他信息显示在跟踪地图下方，其中包括指标、警报以及响应时间分布的选项卡。在**指标**选项卡上，选择每张图的范围以深入查看更多详情，或选择**故障**或**错误**选项以筛选跟踪。在**呼应时间分布**选项卡上，选择在图内的一个范围以按照呼应时间来筛选跟踪。 ![\[Dashboard showing latency, requests, and faults metrics for an ElasticBeanstalk environment.\]](http://docs.amazonaws.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.amazonaws.cn/xray/home#)。默认情况下，将显示服务地图。也可以从左侧导航窗格中选择**服务地图**。 ![\[X-Ray 控制台服务地图页\]](http://docs.amazonaws.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 Amazon ECS container.\]](http://docs.amazonaws.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.amazonaws.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.amazonaws.cn/xray/latest/devguide/images/group-select-console.png) ------ 现在，将会对服务地图进行筛选以显示与所选组的筛选条件表达式匹配的跟踪。 ## 跟踪地图图例和选项 跟踪地图包含图例和多个选项用于自定义地图显示。 ------ #### [ CloudWatch console ] 选择地图右上角的**图例和选项**下拉列表。选择节点内显示的内容，其中包括： + **指标**显示所选时间范围内的平均响应时间和每分钟发送的跟踪数量。 + **节点**显示每个节点内的服务图标。 从**首选项**窗格中选择更多地图设置，可通过点击地图右上角的齿轮图标访问。这些设置包括选择使用哪个指标来确定每个节点的大小，以及应在地图上显示哪些 Canary。 ------ #### [ X-Ray console ] 在地图右上角选择**地图图例**链接，显示服务地图图例。可以在跟踪地图的右下角选择服务地图选项，包括： + 每人节点内显示的**服务图标**切换，用于切换是显示服务图标，还是平均呼应时间以及在所选时间范围内每分钟的跟踪数量。 + **节点大小：None** 将所有节点设置为相同大小。 + **节点大小：运行状况**按受影响的请求数量确定节点大小，其中包括错误、故障或受限制的请求。 + **节点大小：流量**按请求总数确定节点大小。 ------ # 查看跟踪和跟踪详情 跟踪 使用 X-Ray 控制台中的**跟踪**页面根据 URL、响应代码或跟踪摘要中的其他数据查找跟踪。从跟踪列表中选择跟踪后，**跟踪详情**页面会显示与所选跟踪关联的服务节点的地图，以及跟踪分段的时间表。 ## 查看跟踪 ------ #### [ CloudWatch console ] **在 CloudWatch 控制台中查看跟踪** 1. 登录 Amazon Web Services 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)）。 1. 在左侧导航窗格中，依次选择 **X-Ray 跟踪**和**跟踪**。您可以按组筛选或输入[筛选条件表达式](xray-console-filters.md)。这将筛选出显示在页面底部**跟踪**部分中的跟踪。 或者，也可以使用服务地图导航到某个具体的服务节点，然后查看跟踪。这将打开已应用查询的**跟踪**页面。 1. 在**查询优化**部分中优化您的查询。要按常用属性筛选跟踪，请从**按条件优化查询**旁边的向下箭头中选择一个选项。这些选项包括以下内容： + 节点 - 按服务节点筛选跟踪。 + 资源 ARN - 按与跟踪关联的资源筛选跟踪。这些资源的示例包括 Amazon Elastic Compute Cloud（Amazon EC2）实例、Amazon 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 的 Amazon 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.amazonaws.cn/xray/latest/devguide/images/xray-trace-details-cw.png) 如果您有一个使用 Amazon SQS 和 Lambda 的事件驱动型应用程序，则可以在**跟踪地图**中看到每个请求的关联跟踪视图。在地图中，来自消息创建者的跟踪链接到来自 Amazon Lambda 使用者的跟踪，并显示为虚线边缘。有关事件驱动型应用程序的更多信息，请参阅[跟踪事件驱动型应用程序](xray-tracelinking.md)。 **跟踪**和**跟踪详情**页面还支持[跨账户跟踪](xray-console-crossaccount.md)，其中会列出跟踪列表中和单个跟踪地图中多个账户内的跟踪。 ------ #### [ X-Ray console ] **如何在 X-Ray 控制台中查看跟踪** 1. 在 X-Ray 控制台中打开[跟踪](https://console.amazonaws.cn/xray/home#/traces)页面。**跟踪概述**面板显示按常用特征分组的跟踪列表，包括**错误根本原因**、**ResourceARN** 和 **InstanceId**。 1. 要选择常用特征来查看分组的跟踪集，请展开**分组依据**旁边的向下箭头。下图显示了按 [Amazon X-Ray 示例应用程序](xray-scorekeep.md) URL 分组的跟踪的跟踪概述以及关联跟踪的列表。 ![\[按 URL 分组的跟踪概述示例，然后是跟踪列表，其详细信息包括 ID、方法和响应。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-traces.png) 1. 选择跟踪的 **ID** 以在**跟踪列表**下查看。您也可以在导航窗格中选择**服务地图**，来查看特定服务节点的跟踪。然后，您可以查看与该节点关联的跟踪。 **时间线**选项卡显示跟踪的请求流，包括以下内容： + 跟踪中每个分段的路径地图。 + 分段到达跟踪地图中的节点花了多长时间。 + 在跟踪地图中向该节点发出了多少个请求。 下图显示了与向应用程序示例发出的 `GET` 请求关联的**跟踪地图**示例。箭头显示每个分段完成请求所采用的路径。服务节点显示在 `GET` 请求期间发出的请求数。 ![\[跟踪地图，然后是时间线，其中包含各个分段、其持续时间、起点和彼此的终点。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/xray-trace-details.png) 有关**时间线**选项卡的更多信息，请参阅下面的**深入了解跟踪时间线**一节。 **原始数据**选项卡以 `JSON` 格式显示有关跟踪以及构成该跟踪的分段和子分段的信息。此类信息可能包含以下内容： + 时间戳 + 唯一 ID + 与分段或子分段关联的资源 + 分段或子分段的源或起源 + 有关对您的应用程序发出的请求的其他信息，例如 HTTP 请求的响应 ------ ## 深入了解跟踪时间线 **时间线**部分在水平条旁边显示分段和子分段的层次结构，该水平条与其完成任务所用的时间相对应。列表中的第一个条目为分段，表示服务为单个请求记录的所有数据。子分段以缩进形式列出，并在分段后面列出。各列包含有关每个分段的信息。 ------ #### [ CloudWatch console ] 在 CloudWatch 控制台中，**分段时间线**提供以下信息： + 第一列：列出所选跟踪中的分段和子分段。 + **分段状态**列：列出每个分段和子分段的状态结果。 + **响应代码**列：列出对分段或子分段发出的浏览器请求的 HTTP 响应状态代码（如果有）。 + **持续时间**列：列出分段或子分段的运行时长。 + **托管位置**列：列出运行分段或子分段的命名空间或环境（如果适用）。有关更多信息，请参阅[收集的维度和维度组合](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/AppSignals-StandardMetrics.html#AppSignals-StandardMetrics-Dimensions)。 + 最后一列：显示与分段或子分段运行的持续时间相对应的水平条（相对于时间线中的其他分段或子分段）。 要按服务节点对分段和子分段列表进行分组，请打开**按节点分组**。 ------ #### [ X-Ray console ] 在跟踪详情页面中，选择**时间线**选项卡，以查看构成跟踪的每个分段和子分段的时间线。 在 X-Ray 控制台中，**时间线**提供以下信息： + **名称**列：列出跟踪中分段和子分段的名称。 + **响应**列：列出针对分段或子分段发出的浏览器请求的 HTTP 响应状态代码（如果有）。 + **持续时间**列：列出分段或子分段的运行时长。 + **状态**列：列出分段或子分段状态的结果。 + 最后一列：显示与分段或子分段运行的持续时间相对应的水平条（相对于时间线中的其他分段或子分段）。 要查看控制台用来生成时间线的原始跟踪数据，请选择**原始数据**选项卡。原始数据以 `JSON` 格式显示有关跟踪以及构成该跟踪的分段和子分段的信息。此类信息可能包含以下内容： + 时间戳 + 唯一 ID + 与分段或子分段关联的资源 + 分段或子分段的源或起源 + 有关对您的应用程序发出的请求的其他信息，例如 HTTP 请求的响应。 ------ 当您使用检测的 SDKAmazon、HTTP 或 SQL 客户端调用外部资源时，X-Ray SDK 会自动记录子分段。也可以使用 X-Ray SDK 记录任何函数或代码块的自定义子分段。自定义子分段在打开时记录的其他子分段将成为自定义子分段的子级。 ## 查看分段详细信息 在跟踪**时间线**中选择某分段的名称，可以查看其详细信息。 **分段详细信息**面板显示**概述**、**资源**、**注释**、**元数据**、**异常**以及 **SQL** 选项卡。以下选项卡将适用： + **概述**选项卡显示有关请求和响应的信息。信息包括名称、开始时间、结束时间、持续时间、请求 URL、请求操作、请求响应代码以及任何错误和故障。 + 分段的**资源**选项卡显示有关 X-Ray SDK 以及运行您的应用程序的 Amazon 资源的信息。使用 X-Ray SDK 的 Amazon EC2、Amazon Elastic Beanstalk 或 Amazon ECS 插件记录特定于服务的资源信息。有关插件的更多信息，请参阅[配置 X-Ray SDK for Java](xray-sdk-java-configuration.md)中的**服务插件**部分。 + 其余的选项卡显示为分段记录的**注释**、**元数据**和**异常**。当所检测的请求生成异常时，会自动捕获这些异常。注释和元数据包含您使用 X-Ray SDK 提供的操作记录的附加信息。要将注释或元数据添加到分段，请使用 X-Ray SDK。有关更多信息，请参阅[正在对您的应用程序进行检测 Amazon X-Ray](xray-instrumenting-your-app.md)中“使用 SDKAmazon X-Ray 检测应用程序”下方列出的特定于语言的链接。 ## 查看子分段详细信息 在跟踪时间线中选择某个子分段的名称，可以查看其详细信息。 + **概述**选项卡包含有关请求和响应的信息。其中包括名称、开始时间、结束时间、持续时间、请求 URL、请求操作、请求响应代码以及任何错误和故障。对于使用已检测客户端生成的子分段，**概述**选项卡包含从您的应用程序角度来看的请求和响应信息。 + 子分段的**资源**选项卡显示有关用于运行子分段的 Amazon 资源的详细信息。例如，资源选项卡可能包含 Amazon Lambda 函数 ARN、有关 DynamoDB 表的信息、调用的任何操作以及请求 ID。 + 其余的选项卡显示子分段上记录的**注释**、**元数据**和**异常**。当所检测的请求生成异常时，会自动捕获这些异常。注释和元数据包含您使用 X-Ray SDK 提供的操作记录的附加信息。使用 X-Ray SDK，将注释或元数据添加到分段。有关更多信息，请参阅[正在对您的应用程序进行检测 Amazon X-Ray](xray-instrumenting-your-app.md)中**使用 SDKAmazon X-Ray 检测应用程序**下方列出的特定于语言的链接。 对于自定义子分段，**概述**选项卡显示子分段的名称，您可以设置该名称来指定它所记录的代码或函数区域。有关更多信息，请参阅[使用适用于 Java 的 X-Ray 开发工具包生成自定义子分段](xray-sdk-java-subsegments.md)中**使用 SDKAmazon X-Ray 检测应用程序**下方列出的特定于语言的链接。 下图显示了自定义子分段的**概述**选项卡。概述包含子分段 ID、父级 ID、名称、开始和结束时间、持续时间、状态以及错误或故障。 ![\[有关子分段的概述信息，包括 ID、父级 ID、名称、时间、错误和故障。\]](http://docs.amazonaws.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.amazonaws.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 实体的步骤，请参阅[从 Amazon 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 实体的步骤，请参阅[从 Amazon 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 } ``` 例如， Amazon 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 } ``` 要搜索特定节点 Amazon Web Services 账户，请指定账户 ID。 **Example - 具有 id 函数和账户 ID 的服务筛选器** 包含某个特定账户 ID `AWS::Lambda::Function` 中某项服务的请求。 ``` service(id(account.id: "account-id")) ``` # 跨账户跟踪 跨账户跟踪 Amazon X-Ray 支持*跨账户可观测性*，让您可以监控跨越一个Amazon Web Services 区域内多个账户的应用程序并对其进行故障排除。您可以如同在一个账户中进行操作那样，无缝搜索、可视化和分析任何关联账户中的指标、日志和跟踪。这样可提供在多个账户之间移动的请求的完整视图。您可以在 [CloudWatch 控制台](https://console.amazonaws.cn/cloudwatch/)中的 X-Ray 跟踪地图和跟踪页面上查看跨账户跟踪。 共享的可观测性数据可以包括以下任意类型的遥测数据： + Amazon CloudWatch 中的指标 + 在 Amazon CloudWatch Logs 中记录组 + Amazon X-Ray 中的跟踪记录 + Amazon CloudWatch Application Insights 中的应用程序 ## 配置跨账户可观测性 若要启用跨账户可观测性，请设置一个或多个 Amazon *监控*账户，并将它们与多个*源*账户相关联。监控账户是一个中央 Amazon Web Services 账户，可以查看源账户生成的可观测性数据并与之交互。源账户是一个单独的 Amazon Web Services 账户，可为其包含的资源生成可观测性数据。 源账户与监控账户共享其可观测性数据。最多可将每个源账户中的跟踪复制到 5 个监控账户。将源账户中的跟踪副本到第一个监控账户免费。发送到更多监控账户的副本根据标准定价，向每个源账户收费。请参阅 [Amazon X-Ray 定价](https://www.amazonaws.cn/xray/pricing/)和 [Amazon CloudWatch 定价](https://www.amazonaws.cn/cloudwatch/pricing/)，了解更多信息。 若要在监控账户和源账户之间创建关联，请使用 CloudWatch 控制台或 Amazon CLI 中新推出的“可预测性访问管理器”命令以及 API。有关更多信息，请参阅 [CloudWatch 跨账户可观察性](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html)。 **注意** X-Ray 跟踪对接收它们的 Amazon Web Services 账户 收费。如果[采样的](xray-concepts.md#xray-concepts-sampling)请求跨超过一个 Amazon Web Services 账户 的服务，则每个账户都会记录单独的跟踪，且所有跟踪共享同一跟踪 ID。请参阅 [Amazon X-Ray 定价](https://www.amazonaws.cn/xray/pricing/)和 [Amazon CloudWatch 定价](https://www.amazonaws.cn/cloudwatch/pricing/)，了解有关跨账户可观测性定价的更多信息。 ## 查看跨账户跟踪 跨账户跟踪显示在监控账户中。每个源账户仅显示该特定账户的本地跟踪。以下各节假设您已登录监控账户并已打开 Amazon CloudWatch 控制台。在跟踪地图和跟踪页面上，监控账户徽章都显示在右上角。 ![\[监控账户徽章\]](http://docs.amazonaws.cn/xray/latest/devguide/images/crossaccount-monitoring-account.png) ### 跟踪地图 在 CloudWatch 控制台中左侧导航窗格的 **X-Ray 跟踪**下，选择**跟踪地图**。默认情况下，跟踪地图显示将跟踪发送到监控账户的所有源账户的节点，以及监控账户本身的节点。在跟踪地图上，选择左上角的**筛选条件**，使用**账户**下拉列表筛选跟踪地图。应用账户筛选条件后，与当前筛选条件不匹配的账户的服务节点将显示为灰色。 ![\[筛选后的跟踪地图\]](http://docs.amazonaws.cn/xray/latest/devguide/images/crossaccount-servicemap-account-filter.png) 选择服务节点时，节点详细信息窗格将包含该服务的账户 ID 和标签。 ![\[节点详细信息窗格\]](http://docs.amazonaws.cn/xray/latest/devguide/images/crossaccount-servicemap-node-detail.png) 在跟踪地图的右上角，选择**列表视图**以查看服务节点列表。服务节点列表包括来自监控账户的服务以及所有已配置的源帐户。从**节点**筛选条件中进行选择，按 **Account label** 或 **Account id** 筛选节点列表。 ![\[筛选后的服务列表\]](http://docs.amazonaws.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.amazonaws.cn/xray/latest/devguide/images/crossaccount-traces-query-by-account.png) 按**账户**优化查询。从列表中选择一个或多个账户，然后选择**添加到查询**。 ![\[按账户优化跟踪查询\]](http://docs.amazonaws.cn/xray/latest/devguide/images/crossaccount-traces-refine-by-account.png) ### 跟踪详情 从**跟踪**页面底部的**跟踪**列表中选择相应跟踪，可查看该跟踪的详细信息。会显示**跟踪详情**，其中包括一张跟踪详情地图，其中包含相应跟踪通过的所有账户中的服务节点。选择某个具体的服务节点查看其相应的账户。 **分段时间线**一节按照时间线显示每个分段的账户详细信息。 ![\[分段时间线\]](http://docs.amazonaws.cn/xray/latest/devguide/images/crossaccount-traces-segment-timeline.png) # 跟踪事件驱动型应用程序 跟踪事件驱动型应用程序 Amazon X-Ray 支持跟踪使用 Amazon SQS 和 Amazon Lambda 的事件驱动型应用程序。使用 CloudWatch 控制台查看使用 Amazon SQS 排队并由一个或多个 Lambda 函数处理的每个请求的互联视图。上游消息创建者的跟踪会自动链接到下游 Lambda 使用器节点的跟踪，从而创建应用程序的端到端视图。 **注意** 每个跟踪分段最多可以链接到 20 个跟踪，每个跟踪最多可包含 100 个链接。某些情况下，链接更多跟踪可能会导致超出[最大的跟踪文档大小](https://docs.amazonaws.cn/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.amazonaws.cn/cloudwatch/)内的**跟踪地图**页面查看跟踪地图，其中包含链接到 Lambda 使用者的跟踪的消息创建者的跟踪。这些链接以虚线边缘显示，连接到 Amazon SQS 节点和下游 Lambda 使用器节点。 ![\[Amazon SQS 和 Lambda 节点之间的边缘。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-batch-servicemap-linkededge.png) 选择虚线边缘以显示*收到的事件期限*直方图，图中显示了使用器收到时事件年限的分布情况。每次收到事件时都会计算期限。 ![\[带有收到的事件期限直方图的边缘。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-servicemap-linkededgedetails-cw.png) ## 查看链接的跟踪详情 **查看消息创建者、Amazon SQS 队列或 Lambda 使用器发送的跟踪详情：** 1. 使用**跟踪地图**选择消息创建者、Amazon SQS 或 Lambda 使用者节点。 1. 从节点详情中选择**查看跟踪**以显示跟踪列表。您也可以直接导航到 CloudWatch 控制台中的**跟踪**页面。 1. 从列表中选择特定跟踪以打开跟踪详情页面。跟踪详情页面显示所选跟踪是链接的跟踪集合的一部分时的消息。 ![\[链接的跟踪详情\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-batch-tracedetails-header.png) 跟踪详情地图显示当前跟踪以及上下游链接的跟踪，其中每个跟踪都包含在指示每个跟踪边界的框中。如果当前选择的跟踪链接到多个上游或下游跟踪，则上游或下游链接的跟踪的节点会堆叠在一起，并会显示**选择跟踪**按钮。 ![\[多个链接的上游跟踪\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-batch-tracedetails-tracemap.png) 在跟踪详情地图下方显示跟踪分段的时间表，其中包含上下游链接的跟踪。如果有多个上游或下游链接的中，则不会显示它们的分段详情。若要查看链接的跟踪集合中某一个跟踪的分段详情，[选择单一跟踪](#xray-tracelinking-filterbatch)，如下所述。 ![\[显示链接的跟踪的分段时间表\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-batch-tracedetails-timeline.png) ## 选择链接的跟踪集合中的某一个跟踪 **将链接的跟踪集合筛选到只有一个跟踪，以时间表的形式查看分段详情。** 1. 在跟踪详情地图中链接的跟踪下方，选择**选择跟踪**。将会显示跟踪列表。 ![\[链接的跟踪列表\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-batch-tracedetails-tracelist.png) 1. 选中跟踪旁边的单选按钮，在跟踪详情地图里查看它。 1. 选择**取消跟踪选择**以查看链接的跟踪的整个集合。 ![\[单个链接的跟踪\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-batch-tracedetails-filteredbatch.png) # 使用延迟直方图 直方图 当您在 Amazon X-Ray [跟踪地图](xray-console-servicemap.md)上选择一个节点或边缘时，X-Ray 控制台会显示一个延迟分布直方图。 ## 延迟 延迟是指请求从开始到完成所用的时间。直方图显示延迟分布。它的 x 轴显示持续时间，y 轴显示与每个持续时间匹配的请求百分比。 该直方图显示服务在不到 300 ms 的时间内完成大多数请求。一小部分请求用时多达 2 秒，而一些异常项用了更多时间。 ![\[延迟直方图，其中 x 轴显示持续时间，y 轴显示对应每个持续时间的请求百分比\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-servicemap-histogram.png) ## 解释服务详细信息 服务直方图和边缘直方图提供了从服务或请求者角度看的延迟的可视化表示形式。 + 通过单击圆圈选择*服务节点*。X-Ray 显示服务所完成的请求的直方图。延迟是服务记录的延迟，不包括服务和请求者之间的任何网络延迟。 + 通过单击两个服务之间边缘的线条或箭头尖端来选择*边缘*。X-Ray 显示来自请求者的、由下游服务所完成的请求的直方图。延迟是服务记录的延迟，且包括两个服务之间的网络连接延迟。 要解释**服务详细信息**面板直方图，您可以查找偏离直方图中大多数值最大的值。可以将这些*异常值* 视为直方图中的高峰或峰值，并且您可以查看特定区域的跟踪以调查发生了什么情况。 要查看按延迟筛选的跟踪，请在直方图上选择一个范围。单击要开始选择的位置，然后从左向右拖动，突出显示一个要包括在跟踪筛选条件中的延迟范围。 ![\[选择一个范围来查看跟踪，方法是单击要开始的位置，然后从向左向右拖动，画出跟踪筛选器的范围\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-selection.png) 选择范围后，您可以选择 **Zoom**，只查看该部分的直方图并细化您的选择。 ![\[选择 Zoom 以查看直方图中的选定范围\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-servicemap-servicedetails-zoom.png) 将焦点设置为感兴趣的区域后，选择 **View traces**。 # 使用 X-Ray 见解 见解 Amazon X-Ray 会持续分析您账户中的跟踪数据，以识别应用程序中出现的紧急问题。当错误率超出预期范围时，它会创建*见解*来记录问题并跟踪问题产生的影响，直到问题被解决。借助见解，您可以： + 确定应用程序哪里出现了问题，问题的根本原因，以及关联的影响。您可以从见解提供的影响分析中获取到某个问题的严重性和优先级。 + 随着时间推移，当问题发生变化时收到通知。见解通知可以与使用 Amazon EventBridge 的监控和警报解决方案相集成。这种集成让您可以根据问题的严重性发送自动化电子邮件或警报。 X-Ray 控制台可识别跟踪地图中正在发生事件的节点。若要查看见解摘要，请选择受影响的节点。还可以从左侧导航窗格中选择**见解**，查看和筛选见解。 ![\[带有见解摘要的跟踪地图节点。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-insights-servicemap.png) 当 X-Ray 在服务地图的一个或多个节点中检测到*异常*时，便会创建见解。该服务使用统计建模来预测应用程序中服务的预期故障率。前述示例中存在的异常为 Amazon Elastic Beanstalk 中的故障数量增多。Elastic Beanstalk 服务器经历了多次 API 调用超时，导致下游节点出现异常。 ## 在 X-Ray 控制台中启用见解 必须为希望使用见解功能的每个组都启用见解。可以从**组**页面启用见解。 1. 打开 [X-Ray 控制台](https://console.amazonaws.cn/xray/home#)。 1. 选择现有组或通过选择**创建组**创建一个新组，然后选择**启用见解**。有关如何在 X-Ray 控制台中配置组的更多信息，请参阅[配置组](xray-console-groups.md)。 1. 在左侧导航窗格中选择**见解**，然后选择要查看的见解。 ![\[X-Ray 控制台中的见解列表。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-insights.png) **注意** X-Ray 使用 GetInsightSummarts、GetInsightEvents 和 GetInsightImpactGraph API 操作从见解中检索数据。 有关更多信息，请参阅 [如何 Amazon X-Ray 与 IAM 配合使用](security_iam_service-with-iam.md)。 ## 启用见解通知 可以使用见解通知为每个见解事件创建一则通知，例如，当创建见解、发生重大更改，或关闭见解时。客户可以通过 Amazon EventBridge 接收此类通知，并使用条件规则采取行动，例如 SNS 通知、Lambda 调用、将消息发布到 SQS 队列，或任意的目标 EventBridge 支持。我们会尽可能发送见解通知，但并不保证。有关目标的更多信息，请参阅 [Amazon EventBridge 目标](https://docs.amazonaws.cn/eventbridge/latest/userguide/eventbridge-targets.html)。 您可以从**组**页面为任意已启用见解的组启用见解通知。 **为 X-Ray 组启用通知** 1. 打开 [X-Ray 控制台](https://console.amazonaws.cn/xray/home#)。 1. 选择现有组或通过选择**创建组**创建一个新组，确保选中**启用见解**，然后选择**启用通知**。有关如何在 X-Ray 控制台中配置组的更多信息，请参阅[配置组](xray-console-groups.md)。 **配置 Amazon EventBridge 条件规则** 1. 打开 [Amazon EventBridge 控制台](https://console.amazonaws.cn/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，后者暂不支持客户托管密钥。有关更多信息，请参阅 [Amazon X-Ray 中的数据保护](xray-console-encryption.md)。 ## 见解 见解概述页面试图回答以下三个关键问题： + 什么是潜在问题？ + 什么是根本原因？ + 什么是影响？ **异常服务**一节介绍了每个服务的时间表，展示了事件过程中故障率的变化情况。时间表显示了出现故障的跟踪数量，根据记录的流量，以实心条带指明预计的故障数量。*事件窗口*将见解的持续时间可视化。当 X-Ray 观察到指标出现异常并且启用见解后依旧存在的时候，事件窗口启动。 以下示例显示的是导致某个事件的故障出现增加： ![\[X-Ray 见解的概述页面。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-insights-overview.png) **根本原因**一节显示了聚焦根本原因服务和受影响路径的跟踪地图。可以选择根本原因地图右上角的眼睛图标，以隐藏未受影响的节点。根本原因服务是 X-Ray 识别到异常的最远的下游节点。它可以代表您检测的某项服务，或是您服务使用检测客户端调用过的外部服务。例如，如果您调用带有检测的 Amazon SDK 客户端的 Amazon DynamoDB，DynamoDB 中的故障数量会增强，从而导致将 DynamoDB 作为根本原因的见解。 若要进一步调查根本原因，请在根本原因图上选择**查看根本原因详情**。您可以使用**分析**页面来调查根本原因以及相关消息。有关更多信息，请参阅 [与 Analytics 控制台交互](xray-console-analytics.md)。 ![\[X-Ray 见解的概述页面。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-insights-root-cause.png) 在地图中继续上游的故障会影响多个节点，并会导致多种异常。如果某个故障一直传回到发出请求的用户，就会出现*客户端故障*。这是跟踪地图的根节点的一个故障。**影响**示意图为整个组的客户端体验提供了时间表。根据以下状态的比例来计算此体验：**故障**、**错误**、**瓶颈**和**没错**。 ![\[X-Ray 事件的影响图。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-insights-impact.png) 此示例显示在事件发生过程中，在顶部节点带有故障的跟踪增加了。下游服务中的事件并不总是与客户端错误的增加相对应。 选择**分析见解**会在窗口中打开 X-Ray Analytics 控制台，您可以在其中深入研究产生见解的跟踪集。有关更多信息，请参阅 [与 Analytics 控制台交互](xray-console-analytics.md)。 **了解影响** Amazon X-Ray 会衡量某个持续问题造成的影响，并作为一部分生成见解和通知。有两种方法来衡量影响： + 对 X-Ray [组](xray-console-groups.md)的影响 + 对根本原因服务的影响 此影响由在给定时间内发生故障或造成错误的请求比例决定。通过这种影响分析，您可以根据自己的特定情况得出问题的严重性和优先级。除了见解通知以外，影响还是控制台体验的一部分。 **重复数据删除** Amazon X-Ray 见解会重复去除多个微服务中存在的重复问题。它使用异常检测来确定是某个问题根本原因的服务，确定其他相关服务是否由于同一根本原因展现出异常行为，并将结果记录为单个见解。 ## 查看见解的进展 X-Ray 会定期重新评估见解直到问题得到解决，并将每个显著的中间变化记录为[通知](#xray-console-insight-notifications)，可以作为 Amazon EventBridge 事件发送。这让您能够构建流程和工作流以确定问题随时间推移如何变化，并采取适当操作，例如发送电子邮件，或与使用 EventBridge 的警报系统相集成。 您可以在**影响**页面上的**影响时间表**中查看事件活动。默认情况下，时间表会显示最受影响的服务，直到您选择另一项服务。 ![\[检查包含影响时间表的页面。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-insights-inspect.png) 要查看某个事件的跟踪地图和示意图，请从影响时间表中选择该事件。跟踪地图显示应用程序中受事件影响的服务。在“**影响分析**”下，图表显示选定节点和组中客户端的故障时间表。 ![\[X-Ray 见解的影响分析图。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/console-insights-inspect-analysis.png) 若要更加深入地了解某个事件中涉及的跟踪，请在**检查**页面上选择**分析事件**。可以使用**分析**页面来优化跟踪列表并确定受影响的用户。有关更多信息，请参阅 [与 Analytics 控制台交互](xray-console-analytics.md)。 # 与 Analytics 控制台交互 Analytics Amazon 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.amazonaws.cn/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.amazonaws.cn/xray/latest/devguide/xray-api-gettingdata.html#xray-api-analytics)。 | | **增量 (**�**)** | 在跟踪集 A 和 B 都处于活动状态时添加到指标表中的列。增量列计算跟踪集 A 和跟踪集 B 之间的跟踪百分比差异。 | ## 响应时间分配 X-Ray Analytics 控制台生成两个主要图表以帮助您直观显示跟踪：**响应时间分配**和**时间序列活动**。本节和下面的内容提供有关每个图表的示例，并说明有关如何阅读这些图表的基本知识。 以下是与响应时间线状图关联的颜色（时间序列图使用相同的颜色方案）： + **组中的所有跟踪** - 灰色 + **已检索跟踪** - 橙色 + **已筛选跟踪集 A** - 绿色 + **已筛选跟踪集 B** - 蓝色 **Example - 响应时间分配** 响应时间分配是一个图表，用于显示给定响应时间内的跟踪数量。单击并拖动以在响应时间分配内进行选择。这会针对特定响应时间内的所有跟踪的工作跟踪集，选择和创建一个名为 `responseTime` 的筛选条件。 ![\[显示跟踪响应时间分布的图表。\]](http://docs.amazonaws.cn/xray/latest/devguide/images/analytics-responseTime.png) ## 时间序列活动 时间序列活动图表显示给定时间段的跟踪数量。颜色指示反映响应时间分配的线图颜色。活动序列中的颜色块越深越饱满，则表示给定时间的跟踪数越多。 **Example - 时间序列活动** 单击并拖动以在时间序列活动图表内进行选择。这会针对特定时间范围内的所有跟踪的工作跟踪集，选择和创建一个名为 `timerange` 的筛选条件。 ![\[进行选择并创建筛选条件\]](http://docs.amazonaws.cn/xray/latest/devguide/images/analytics-timeSeries.png) ## 工作流程示例 下面的示例说明 X-Ray Analytics 控制台的常见使用案例。每个示例演示控制台体验的一个关键功能。这些示例作为一个组遵循基本的疑难排查工作流。这些步骤介绍了如何先发现运行状况不佳的节点，以及如何与 Analytics 控制台交互以自动生成比较查询。通过查询缩小范围后，您就可以查看感兴趣的跟踪的详细信息，以确定是什么问题影响了服务的健康运行。 ## 在服务图表上观察故障 跟踪地图根据成功调用与错误和故障的比率为每个节点配置颜色，从而指示这些节点的运行状况。当您在节点上看到红色百分比时，这指示一个故障。使用 X-Ray Analytics 控制台调查此故障。 有关如何解读跟踪地图的更多信息，请参阅[查看跟踪地图](https://docs.amazonaws.cn/xray/latest/devguide/xray-console.html#xray-console-servicemap)。 ![\[观察故障\]](http://docs.amazonaws.cn/xray/latest/devguide/images/scorekeep-gettingstarted-servicemap-before-2021.png) ## 确定高峰响应时间 使用响应时间分配，您可以观察高峰响应时间。通过选择高峰响应时间，图表下方的各个表格将会更新，以显示所有关联的指标，如状态代码。 您可以通过单击并拖动 X-Ray 来选择和创建筛选条件。筛选条件会以灰色阴影的形式显示在线状图顶部。现在，您可以沿着分配左右拖动阴影区以更新您的选择和筛选条件。 ![\[进行选择并创建筛选条件\]](http://docs.amazonaws.cn/xray/latest/devguide/images/analytics-showFilterf.png) ## 查看所有标有状态代码的跟踪 您可以使用图表下方的指标表钻取所选峰值内的跟踪。通过单击**HTTP 状态代码**表中的行，您可以自动对工作数据集创建筛选条件。例如，您可以查看状态代码为 500 的所有跟踪。这会在跟踪集平铺中创建一个名为 `http.status` 的筛选条件标签。 ## 查看子组中与用户关联的所有项目 根据用户、URL、响应时间根本原因或其他预定义的属性钻取错误集。例如，要额外筛选状态代码为 500 的跟踪集，请从 **USERS** 表中选择一行。这会导致在跟踪集平铺中产生两个筛选条件标签：`http.status`（如前面指定）和 `user`。 ## 比较具有不同标准的两组跟踪 跨不同用户及其 POST 请求进行比较，以查找其他差异和关联。应用您的第一个筛选条件集。它们通过响应时间分配中的蓝线定义。然后，选择**比较**。最初，这会对跟踪集 A 创建筛选器的副本。 要继续，请定义要应用于跟踪集 B 的新的筛选条件集。这第二个集合由绿线表示。以下示例根据蓝色和绿色颜色方案显示不同的行。 ![\[线图比较\]](http://docs.amazonaws.cn/xray/latest/devguide/images/analytics-compareLines.png) ## 确定感兴趣的跟踪并查看其详细信息 当您使用控制台筛选条件缩小范围时，指标表下方的跟踪列表将变得更有意义。跟踪列表将有关 **URL**、**用户**和**状态代码**的信息合并显示在一个视图中。如需更多见解，请从此表中选择一行，以打开跟踪的详细信息页面并查看其时间线和原始数据。 # 配置组 组 组是由筛选条件表达式定义的跟踪的集合。您可以使用组生成其他服务图并提供 Amazon CloudWatch 指标。您可以使用 Amazon X-Ray 控制台或 X-Ray API 为服务创建组并进行管理。本主题介绍如何使用 X-Ray 控制台来创建和管理组。请参阅[组](xray-api-configuration.md#xray-api-configuration-groups)，了解如何使用 X-Ray API 管理组。 您可以为跟踪地图、跟踪或分析创建跟踪组。创建组后，该组会在以下全部三个页面上的组下拉菜单中变为一个可用的筛选条件：**跟踪地图**、**跟踪**和**分析**。 ![\[组菜单\]](http://docs.amazonaws.cn/xray/latest/devguide/images/group-menu.png) 组由其名称或 Amazon 资源名称（ARN）标识，并包含筛选条件表达式。此服务将比较传入到表达式的跟踪并相应地存储它们。请参阅[使用筛选条件表达式](xray-console-filters.md)，详细了解如何构建筛选表达式。 更新组的筛选条件表达式不会更改已记录的数据。更新仅应用于后续跟踪。这可能会生成新旧表达式的合并图。为避免发生这种情况，请删除当前群组并创建一个新的组。 **注意** 群组按检索到的符合筛选条件表达式的追踪数量计费。有关更多信息，请参阅[Amazon X-Ray定价](https://www.amazonaws.cn/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. 登录 Amazon Web Services 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/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.amazonaws.cn/xray/latest/devguide/images/group-insights-cw.png) 1. 在**标签**中，选择**添加新标签**以输入标签键，以及选填的标签值。根据需要继续添加其他标签。标签键必须是唯一的。要删除标签，请选择每个标签下方的**删除**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.amazonaws.cn/xray/latest/devguide/images/group-tags-cw.png) 1. 选择**创建群组**。 ------ #### [ X-Ray console ] 1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/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.amazonaws.cn/xray/latest/devguide/images/group-insights.png) 1. 在**标签**中，输入一个标签键和可选的标签值。添加标签时会出现一个新行，供您添加另一个标签。标签键必须是唯一的。若要删除标签，请选择标签行末的 **X**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.amazonaws.cn/xray/latest/devguide/images/group-tags.png) 1. 选择**创建群组**。 ------ ## 应用组 ------ #### [ CloudWatch console ] 1. 登录 Amazon Web Services 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)）。 1. 从 **X-Ray 跟踪**下的导航窗格中打开以下任意一个页面： + **跟踪地图** + **跟踪** 1. 在**按 X-Ray 组筛选**筛选条件中输入组名称。页面上显示的数据会发生变化，以匹配组中设置的筛选条件表达式。 ------ #### [ X-Ray console ] 1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/xray/home)。 1. 从导航窗格中打开以下任意一个页面： + **跟踪地图** + **跟踪** + **Analytics** 1. 在组菜单中，选择在 [创建组](#xray-console-group-create-console) 中创建的组。页面上显示的数据会发生变化，以匹配组中设置的筛选条件表达式。 ------ ## 编辑组 ------ #### [ CloudWatch console ] 1. 登录 Amazon Web Services 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/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.amazonaws.cn/xray/latest/devguide/images/group-insights-cw.png) 1. 在**标签**中，选择**添加新标签**以输入标签键，以及选填的标签值。根据需要继续添加其他标签。标签键必须是唯一的。要删除标签，请选择每个标签下方的**删除**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.amazonaws.cn/xray/latest/devguide/images/group-tags-cw.png) 1. 更新完组后，选择**更新组**。 ------ #### [ X-Ray console ] 1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/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.amazonaws.cn/xray/latest/devguide/images/group-insights.png) 1. 在**标签**中，编辑标签键和值。标签键必须是唯一的。标签值是选填，如果需要可以删除。若要删除标签，请选择标签行末的 **X**。有关标签的更多信息，请参阅 [标记 X-Ray 采样规则和组](xray-tagging.md)。 ![\[“组”页面上的“标签”字段\]](http://docs.amazonaws.cn/xray/latest/devguide/images/group-tags.png) 1. 更新完组后，选择**更新组**。 ------ ## 克隆组 克隆组会创建具有现有组的筛选条件表达式和标签的新组。克隆组时，新组具有被克隆组的同一名称，名称后附加 `-clone`。 ------ #### [ CloudWatch console ] 1. 登录 Amazon Web Services 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/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. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/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. 登录 Amazon Web Services 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)）。 1. 在左侧导航窗格中，选择**设置**。 1. 在 **X-Ray 跟踪**部分中的**组**下，选择**查看设置**。 1. 从**组**部分中选择一个组，然后选择**删除**。 1. 请在提示您进行确认时选择**删除**。 ------ #### [ X-Ray console ] 1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/xray/home)。 1. 从左侧导航窗格中打开**组**页面，然后选择想要删除的组的名称。 1. 在**操作**菜单上，选择**删除组**。 1. 请在提示您进行确认时选择**删除**。 ------ ## 在 Amazon CloudWatch 中查看组指标 创建组后，将根据组的筛选条件表达式检查传入跟踪，因为它们存储在 X-Ray 服务中。匹配每个标准的跟踪数量的指标每分钟都会发布到 Amazon CloudWatch。在**编辑组**页面上选择**查看指标**以打开 CloudWatch 控制台，转到**指标**页面。有关如何使用 CloudWatch 指标的更多信息，请参阅 *Amazon CloudWatch 用户指南* 中的[使用 Amazon CloudWatch 指标](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/working_with_metrics.html)。 ------ #### [ CloudWatch console ] 1. 登录 Amazon Web Services 管理控制台并打开 CloudWatch 控制台（[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/cloudwatch/)）。 1. 在左侧导航窗格中，选择**设置**。 1. 在 **X-Ray 跟踪**部分中的**组**下，选择**查看设置**。 1. 从**组**部分中选择一个组，然后选择**编辑**。 1. 在**编辑组**页面上，选择**查看指标**。 此操作在新选项卡中打开 CloudWatch 控制台**指标**页面。 ------ #### [ X-Ray console ] 1. 登录到 Amazon Web Services 管理控制台，然后通过以下网址打开 X-Ray 控制台：[https://console.aws.amazon.com/xray/home](https://console.amazonaws.cn/xray/home)。 1. 从左侧导航窗格中打开**组**页面，然后选择想要查看其指标的组的名称。 1. 在**编辑组**页面上，选择**查看指标**。 此操作在新选项卡中打开 CloudWatch 控制台**指标**页面。 ------ # 配置采样规则 采样 您可以使用 Amazon X-Ray 控制台为您的服务配置采样规则。支持带采样配置[的主动跟踪 Amazon Web Services 服务](xray-services.md)的 X-Ray SDK Amazon 发行版使用采样规则来确定要记录哪些请求。 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 主动追踪支持 Amazon X-Ray](xray-services-apigateway.md)。 + **Amazon AppSync**— Amazon AppSync 支持采样和主动跟踪。要启用对 Amazon AppSync 请求的主动跟踪，请参阅[使用 Amazon X-Ray 进行跟踪](https://docs.amazonaws.cn/appsync/latest/devguide/x-ray-tracing.html)。 + **Amazon Step Functions**— Amazon Step Functions 支持采样和主动跟踪。要在 Amazon Step Functions 状态机上启用主动跟踪，请参阅 Ste [p Functions 中的 X-Ray 跟踪](https://docs.amazonaws.cn/step-functions/latest/dg/concepts-xray-tracing.html)。 + **适用于 OpenTelemetry 计算平台的 In Amazon strument Distro** — 当使用诸如 Amazon EC2、Amazon ECS 或之类的计算平台时 Amazon Elastic Beanstalk，如果应用程序已使用最新的 Amazon Distro for 或 OpenTelemetry X-Ray SDK 进行检测，则支持采样。 ## 自定义抽样规则 您可以通过自定义采样规则来控制记录的数据量。也可以修改采样行为，而无需修改或重新部署代码。采样规则告诉 Amazon 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. 登录 Amazon Web Services 管理控制台 并打开 CloudWatch 控制台，网址为[https://console.aws.amazon.com/cloudwatch/](https://console.amazonaws.cn/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`— Amazon Elastic Beanstalk 环境（插件）。 + `AWS::EC2::Instance`— 亚马逊 EC2 实例（插件）。 + `AWS::ECS::Container` — Amazon ECS 容器（插件）。 + `AWS::EKS::Container`— 亚马逊 EKS 容器（插件）。 + `AWS::APIGateway::Stage` - Amazon API Gateway 阶段。 + `AWS::AppSync::GraphQLAPI `— 一个 Amazon AppSync API 请求。 + `AWS::StepFunctions::StateMachine`— Amazon Step Functions 状态机。 + **主机**（字符串）— HTTP 主机标头中的主机名。 + **HTTP 方法** - 字符串 HTTP 请求的方法。 + **URL 路径**（字符串） — 请求的 URL 路径。 + X-Ray SDK – HTTP 请求 URL 的路径部分。 + **资源 ARN**（字符串）-运行服务的 Amazon 资源的 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** ## 将服务配置为使用采样规则 Amazon 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 主动追踪支持 Amazon 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，您可以按计划以编程方式创建和更新规则，也可以作为对警报或通知的响应执行此操作。有关说明和其他规则示例，请参阅[使用 Amazon X-Ray API 配置采样、分组和加密设置](xray-api-configuration.md)。 适用于 X-Ray SDK 的 Amazon 发行版 OpenTelemetry， Amazon Web Services 服务 还使用 X-Ray API 来读取采样规则、报告采样结果和获取采样目标。服务必须跟踪它们应用每个规则的频率，根据优先级评估规则，并在某个请求与 X-Ray 尚未针对其向服务分配配额的规则匹配时从容器中借用。有关服务如何使用 API 进行采样的更多详细信息，请参阅[通过 X-Ray API 使用采样规则](xray-api-sampling.md)。 当 Amazon Distro OpenTelemetry 或 X-Ray SDK 调用采样时 APIs，它们会使用 CloudWatch 代理作为代理。如果您已经在使用 TCP 端口 2000，则可以将代理配置为在其他端口上运行代理。有关详细信息，请参阅[CloudWatch 代理安装指南](https://docs.amazonaws.cn/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 是常见的平台，Amazon 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` 的规则都将公布其有效采样率，包括基准速率和任何临时提升。从而让您能够实现以下目的： + 追踪触发提升的时间 + 监控每条规则的有效采样率 + 将提升与应用程序异常（例如错误峰值或延迟事件）关联起来 您可以在 **Amazon/X-Ray 命名空间下的 Amazon CloudWatch 指标中查看这些指标。该指标值是一个介于 0 和 1 之间的浮点数，表示有效采样率**。 **使用 X-Ray 采样规则配置采样提升** 通过添加新 `SamplingRateBoost` 字段，您可以直接在现有 X-Ray 采样规则中启用自适应采样。有关更多信息，请参阅[配置采样规则](https://docs.amazonaws.cn/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.amazonaws.cn/xray/latest/devguide/xray-transactionsearch.html) 以查看和查询部分跟踪。以下示例显示了 [Application Signals](https://docs.amazonaws.cn/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) 控制台中的“服务”页面。ServiceC 配置了异常跨度捕获，它是应用采样提升的调用链的一部分。此配置会生成完整和部分跟踪。您可以使用 `aws.trace.flag.sampled` 属性来区分跟踪类型。 ![\[捕获异常跨度\]](http://docs.amazonaws.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.amazonaws.cn/xray/home#/welcome) + 入门 - [xray/home\$1/getting-started](https://console.amazonaws.cn/xray/home#/getting-started) + 跟踪地图 - [xray/home\$1/service-map](https://console.amazonaws.cn/xray/home#/service-map) + 跟踪 - [xray/home\$1/traces](https://console.amazonaws.cn/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 ``` ## 区域 指定一个 Amazon Web Services 区域 以链接到该区域的页面。如果您未指定区域，则控制台会将您重定向到最近访问过的区域。 **区域** ‐ `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