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

# 設定 取樣規則
<a name="xray-console-sampling"></a>

您可以使用 AWS X-Ray 主控台來設定 服務的取樣規則。 AWS Distro for OpenTelemetry、X-Ray SDK 和 AWS 服務 支援具有取樣組態的[主動追蹤](xray-services.md)，使用取樣規則來決定要記錄哪些請求。

**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)

## 設定 取樣規則
<a name="xray-console-config"></a>

您可以針對下列使用案例設定取樣：
+ **API Gateway Entrypoint** – API Gateway 支援取樣和主動追蹤。若要在 API 階段上啟用主動追蹤，請參閱 [的 Amazon API Gateway 主動追蹤支援 AWS X-Ray](xray-services-apigateway.md)。
+ **AWS AppSync** – AWS AppSync 支援取樣和主動追蹤。若要啟用請求的 AWS AppSync 主動追蹤，請參閱[使用 AWS X-Ray 追蹤](https://docs.aws.amazon.com/appsync/latest/devguide/x-ray-tracing.html)。
+ **AWS Step Functions** – AWS Step Functions 支援取樣和主動追蹤。若要在狀態機器上 AWS Step Functions 啟用主動追蹤，請參閱 [Step Functions 中的 X-Ray 追蹤](https://docs.aws.amazon.com/step-functions/latest/dg/concepts-xray-tracing.html)。
+ **運算平台上的 Instrument AWS Distro for OpenTelemetry ** – 使用 Amazon EC2、Amazon ECS 或 等運算平台時 AWS Elastic Beanstalk，當應用程式已使用最新的 AWS Distro for OpenTelemetry 或 X-Ray SDK 進行檢測時，支援取樣。

## 自訂抽樣規則
<a name="xray-console-custom"></a>

透過自訂抽樣規則，您可以控制記錄的資料量。您也可以修改抽樣行為，而無需修改或重新部署程式碼。取樣規則會告知 AWS Distro for OpenTelemetry (ADOT) 或 X-Ray SDK 要針對一組條件記錄多少請求。根據預設，軟體開發套件每秒會記錄第一個請求，以及任何額外請求的 5%。每秒一個請求是*儲槽*。這可確保只要服務持續提供請求，每秒都會記錄至少一個追蹤。5% 是超過儲槽大小的額外請求抽樣「速率」**。

您可以設定 X-Ray 開發套件，從程式碼隨附的 JSON 文件讀取抽樣規則。但是，當您執行服務的多個執行個體時，每個執行個體都會獨立執行抽樣。這會導致抽樣請求的整體百分比增加，因為所有執行個體的儲槽都會加在一起。此外，若要更新本機取樣規則，您必須重新部署程式碼。

透過在 X-Ray 主控台中定義抽樣規則，並將 [SDK 設定為](#xray-console-sampling-service)從 X-Ray 服務讀取規則，您可以避免這兩個問題。服務會管理每個規則的儲槽，並根據執行中的執行個體數，將配額指派給每個服務執行個體來平均分散儲槽。儲槽限制是根據您設定的規則所計算。由於規則是在 服務中設定，因此您可以管理規則，而無需進行其他部署。

**注意**  
設定取樣規則時，請務必了解 X-Ray 取樣是「父系型」。這表示抽樣決策只會做出一次，通常是由處理請求的第一個X-Ray-enabled的服務 (「根」服務） 做出。  
如果下游服務收到已擁有上游父項取樣決策的請求，無論其自己的任何相符取樣規則為何，都會遵守該決策。  
規則套用時：您的自訂抽樣規則只會在尚未做出抽樣決策的服務上生效。這通常適用於：  
應用程式的進入點 （例如 API Gateway、Load Balancer 或第一個經檢測的微服務）。
啟動全新追蹤的非同步程序或工作者。
常見缺陷：如果您為「服務 B」建立嚴格的取樣規則，但「服務 A」一律會呼叫「服務 B」，則您的服務 B 規則可能永遠不會套用，因為它只是遵循服務 A 傳遞的決定。若要變更此工作流程的追蹤取樣，您必須將取樣規則設定為根服務 （服務 A)。

**注意**  
X-Ray 使用最盡力的方法套用抽樣規則，在某些情況下，有效的抽樣率可能不會完全符合設定的抽樣規則。不過，隨著時間的推移，取樣的請求數量應該接近設定的百分比。

您現在可以從 Amazon CloudWatch 主控台設定 X-Ray 抽樣規則。

**在 CloudWatch 主控台中設定抽樣規則**

1. 登入 AWS 管理主控台 ，並在 https：//[https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/) 開啟 CloudWatch 主控台。

1. 在**設定**下方的左側導覽窗格中選擇**設定**。

1. 選擇 **X-Ray 追蹤**區段中**取樣規則**下的**檢視設定**。

1. 若要建立規則，請選擇 **Create sampling rule (建立抽樣規則)**。

   若要編輯規則，請選擇規則，然後選擇**編輯**以進行編輯。

   若要刪除規則，請選擇規則，然後選擇**刪除**以刪除規則。

## 抽樣規則選項
<a name="xray-console-sampling-options"></a>

下列選項可用於每個規則。字串值可以使用萬用字元來以符合單一字元 (`?`) 或零或多個字元 (`*`)。

**抽樣規則選項**
+ **規則名稱** （字串） – 規則的唯一名稱。
+ **優先順序** （介於 1 和 9999 之間的整數） – 取樣規則的優先順序。服務會以遞增的優先順序來評估規則，並使用符合的第一個規則來決定取樣決策。
+ **儲存器 **（非負整數） – 套用固定速率之前，每秒要檢測的比對請求固定數量。儲槽不會直接用於服務，而是集體套用至使用該規則的所有服務。
+ **速率** （介於 0 到 100 之間的整數） – 在儲槽用盡之後，與檢測相符的請求百分比。在主控台中設定取樣規則時，請選擇介於 0 到 100 之間的百分比。使用 JSON 文件在用戶端 SDK 中設定取樣規則時，請提供介於 0 和 1 之間的百分比值。
+ **服務名稱** （字串） – 檢測服務的名稱，如追蹤映射中所示。
  + X-Ray SDK – 您在記錄器上設定的服務名稱。
  + Amazon API Gateway – `api-name/stage`。
+ **服務類型** （字串） – 顯示在追蹤映射中的服務類型。對於 X-Ray 開發套件，請套用適當的外掛程式來設定服務類型：
  + `AWS::ElasticBeanstalk::Environment` – AWS Elastic Beanstalk 環境 （外掛程式）。
  + `AWS::EC2::Instance` – Amazon EC2 執行個體 （外掛程式）。
  + `AWS::ECS::Container` – Amazon ECS 容器 （外掛程式）。
  + `AWS::EKS::Container` – Amazon EKS 容器 （外掛程式）。
  + `AWS::APIGateway::Stage` – Amazon API Gateway 階段。
  + `AWS::AppSync::GraphQLAPI ` – AWS AppSync API 請求。
  + `AWS::StepFunctions::StateMachine` – AWS Step Functions 狀態機器。
+ **主機** （字串） – 來自 HTTP 主機標頭的主機名稱。
+ **HTTP 方法** （字串） – HTTP 請求的方法。
+ **URL 路徑** （字串） – 請求的 URL 路徑。
  + X-Ray SDK – HTTP 請求 URL 的路徑部分。
+ **資源 ARN** （字串） – 執行服務之 AWS 資源的 ARN。
  + X-Ray SDK – 不支援。軟體開發套件僅能使用 **Resource ARN (資源 ARN)** 設為 `*` 的規則。
  + Amazon API Gateway – 階段 ARN。
+ （選用） **屬性 **（索引鍵和值） – 取樣決策時已知的區段屬性。
  + X-Ray SDK – 不支援。軟體開發套件會忽略指定屬性的規則。
  + Amazon API Gateway – 來自原始 HTTP 請求的標頭。
+ （選用） **SamplingRateBoost** （物件） – 控制異常驅動的取樣提升行為。
  + MaxRate （介於 0 和 100 之間的整數） – 在異常期間，X-Ray 可能會增加到
  + CooldownWindowMinutes （大於 0 的整數） – 只能觸發一次提升的時段 （分鐘），防止持續提升

## 抽樣規則範例
<a name="xray-console-sampling-examples"></a>

**Example – 預設規則，沒有儲槽且速率低**  
您可以修改預設規則的儲槽和速率。預設規則會套用至不符合任何其他規則的請求。  
+ **儲存庫**： **0**
+ **速率**：**5**(**0.05**如果使用 JSON 文件設定）

**Example – 偵錯規則以追蹤有問題路由的所有請求**  
會暫時套用高優先順序的規則來進行除錯。  
+ **規則名稱**： **DEBUG – history updates**
+ **優先順序**： **1**
+ **儲存庫**： **1**
+ **速率**：**100**(**1**如果使用 JSON 文件設定）
+ **服務名稱**： **Scorekeep**
+ **Service type (服務類型)：****\$1**
+ **主機**： **\$1**
+ **HTTP 方法**： **PUT**
+ **URL 路徑**： **/history/\$1**
+ **資源 ARN**： **\$1**

**Example – POSTs的較高最低速率**  
+ **規則名稱**： **POST minimum**
+ **優先順序**： **100**
+ **儲存庫**： **10**
+ **速率**：**10**(**.1**如果使用 JSON 文件設定）
+ **服務名稱**： **\$1**
+ **Service type (服務類型)：****\$1**
+ **主機**： **\$1**
+ **HTTP 方法**： **POST**
+ **URL 路徑**： **\$1**
+ **資源 ARN**： **\$1**

**Example 啟用異常驅動提升**  
設定在異常期間觸發取樣提升高達 50% 的規則，冷卻時間為 10 分鐘。  
+ **規則名稱**： **MyAdaptiveRule**
+ **優先順序**： **100**
+ **儲存庫**： **1**
+ **FixedRate**： **0.0510**
+ **服務名稱**： **\$1**
+ **Service type (服務類型)：****\$1**
+ **主機**： **\$1**
+ **HTTP 方法**： **POST**
+ **URL 路徑**： **\$1**
+ **maxRate**： **0.5**
+ **cooldownWindowMinutes**： **10**

## 將您的服務設定為使用抽樣規則
<a name="xray-console-sampling-service"></a>

 AWS Distro for OpenTelemetry (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 JavaScript [使用 X-Ray 遠端取樣](https://aws-otel.github.io/docs/getting-started/js-sdk/trace-metric-auto-instr#using-x-ray-remote-sampling) 
+ 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：搭配 ADOT .NET [使用 X-Ray 遠端取樣](https://aws-otel.github.io/docs/getting-started/dotnet-sdk/auto-instr#using-x-ray-remote-sampling) 

如需 API Gateway，請參閱 [的 Amazon API Gateway 主動追蹤支援 AWS X-Ray](xray-services-apigateway.md)。

## 檢視抽樣結果
<a name="xray-console-sampling-results"></a>

X-Ray 主控台**取樣**頁面顯示服務如何使用每個取樣規則的詳細資訊。

**Trend (趨勢)** 資料行會顯示過去幾分鐘內使用規則的方式。每個資料行都會顯示 10 秒間的統計資料。

**抽樣統計資料**
+ **符合的規則總數**：符合此規則的請求數量。此數量不包含本來會和此規則相符，但是卻先符合高優先順序規則的請求。
+ **取樣總數**：記錄的請求數。
+ **以固定速率取樣**：套用規則固定速率取樣的請求數。
+ **使用儲槽限制取樣**：使用 X-Ray 指派的配額取樣的請求數量。
+ **從儲槽借用**：透過從儲槽借用取樣的請求數量。服務第一次將請求符合規則時，X-Ray 尚未為其指派配額。不過，如果儲槽至少為 1，服務會借用每秒一個追蹤，直到 X-Ray 指派配額為止。

如需抽樣統計資料和服務使用抽樣規則方式的詳細資訊，請參閱[透過 X-Ray API 使用取樣規則](xray-api-sampling.md)。

## 後續步驟
<a name="xray-console-sampling-nextsteps"></a>

您可以使用 X-Ray API 來管理抽樣規則。透過 API，您可以透過編寫程式設計的方式在排程上建立及更新規則，或是回應警示或通知。如需說明及其他規則範例，請參閱[使用 AWS X-Ray API 設定取樣、群組和加密設定](xray-api-configuration.md)。

 AWS Distro for OpenTelemetry、X-Ray SDK 和 AWS 服務 也使用 X-Ray API 來讀取抽樣規則、報告抽樣結果，以及取得抽樣目標。當請求符合 X-Ray 尚未為服務指派配額的規則時，服務必須追蹤其套用每個規則的頻率、根據優先順序評估規則，以及從儲槽借用。如需服務使用 API 進行抽樣的詳細資訊，請參閱[透過 X-Ray API 使用取樣規則](xray-api-sampling.md)。

當 AWS Distro for OpenTelemetry 或 X-Ray SDK 呼叫取樣 APIs時，他們會使用 CloudWatch 代理程式做為代理。如果您已使用 TCP 連接埠 2000，您可以設定代理程式在不同連接埠上執行代理。如需詳細資訊，請參閱 [CloudWatch 代理程式安裝指南](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html)。