本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 設定自適應抽樣 在異常峰值期間缺少關鍵追蹤可能會使根本原因分析變得困難。不過，維持高取樣率非常昂貴。X-Ray 自適應取樣提供對異常的完整可見性，並在正常操作期間控制成本。透過適應性取樣，您可以設定最大取樣率，X-Ray 會自動在該限制內調整。X-Ray 會計算擷取錯誤追蹤所需的最低提升。如果您的基準速率擷取足夠的資料，則不會發生提升。您只需在需要時支付額外的抽樣費用。 使用自適應取樣的優點： + 完整的事件可見性 – 在事件期間取得完整的追蹤，無需手動介入。X-Ray 會自動調整取樣率以擷取錯誤追蹤，然後返回正常速率。 + 根本原因可見性 – 一律查看問題的來源。即使未觸發完整追蹤取樣，X-Ray 也會擷取重要的錯誤資料。 + 最佳化成本 – 短暫取樣提升 （最多 1 分鐘） 和自動冷卻時間可防止過度取樣。您只需為診斷問題所需的資料付費。 **Topics** + [支援的 SDKs和平台](#adaptive-sampling-supported-sdks) + [選擇您的自適應抽樣方法](#adaptive-sampling-features) + [本機 SDK 組態](#local-sdk-configuration) ## 支援的 SDKs和平台 **支援的 SDK** – 自適應取樣需要 AWS Distro for OpenTelemetry (ADOT) SDK。 **支援的語言** + Java ([2.11.5 ](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5)版或更新版本） + Python [(0.15.0 ](https://github.com/aws-observability/aws-otel-python-instrumentation/releases/tag/v0.15.0)版或更新版本） 您的應用程式必須使用支援的 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 取樣規則中啟用自適應取樣。如需詳細資訊，請參閱[自訂抽樣規則](https://docs.aws.amazon.com/xray/latest/devguide/xray-console-sampling.html#xray-console-custom)。這提供了一種集中式方法來啟用適應性抽樣，而無需修改應用程式程式碼或套用應用程式部署。當您啟用適應性取樣時，X-Ray 會在錯誤峰值或延遲極端值等異常期間自動增加取樣，同時將取樣率保持在設定的最大範圍內。 `SamplingRateBoost` 可以套用至取樣規則以外的任何自訂`Default`取樣規則。 `SamplingRateBoost` 欄位定義異常驅動取樣的上限和行為。 ``` "SamplingRateBoost": { "MaxRate": 0.25, "CooldownWindowMinutes": 10, "DisableDefaultAnomalyDetection": false } ``` `MaxRate` 定義 X-Ray 在偵測到異常時將套用的最大取樣率。值範圍為 `0.0`到 `1.0`。例如， `"MaxRate": 0.25` 允許抽樣在異常時段內增加高達 25% 的請求。X-Ray 會根據異常活動，決定基準與最大值之間的適當速率。 `CooldownWindowMinutes` 定義了只能觸發一次取樣率提升的時間範圍 （以分鐘為單位）。提升發生後，在下一個時段之前不允許進一步提升。值類型為*整數 （分鐘）*。 `DisableDefaultAnomalyDetection` 控制 ADOT 開發套件是否使用內建的預設異常條件 (HTTP 5xx 錯誤回應） 來觸發取樣提升。值類型為*布林值*，預設值為 `false`。設為 時`true`，軟體開發套件預設不會再提升 HTTP 5xx 回應的取樣。在這種情況下，提升只會由您透過 明確定義的異常條件觸發[本機 SDK 組態](#local-sdk-configuration)。當您想要完全控制什麼構成異常 （例如，僅特定錯誤代碼或延遲閾值），並想要避免在所有 5xx 回應上提升時，請使用此選項。 **具有適應性取樣的範例規則** ``` { "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 錯誤代碼**做為預設異常條件，以觸發取樣提升。您可以在 `true` `SamplingRateBoost` 欄位中將 設定為 `DisableDefaultAnomalyDetection` 以停用此預設值。 您也可以使用環境變數，在支援的 ADOT 開發套件中於本機微調異常情況。如需詳細資訊，請參閱[本機 SDK 組態](#local-sdk-configuration)。 ### 異常範圍擷取 異常範圍擷取可確保一律記錄代表異常的關鍵範圍，即使未對完整追蹤進行取樣。此功能透過專注於擷取異常本身來補充抽樣提升，而不是增加未來追蹤的抽樣。 ADOT SDK 偵測到異常時，會立即發出跨度，無論抽樣決策為何。由於 SDK 只會發出與異常相關的範圍，因此這些追蹤是部分追蹤，而不是完整的end-to-end交易。 一旦 ADOT SDK 偵測到異常跨度，它會嘗試從相同的追蹤發出盡可能多的跨度。此功能下發出的所有範圍都會以 屬性 標記`aws.trace.flag.sampled = 0`。這可讓您輕鬆地區分部分追蹤 （異常擷取） 與交易搜尋和分析中的完整追蹤 （正常抽樣）。 我們建議加入[交易搜尋](https://docs.aws.amazon.com/xray/latest/devguide/xray-transactionsearch.html)以檢視和查詢部分追蹤。下列範例顯示 [Application Signals](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Application-Monitoring-Sections.html) 主控台中的服務頁面。ServiceC 設定為異常跨度擷取，它是套用取樣提升的呼叫鏈的一部分。此組態會產生完整和部分追蹤。您可以使用 `aws.trace.flag.sampled` 屬性來區分追蹤類型。 ![異常範圍擷取](http://docs.aws.amazon.com/zh_tw/xray/latest/devguide/images/adaptive-sampling.png) 異常範圍擷取只能透過 啟用或自訂[本機 SDK 組態](#local-sdk-configuration)。 ## 本機 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 ```