配置自适应采样 - Amazon X-Ray
支持 SDKs 和平台选择您的自适应采样方法本地 SDK 配置
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

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

配置自适应采样

在异常峰值期间缺少关键轨迹会使根本原因分析变得困难。但是，保持高采样率的成本很高。X-Ray 自适应采样可在正常操作期间全面了解异常情况并控制成本。使用自适应采样，您可以设置最大采样率，然后 X-Ray 会自动在该限制范围内进行调整。X-Ray 计算捕获错误痕迹所需的最小提升。如果您的基准速率捕获了足够的数据，则不会出现提升。您只需在需要时支付额外采样费用。

使用自适应采样的好处：

  • 全面的事件可见性 — 无需人工干预即可在事故期间获得完整跟踪。X-Ray 会自动调整采样率以捕获错误痕迹，然后恢复到正常速率。

  • 根本原因可见性-始终查看问题的根源。即使未触发全迹采样，X-Ray 也会捕获关键错误数据。

  • 优化成本 — 短暂的采样提升（最多 1 分钟）和自动冷却时间可防止过度采样。您只需为诊断问题所需的数据付费。

支持 SDKs 和平台

支持的 SDK-自适应采样需要最新版本的 ADOT SDK。

支持的语言-Java（版本 v2.11.5 或更高版本）

您的应用程序必须使用支持的 ADOT 软件开发工具包进行检测，并与 Amazon A CloudWatch gent 或收集器一起执行。 OpenTelemetry

例如，亚马逊 EC2、亚马逊 ECS 和 Amazon EKS 是常见的平台， Amazon 应用程序信号为启用 ADOT SDK 和 Amazon A CloudWatch gent 提供指导。

选择您的自适应采样方法

自适应采样支持两种方法，即采样增强和异常跨度捕获。它们可以单独使用，也可以组合在一起。

采样提升

自适应采样增强基于采样规则，可与现有的基于 X-Ray 头部的采样模型配合使用。基于头部的采样意味着采样决策是在根服务上做出的，采样标志会传递到下游的呼叫链中的所有服务。

  • 基于规则的提升 — 提升始终与特定的 X-Ray 采样规则相关联。每条规则都可以定义自己的最大提升速率和冷却行为。

  • 基于头部的采样 — 采样决策在根服务中做出，采样标志向下游传递给调用链中的所有服务。

  • 异常驱动 — X- Ray 依靠 SDK 来报告异常统计信息。当 X-Ray 检测到错误或高延迟等异常情况时，它会使用这些统计数据来计算适当的提升速率（不超过配置的最大值）。

异常报告

调用链中的每个应用程序服务都可以通过所需的 SDK 发出异常统计信息：

  • 根服务 — 必须在支持的 SDK 和平台上运行才能启用采样提升。如果不支持根服务，则不会进行提升。

  • 下游服务-下游服务仅报告异常；它们无法做出抽样决策。当下游服务运行受支持的 SDK 时，检测到的异常可能会触发采样提升。当不支持下游服务（例如，运行较旧的 SDK）时，该服务的异常不会触发提升。当这些服务遵循标准上下文传播（例如 W3C 跟踪上下文和行李）时，它们仍然可以向下游传播上下文。这样可以确保支持更多下游 SDKs 的服务可以报告触发提升的异常情况。

提高时机和范围

  • 触发延迟 — 您可以预计，在 X-Ray 检测到异常后，采样量会低至 10 秒钟开始提升。

  • 增强期 — 在 X-Ray 触发增强后，它会持续长达 1 分钟，然后恢复到基本采样率。

  • Boost 冷却 — 提升发生后，在冷却窗口过去之前，X-Ray 不会触发符合相同规则的另一次提升。

    例如，当你设置cooldown为 10 分钟时，一旦增强结束，则在接下来的 10 分钟窗口之前无法触发新的提升。

    特殊情况：当你设置cooldown为 1 分钟时，由于提升本身可以持续长达 1 分钟，因此如果异常持续存在，则可以有效地持续触发增强。

注意

为根服务使用支持的 SDKs 和平台。采样提升仅适用于支持的 SDKs 平台。虽然采样增强捕获异常轨迹的可能性很高，但它可能无法捕获所有异常轨迹。

提高知名度

当采样规则配置了自适应采样增强功能时，X-Ray 会自动发出允许您监控增强活动的预设指标。

  • 指标名称 — SamplingRate

  • 维度-RuleName（设置为实际规则名称）

每条SamplingRateBoost启用的规则都将公布其有效采样率，包括基准率和任何临时提升。从而让您能够实现以下目的：

  • 追踪何时触发提升

  • 监控每条规则的有效采样率

  • 将提升与应用程序异常（例如错误峰值或延迟事件）关联起来

您可以在 Amazon/X-Ray 命名空间下的 Amazon CloudWatch 指标中查看这些指标。该指标值是一个介于 0 和 1 之间的浮点数，表示有效采样率。

使用 X-Ray 采样规则配置采样提升

通过添加新SamplingRateBoost字段，您可以直接在现有 X-Ray 采样规则中启用自适应采样。有关更多信息，请参阅自定义采样规则。这提供了一种集中式方法，无需修改应用程序代码或应用应用程序部署即可启用自适应采样。启用自适应采样后，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 配置。

异常跨度捕获

异常跨度捕获可确保始终记录表示异常的临界跨度，即使未对完整轨迹进行采样。此功能通过专注于捕获异常本身来补充采样提升，而不是为未来的轨迹增加采样。

当 ADOT SDK 检测到异常时，无论采样决策如何，它都会立即发出该跨度。由于 SDK 仅发出与异常相关的跨度，因此这些跟踪是部分跟踪，而不是完整交易。 end-to-end

一旦 ADOT SDK 检测到异常跨度，它就会尝试从同一条轨迹中发出尽可能多的跨度。在此功能下发射的所有跨度都使用属性进行标记。aws.trace.flag.sampled = 0这使您能够在交易搜索和分析中轻松区分部分跟踪（异常捕获）和完整轨迹（正常采样）。

我们建议您加入交易搜索以查看和查询部分跟踪。以下示例显示了 “应用程序信号” 控制台中的 “服务” 页面。ServiceC 配置了异常跨度捕获，它是应用采样增强的呼叫链的一部分。此配置会生成完整和部分跟踪。您可以使用该aws.trace.flag.sampled属性来区分追踪类型。

异常跨度捕获

只能通过启用或自定义异常跨度捕获。本地 SDK 配置

本地 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，关系为 O R。

    • 在单个项目中，多个字段（例如errorCodeRegex和highLatencyMs）与 AND 合并。

      例如：

      
errorCodeRegex: "^429|5\\d\\d$"
highLatencyMs: 300

      这种情况意味着，状态码与 429 或 5xx 匹配，延迟 ≥ 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