在 X-Ray 控制台中配置采样规则 - AWS X-Ray
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

在 X-Ray 控制台中配置采样规则

您可以使用 AWS X-Ray 控制台为您的服务配置采样规则。X-Ray 开发工具包和支持主动跟踪及采样配置的 AWS 服务使用采样规则来确定哪些请求需要记录。

配置采样规则

您可以为以下使用案例配置采样:

  • API 网关 Entrypoint – API 网关 支持采样和主动跟踪。要在 API 阶段启用主动跟踪,请参阅针对 AWS X-Ray 的 Amazon API Gateway 活动跟踪支持

  • AWS AppSync – AWS AppSync 支持采样和主动跟踪。要对 AWS AppSync 请求启用主动跟踪,请参阅 使用 AWS X-Ray 进行跟踪

  • 分析计算平台上的 X-Ray 开发工具包 – 在使用诸如 Amazon EC2、Amazon ECS 或 AWS Elastic Beanstalk 等计算平台时,如果使用最新版本的 X-Ray 开发工具包分析应用,则支持采样。

自定义抽样规则

通过自定义采样规则,您可以控制您记录的数据量,并即刻修改采样行为,而不修改或重新部署您的代码。采样规则向 X-Ray 开发工具包告知要为一系列条件记录的请求数。默认情况下,X-Ray 开发工具包记录每秒的第一个请求,以及任何额外请求中的 5%。每秒一个请求是容器。这可确保只要服务正在处理请求,就会每秒至少记录一个跟踪。5% 是对超出容器尺寸的额外请求进行采样的比率

您可以将 X-Ray 开发工具包配置为从您包含在代码中的 JSON 文档读取采样规则。但是,当您运行服务的多个实例时,每个实例都会单独执行采样。这会导致采样的请求的总体比例升高,因为所有实例的容器都会被有效地一起添加。此外,要更新本地采样规则,则需要重新部署您的代码。

通过在 X-Ray 控制台中定义采样规则,然后配置开发工具包以从 X-Ray 服务读取规则,您可以避免这两个问题。该服务将管理每条规则的容器,并向您的服务的每个实例分配配额以基于正在运行的实例数均匀地分配容器。容器限制是根据您设置的规则计算的。此外,由于规则是在服务中配置的,您可以管理规则而不进行额外的部署。

在 X-Ray 控制台中配置采样规则

  1. 打开 X-Ray 控制台

  2. 选择 Sampling (采样)

  3. 要创建规则,请选择 Create sampling rule (创建采样规则)

    要编辑规则,请选择规则的名称。

    要删除规则,请选择一条规则并使用 Actions (操作) 菜单来删除它。

采样规则选项

以下选项可用于每条规则。字符串值可以使用通配符来匹配单个字符 (?) 或零或多个字符 (*)。

采样规则选项

  • 规则名称(字符串) – 一个唯一的规则名称。

  • 优先级(1 和 9999 之间的整数) – 采样规则的优先级。服务按优先级的上升顺序评估规则,并与匹配的第一条规则进行抽样决策。

  • Reservoir (容器)(非负整数)– 在应用固定比率之前,每秒与仪器匹配的固定请求数。该容器不由服务直接使用,但适用于所有使用该规则的服务。

  • 速率(0 到 100 之间的数字) – 容器耗尽后,与仪器相匹配的请求百分比。速率可以是整数或浮点数。

  • Service name (服务名称)(字符串)– 分析过的服务在服务地图中呈现的名称。

    • X-Ray 开发工具包 – 您在记录器上配置的服务名称。

    • Amazon API Gateway – api-name/stage

  • Service type (服务类型)(字符串)– 在服务地图中呈现的服务类型。对于 X-Ray 开发工具包,请通过应用合适的插件来设置服务类型:

    • AWS::ElasticBeanstalk::Environment – AWS Elastic Beanstalk 环境(插件)。

    • AWS::EC2::Instance – Amazon EC2 实例(插件)。

    • AWS::ECS::Container – Amazon ECS 容器(插件)。

    • AWS::APIGateway::Stage – Amazon API Gateway 阶段。

    • AWS::AppSync::GraphQLAPI – AWS AppSync API 请求。

  • 主机(字符串) – HTTP 主机标头中的主机名。

  • HTTP method (HTTP 方法)字符串 – HTTP 请求的方法。

  • URL path (URL 路径)字符串 – 请求的 URL 路径。

    • X-Ray 开发工具包 – HTTP 请求 URL 的路径部分。

    • Amazon API Gateway – 不支持。

  • Resource ARN (资源 ARN)(字符串)– 运行服务的 AWS 资源的 ARN。

    • X-Ray 开发工具包 – 不支持。该开发工具包只能将规则与设置为 *Resource ARN (资源 ARN) 结合使用。

    • Amazon API Gateway – 阶段 ARN。

  • (可选)Attributes (属性)(键和值)– 在做出采样决定时已知的片段属性。

    • X-Ray 开发工具包 – 不支持。该开发工具包将忽略指定属性的规则。

    • Amazon API Gateway – 来自原始 HTTP 请求的标头。

采样规则示例

例 – 没有容器和低比率的默认规则

您可以修改默认规则的容器和比率。默认规则应用于与任何其他规则都不匹配的请求。

  • Reservoir (容器)0

  • Rate (比率)0.005 (0.5%)

例 – 调试规则以跟踪对有问题的路由的所有请求

一个临时应用的用于调试的高优先级规则。

  • Rule name (规则名称)DEBUG – history updates

  • Priority (优先级)1

  • Reservoir (容器)1

  • Rate (比率)1

  • Service name (服务名称)Scorekeep

  • Service type (服务类型)*

  • Host (主机)*

  • HTTP method (HTTP 方法)PUT

  • URL path (URL 路径)/history/*

  • Resource ARN (资源 ARN)*

例 – 针对 POST 的更高的最低比率

  • Rule name (规则名称)POST minimum

  • Priority (优先级)100

  • Reservoir (容器)10

  • Rate (比率)0.10

  • Service name (服务名称)*

  • Service type (服务类型)*

  • Host (主机)*

  • HTTP method (HTTP 方法)POST

  • URL path (URL 路径)*

  • Resource ARN (资源 ARN)*

将服务配置为使用采样规则

X-Ray 开发工具包需要额外配置来使用在控制台中配置的采样规则。有关更多信息,请参阅采用您的语言的配置主题中有关配置采样策略的详细信息:

有关 API 网关,请参阅针对 AWS X-Ray 的 Amazon API Gateway 活动跟踪支持

查看采样结果

X-Ray 控制台 Sampling (采样) 页显示了有关您的服务如何使用每个采样规则的详细信息。

Trend (趋势) 列显示了在前几分钟如何使用了规则。每个列显示了 10 秒时段的统计数据。

采样统计数据

  • Total matched rule (匹配的总规则数) – 与此规则匹配的请求数。此数字不包含可能与此规则匹配但先与优先级更高的规则匹配的请求。

  • Total sampled (总采样数) – 已记录的请求数。

  • Sampled with fixed rate (以固定比率采样) – 通过应用规则的固定比率采样的请求数。

  • Sampled with reservoir limit (在容器限制下采样) – 使用由 X-Ray 分配的配额采样的请求数。

  • Borrowed from reservoir (已从容器借用) – 通过从容器借用来采样的请求数。当某个服务首次将请求与规则匹配时,X-Ray 尚未向它分配配额。但是,如果容器至少为 1,该服务会每秒借用一个跟踪,直到 X-Ray 分配一个配额。

有关采样统计数据以及服务采样规则的方式的更多信息,请参阅通过 X-Ray API 使用采样规则

后续步骤

您可以使用 X-Ray API 管理采样规则。利用 API,您可以按计划以编程方式创建和更新规则,也可以作为对警报或通知的响应执行此操作。有关说明和其他规则示例,请参阅利用 AWS X-Ray API 配置采样、组和加密设置

X-Ray 开发工具包和 AWS 服务还使用 X-Ray API 来读取采样规则、报告采样结果和获取采样目标。服务必须跟踪它们应用每个规则的频率,根据优先级评估规则,并在某个请求与 X-Ray 尚未针对其向服务分配配额的规则匹配时从容器中借用。有关服务如何使用 API 进行采样的更多详细信息,请参阅通过 X-Ray API 使用采样规则

当 X-Ray 开发工具包调用采样 API 时,它使用 X-Ray 守护程序作为代理。如果您已使用 TCP 端口 2000,则可以配置守护程序以在其他端口上运行代理。有关详细信息,请参阅配置 AWS X-Ray 守护程序