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

# 透過 X-Ray API 使用取樣規則
<a name="xray-api-sampling"></a>



SDK AWS X-Ray 使用 X-Ray API 來取得取樣規則、報告取樣結果，以及取得配額。您可以使用這些 APIs 來進一步了解抽樣規則的運作方式，或以 X-Ray SDK 不支援的語言實作抽樣。

從使用 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 取得所有抽樣規則開始。

```
$ 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
        }
    ]
}
```

輸出會包含預設規則和自訂規則。若您尚未建立抽樣規則，請參閱[抽樣規則](xray-api-configuration.md#xray-api-configuration-sampling)。

依照遞增優先順序排序，針對傳入請求評估規則。當規則相符時，使用固定速率和儲槽大小來進行抽樣決策。記錄抽樣請求並忽略 (針對追蹤用途) 未抽樣請求。在完成抽樣決策後停止評估規則。

規則儲槽大小是在套用固定速率前，每秒要記錄的追蹤目標數。儲槽會累積套用到所有服務，因此您無法直接使用它。不過，如果不是零，您可以從儲槽借用每秒一個追蹤，直到 X-Ray 指派配額為止。在接收配額前，記錄每秒的第一個請求，然後將固定速率套用到其他請求。固定速率是介於 0 和 1.00 (100%) 間的十進位數。

以下範例會顯示對 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingTargets.html) 發出的呼叫，其中包含在過去 10 秒間進行的抽樣決策詳細資訊。

```
$ 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 個追蹤，並將 10% 的固定速率套用到其他 100 個請求，其結果合計為 20 個抽樣請求。配額有效期為五分鐘 （以存留時間表示） 或直到指派新的配額為止。X-Ray 也可能指派比預設值更長的報告間隔，雖然不是在這裡。

**注意**  
第一次呼叫時，來自 X-Ray 的回應可能不會包含配額。繼續從儲存借用，直到您獲得指派配額。

回應中的其他兩個欄位可能會指出輸入的問題。針對您最後一次呼叫 [https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html](https://docs.aws.amazon.com/xray/latest/api/API_GetSamplingRules.html) 檢查 `LastRuleModification`。若其較新，請取得規則的新複本。`UnprocessedStatistics` 可包含錯誤，指出規則已遭到刪除、輸入中的統計文件過舊，或是許可錯誤。