本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 配置采样规则
采样

您可以使用 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)。