AWS X-Ray
開発者ガイド

X-Ray API でのサンプリングルールの使用

AWS X-Ray SDK は、X-Ray API を使用してサンプリングルールの取得、サンプリング結果の報告、およびクォータの取得を行います。これらの API を使用すれば、サンプリングルールの仕組みを理解したり、X-Ray SDK でサポートされていない言語でサンプリングを実行したりできます。

まず、GetSamplingRules を使用してすべてのサンプリングルールを取得します。

$ aws xray get-sampling-rules { "SamplingRuleRecords": [ { "SamplingRule": { "RuleName": "Default", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/Default", "ResourceARN": "*", "Priority": 10000, "FixedRate": 0.01, "ReservoirSize": 0, "ServiceName": "*", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 0.0, "ModifiedAt": 1530558121.0 }, { "SamplingRule": { "RuleName": "base-scorekeep", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/base-scorekeep", "ResourceARN": "*", "Priority": 9000, "FixedRate": 0.1, "ReservoirSize": 2, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "*", "URLPath": "*", "Version": 1, "Attributes": {} }, "CreatedAt": 1530573954.0, "ModifiedAt": 1530920505.0 }, { "SamplingRule": { "RuleName": "polling-scorekeep", "RuleARN": "arn:aws:xray:us-east-1::sampling-rule/polling-scorekeep", "ResourceARN": "*", "Priority": 5000, "FixedRate": 0.003, "ReservoirSize": 0, "ServiceName": "Scorekeep", "ServiceType": "*", "Host": "*", "HTTPMethod": "GET", "URLPath": "/api/state/*", "Version": 1, "Attributes": {} }, "CreatedAt": 1530918163.0, "ModifiedAt": 1530918163.0 } ] }

出力には、デフォルトルールとカスタムルールが含まれています。まだサンプリングルールを作成していない場合は、「サンプリングルール」を参照してください。

優先度の昇順で受信リクエストのルールを評価します。ルールが一致したら、固定レートとリザーバのサイズを使用してサンプリングデシジョンを作成します。サンプリングされたリクエストを記録し、(トレースを目的とする) サンプリングされていないリクエストは無視します。サンプリングデシジョンが作成されたら、ルールの評価を停止します。

ルールのリザーバのサイズは、固定レートを適用する前に記録する 1 秒あたりのトレースの目標数です。リザーバはすべてのサービスに累積的に適用されるため、直接使用することはできません。ただし、0 以外の場合は、X-Ray がクォータを割り当てるまでリザーバから 1 秒に 1 個トレースを借りることが可能です。クォータを受信する前に、1 秒ごとに最初のリクエストを記録し、追加のリクエストに固定レートを適用します。固定レートは、0~1.00 (100%) の 10 進数です。

次の例は、過去 10 秒間に作成されたサンプリングデシジョンの詳細を含む GetSamplingTargets の呼び出しを示したものです。

$ aws xray get-sampling-targets --sampling-statistics-documents '[ { "RuleName": "base-scorekeep", "ClientID": "ABCDEF1234567890ABCDEF10", "Timestamp": "2018-07-07T00:20:06, "RequestCount": 110, "SampledCount": 20, "BorrowCount": 10 }, { "RuleName": "polling-scorekeep", "ClientID": "ABCDEF1234567890ABCDEF10", "Timestamp": "2018-07-07T00:20:06", "RequestCount": 10500, "SampledCount": 31, "BorrowCount": 0 } ]' { "SamplingTargetDocuments": [ { "RuleName": "base-scorekeep", "FixedRate": 0.1, "ReservoirQuota": 2, "ReservoirQuotaTTL": 1530923107.0, "Interval": 10 }, { "RuleName": "polling-scorekeep", "FixedRate": 0.003, "ReservoirQuota": 0, "ReservoirQuotaTTL": 1530923107.0, "Interval": 10 } ], "LastRuleModification": 1530920505.0, "UnprocessedStatistics": [] }

X-Ray からのレスポンスには、リザーバから借りる代わりに使用するクォータが含まれています。この例では、サービスがリザーバから 10 秒間に 10 個のトレースを借り、他の 100 個のリクエストに 10% の固定レートを適用した結果、サンプリングされたリクエストの合計数が 20 個になりました。クォータは (有効期限で示される) 5 分間、または新しいクォータが割り当てられるまで有効です。また、ここで割り当てられなかったとしても、X-Ray がデフォルトより長いレポート間隔を割り当てる場合があります。

注記

最初の呼び出しのときには、X-Ray からのレスポンスにクォータが含まれていない可能性があります。その場合は、クォータが割り当てられるまで、リザーバからクォータを借り続けてください。

レスポンスの他の 2 つのフィールドは、入力の問題を示している可能性があるため、前回呼び出した GetSamplingRulesLastRuleModification を確認します。より新しい場合は、そのルールの新しいコピーを取得します。UnprocessedStatistics には、ルールが削除されたこと、入力の統計ドキュメントが古すぎること、またはアクセス許可のエラーが発生していることを示すエラーが含まれている可能性があります。