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

# 配置自适应采样
自适应采样

在异常峰值期间缺少关键跟踪会导致根本原因分析困难。但是，保持高采样率的成本很高。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
```