設定自適應抽樣 - AWS X-Ray
支援的 SDKs和平台選擇您的自適應抽樣方法本機 SDK 組態

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

設定自適應抽樣

在異常峰值期間缺少關鍵追蹤可能會使根本原因分析變得困難。不過，維持高取樣率非常昂貴。X-Ray 自適應取樣提供對異常的完整可見性，並在正常操作期間控制成本。透過適應性取樣，您可以設定最大取樣率，而 X-Ray 會自動在該限制內調整。X-Ray 會計算擷取錯誤追蹤所需的最低提升。如果您的基準速率擷取足夠的資料，則不會發生提升。您只需在需要時支付額外的抽樣費用。

使用自適應取樣的優點：

  • 完整的事件可見性 – 在事件期間取得完整的追蹤，無需手動介入。X-Ray 會自動調整取樣率以擷取錯誤追蹤，然後返回正常速率。

  • 根本原因可見性 – 一律查看問題的來源。即使未觸發完整追蹤取樣，X-Ray 也會擷取重要的錯誤資料。

  • 最佳化成本 – 短暫取樣提升 （最多 1 分鐘） 和自動冷卻時間可防止過度取樣。您只需為診斷問題所需的資料付費。

支援的 SDKs和平台

支援的 SDK – 自適應取樣需要最新版本的 ADOT 開發套件。

支援的語言 – Java (2.11.5 版或更新版本）

您的應用程式必須使用支援的 ADOT 開發套件進行檢測，並與 Amazon CloudWatch Agent 或 OpenTelemetry Collector 一起執行。

例如，Amazon EC2、Amazon ECS 和 Amazon EKS 是常見的平台，其中 AWS Application Signals 提供啟用 ADOT SDK 和 Amazon CloudWatch Agent 的指引。

選擇您的自適應抽樣方法

自適應取樣支援兩種方法：取樣提升和異常範圍擷取。這些可以獨立套用，也可以合併在一起。

取樣提升

自適應取樣提升是以取樣規則為基礎，並適用於現有的 X-Ray 前端型取樣模型。以前端為基礎的取樣表示在根服務進行取樣決策，而取樣旗標會在下游傳遞給呼叫鏈中的所有服務。

  • 以規則為基礎的提升 – 提升一律與特定的 X-Ray 取樣規則繫結。每個規則都可以定義自己的最大提升速率和冷卻行為。

  • 以頭部為基礎的抽樣 – 在根服務中做出抽樣決策，並將抽樣旗標向下游傳遞給呼叫鏈中的所有服務。

  • 異常驅動 – X-Ray 依賴 SDK 報告異常統計資料。當 X-Ray 偵測到異常，例如錯誤或高延遲時，它會使用這些統計資料來計算適當的提升速率 （高達設定的最大值）。

異常報告

呼叫鏈中的每個應用程式服務都可以透過所需的 SDK 發出異常統計資料：

  • 根服務 – 必須在支援的 SDK 和平台上執行，才能啟用取樣提升。如果不支援根服務，則不會進行提升。

  • 下游服務 – 下游服務只會報告異常；無法做出抽樣決策。當下游服務執行支援的 SDK 時，偵測到的異常可能會觸發取樣提升。當下游服務不受支援 （例如，執行較舊的 SDK) 時，該服務的異常不會觸發提升。當這些服務遵循標準內容傳播 （例如 W3C 追蹤內容和裝訂） 時，仍然可以在下游傳播內容。這可確保進一步下游服務中支援的 SDKs 可以報告觸發提升的異常。

提升時間和範圍

  • 觸發延遲 – 在 X-Ray 偵測到異常之後，您可以預期取樣提升開始的時間低至 10 秒。

  • 提升期間 – X-Ray 觸發提升後，最長會持續 1 分鐘，然後再返回基本取樣率。

  • 提升冷卻 – 提升發生後，X-Ray 不會觸發相同規則的另一個提升，直到超過冷卻時段為止。

    例如，當您將 cooldown設定為 10 分鐘時，一旦提升結束，在接下來的 10 分鐘時段之前，就無法觸發新的提升。

    特殊情況：當您將 cooldown 設定為 1 分鐘時，由於提升本身最多可持續 1 分鐘，因此如果異常持續存在，則可以持續有效觸發提升。

注意

為您的根服務使用支援的 SDKs和平台。取樣提升僅適用於支援的 SDKs和平台。雖然取樣提升有很高的機率會擷取異常追蹤，但可能不會擷取每個異常追蹤。

提高可見性

當取樣規則設定為調適式取樣提升時，X-Ray 會自動發出推展指標，讓您監控提升活動。

  • 指標名稱 – SamplingRate

  • 維度 – RuleName（設定為實際規則名稱）

SamplingRateBoost 啟用 的每個規則都會發佈其有效的取樣率，包括基準速率和任何暫時提升。這可讓您：

  • 觸發提升時的追蹤

  • 監控每個規則的有效取樣率

  • 將提升與應用程式異常 （例如錯誤峰值或延遲事件） 相關聯

您可以在 Amazon CloudWatch Metrics 的 AWS/X-Ray 命名空間下檢視這些指標。指標值是介於 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 組態。

異常範圍擷取

異常範圍擷取可確保一律記錄代表異常的關鍵範圍，即使未對完整追蹤進行取樣。此功能透過專注於擷取異常本身來補充抽樣提升，而不是增加未來追蹤的抽樣。

當 ADOT SDK 偵測到異常時，它會立即發出跨度，無論抽樣決策為何。由於 SDK 只會發出與異常相關的範圍，因此這些追蹤是部分追蹤，而不是完整的end-to-end交易。

一旦 ADOT SDK 偵測到異常跨度，它會嘗試從相同的追蹤發出盡可能多的跨度。此功能下發出的所有範圍都會以 屬性 標記aws.trace.flag.sampled = 0。這可讓您在交易搜尋和分析中輕鬆區分部分追蹤 （異常擷取） 與完整追蹤 （正常抽樣）。

我們建議加入交易搜尋以檢視和查詢部分追蹤。下列範例顯示 Application Signals 主控台中的服務頁面。ServiceC 設定為異常跨度擷取，它是套用取樣提升的呼叫鏈的一部分。此組態會產生完整和部分追蹤。您可以使用 aws.trace.flag.sampled 屬性來區分追蹤類型。

異常範圍擷取

異常範圍擷取只能透過 啟用或自訂本機 SDK 組態。

本機 SDK 組態

您可以透過環境變數提供 YAML 組態，在 ADOT 開發套件中設定自適應抽樣功能。本機組態提供對異常條件、閾值的精細控制。

這是異常範圍擷取的必要項目，以及自訂取樣提升條件的選用項目。以下是組態的範例：


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 且延遲 ≥ 300 毫秒。

將本機組態套用至 ADOT SDK

您可以設定環境變數 ，將本機組態套用至 ADOT 開發套件AWS_XRAY_ADAPTIVE_SAMPLING_CONFIG。值必須是有效的 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