翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# アダプティブサンプリングの設定
異常スパイク中に重要なトレースが見つからないと、根本原因の分析が困難になる可能性があります。ただし、高いサンプリングレートを維持するにはコストがかかります。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** – アダプティブサンプリングには AWS 、 Distro for OpenTelemetry (ADOT) SDK が必要です。
**サポートされている言語**
+ Java (バージョン [v2.11.5](https://github.com/aws-observability/aws-otel-java-instrumentation/releases/tag/v2.11.5) 以降)
+ Python (バージョン [v0.15.0](https://github.com/aws-observability/aws-otel-python-instrumentation/releases/tag/v0.15.0) 以降)
アプリケーションは、サポートされている ADOT SDK で計装し、Amazon CloudWatch エージェントまたは OpenTelemetry コレクターと一緒に実行する必要があります。
例えば、Amazon EC2、Amazon ECS、Amazon EKS は、 AWS Application Signals が ADOT SDK と Amazon CloudWatch エージェントを有効にするためのガイダンスを提供する一般的なプラットフォームです。
## アダプティブサンプリングアプローチを選択する
アダプティブサンプリングは、サンプリングブーストと異常スパンキャプチャの 2 つのアプローチをサポートしています。これらは個別に適用することも、組み合わせて適用することもできます。
### サンプリングブースト
アダプティブサンプリングブーストはサンプリングルールに基づいており、既存の X-Ray ヘッドベースのサンプリングモデルで動作します。ヘッドベースのサンプリングとは、サンプリングの決定がルートサービスで行われ、サンプリングフラグがコールチェーン内のすべてのダウンストリームのサービスに伝播されることを意味します。
+ **ルールベースのブースティング** – ブースティングは常に特定の X-Ray サンプリングルールに関連付けられます。各ルールは、独自の最大ブーストレートとクールダウン動作を定義できます。
+ **ヘッドベースのサンプリング** – サンプリングの決定はルートサービスで行われ、サンプリングフラグがコールチェーン内のすべてのダウンストリームのサービスに伝播されます。
+ **異常駆動型** – X-Ray は SDK を使用して異常統計を報告します。X-Ray は、エラーや高レイテンシーなどの異常を検出すると、これらの統計を使用して適切なブーストレート (設定された最大値まで) を計算します。
**異常レポート**
コールチェーン内のすべてのアプリケーションサービスは、必要な SDK を通じて異常統計を出力できます。
+ **ルートサービス** – サンプリングブーストを有効にするには、サポートされている SDK とプラットフォームで実行する必要があります。ルートサービスがサポートされていない場合、ブーストは行われません。
+ **ダウンストリームサービス** – ダウンストリームサービスは異常のみを報告します。サンプリングの決定を行うことはできません。ダウンストリームサービスがサポートされている SDK を実行している場合、検出された異常によってサンプリングブーストがトリガーされる可能性があります。ダウンストリームサービスがサポートされていない場合 (古い SDK の実行など)、そのサービスの異常はブーストをトリガーしません。これらのサービスは、標準のコンテキスト伝播 (W3C トレースコンテキストやバゲッジなど) に従うと、引き続きコンテキストをダウンストリームに伝播できます。これにより、さらにダウンストリームのサービスでサポートされている SDK が、ブーストをトリガーする異常をレポートできるようになります。
**ブーストのタイミングと範囲**
+ **トリガー遅延** – X-Ray が異常を検出してから 10 秒ほどでサンプリングブーストが開始されると予想できます。
+ **ブースト期間** – X-Ray がブーストをトリガーした後、基本サンプリングレートに戻るまで最大 1 分間続きます。
+ **ブーストクールダウン** – ブーストが発生すると、クールダウン期間が経過するまで、X-Ray は同じルールに対して別のブーストをトリガーしません。
例えば、`cooldown` を 10 分間に設定した場合、ブーストが終了すると、次の 10 分間のウィンドウまで新しいブーストをトリガーすることはできません。
特殊なケース: `cooldown` を 1 分間に設定すると、ブースト自体が最大 1 分間続く可能性があるため、異常が持続するとブーストを効果的かつ連続的にトリガーできます。
**注記**
ルートサービスでサポートされている SDK とプラットフォームを使用します。サンプリングブーストは、サポートされている SDK とプラットフォームでのみ機能します。サンプリングブーストは異常トレースをキャプチャする可能性が高いですが、すべての異常トレースをキャプチャするとは限りません。
**可視性の向上**
サンプリングルールがアダプティブサンプリングブーストで設定されている場合、X-Ray はブーストアクティビティをモニタリングできる提供されたメトリクスを自動的に出力します。
+ **メトリクス名** – `SamplingRate`
+ **ディメンション** – `RuleName` (実際のルール名に設定)
`SamplingRateBoost` が有効になっている各ルールは、ベースラインレートと一時的なブーストの両方を含む有効なサンプリングレートを発行します。これにより、次のことが可能になります。
+ ブーストがトリガーされるタイミングを追跡する
+ 各ルールの有効なサンプリングレートをモニタリングする
+ ブーストをアプリケーションの異常 (エラースパイクやレイテンシーイベントなど) と関連付ける
これらのメトリクスは、**Amazon CloudWatch Metrics の AWS/X-Ray 名前空間で表示できます。メトリクス値は、有効なサンプリングレートを表す 0～1 の浮動小数点数です**。
**X-Ray サンプリングルールを使用してサンプリングブーストを設定する**
新しい `SamplingRateBoost` フィールドを追加することで、既存の X-Ray サンプリングルールでアダプティブサンプリングを直接有効にできます。詳細については、「[Customizing sampling rules](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` は、1 つのサンプリングレートブーストのみをトリガーできる時間枠 (分単位) を定義します。ブーストが発生すると、次のウィンドウまでそれ以上ブーストは許可されません。値タイプは*整数 (分)* です。
は、ADOT SDK が組み込みのデフォルトの異常条件 (HTTP 5xx 障害レスポンス) を使用してサンプリングブーストをトリガーするかどうか`DisableDefaultAnomalyDetection`を制御します。値タイプは*ブール*値で、デフォルトは です`false`。に設定すると`true`、SDK はデフォルトで 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 分に 1 回のみ行われます。
**異常条件の設定**
異常条件設定が指定されていない場合、ADOT SDK はデフォルトの異常条件として **HTTP 5xx エラーコード**を使用してサンプリングブーストをトリガーします。このデフォルトを無効にするには、 `SamplingRateBoost`フィールド`true`で `DisableDefaultAnomalyDetection` を に設定します。
環境変数を使用して、サポートされている ADOT SDK で異常条件をローカルでファインチューニングすることもできます。詳細については、「[SDK のローカル設定](#local-sdk-configuration)」を参照してください。
### 異常スパンのキャプチャ
異常スパンのキャプチャにより、完全なトレースがサンプリングされていない場合でも、異常を表す重要なスパンが常に記録されます。この機能は、将来のトレースのサンプリングを増やすのではなく、異常自体のキャプチャに焦点を当てることで、サンプリングブーストを補完します。
ADOT SDK が異常を検知すると、サンプリングの決定に関係なく、そのスパンがすぐに出力されます。SDK は異常に関連するスパンのみを出力するため、これらのトレースは完全なエンドツーエンドのトランザクションではなく部分的なトレースです。
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` 属性を使用して、トレースタイプを区別できます。
異常スパンのキャプチャは、[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` – 過剰なスパンボリュームを防ぐため、1 秒あたりにキャプチャされた異常スパンを持つトレースの最大数 (anomalyCaptureLimit が存在しない場合、デフォルト値は 1)
**注記**
`AnomalyConditions` は、サンプリングブースト (HTTP 5xx) のデフォルトの異常条件を**上書き**します。ローカル設定の使用中にデフォルト条件を保持する場合は、`AnomalyConditions` の任意の項目に明示的に含める必要があります。
各 `anomalyConditions` 項目について:
`operations` フィールドを**省略**すると、条件は**すべてのオペレーション** (サービスレベル) に適用されます。
`operations` フィールドが存在するものの、**空のリスト**に設定されている場合、条件は**オペレーションに適用されず**、その項目はオペレーションなしになります。
`errorCodeRegex` と `highLatencyMs` の両方を省略すると、条件には評価すべき異常基準がなく、その項目はオペレーションなしになります。
論理関係:
`anomalyConditions` の項目間の関係は **OR** です。
1 つの項目内では、複数のフィールド (`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 の場合、ポッド仕様内の環境変数をネストされた 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
```