このドキュメントでは、Distribution 値のタイプを使用する指標データのパーセンタイルとヒストグラム モデルについて説明します。分布指標は、バケットと呼ばれる値の範囲を定義し、各バケットに分類される測定値の数を記録します。分布指標は、個々の測定値をレポートしません。バケット内のカウントのヒストグラムをレポートします。この値タイプは、個別測定値があまりに多すぎて収集できないが、測定値に関する統計情報（平均やパーセンタイルなど）に価値がある場合にサービスによって使用されます。
このページの次のセクションでは、パーセンタイルの決定方法を示す合成例を使用します。この例は、パーセンタイル値がバケット数、バケットの幅、測定値の分布、サンプルの総数に依存することを示しています。パーセンタイル値はヒストグラムで使用できないため、この値は実際の測定値に依存しません。
合成データを使用した例
スケールが 1、増加係数が 2、10 個の有限バケットを持つ Exponential バケットモデルについて考えてみます。このヒストグラムには、12 個のバケット、10 個の有限バケット、上限のみを指定する 1 つのバケット、下限のみを指定する 1 つのバケットが含まれます。この例では、インデックスが n+1 の有限バケットの幅は、インデックスが n の有限バケットの 2 倍になります。
次の例では、計算されたパーセンタイルと測定値の間の最大エラーがバケットの幅によって、決まることを示しています。また、ヒストグラム内のサンプル数の重要性も示しています。たとえば、サンプル数が 20 未満の場合、95 パーセンタイルと 99 パーセンタイルは常に同じバケットに配置されます。
ケース 1: サンプルの総数は 1 です。
測定値が 1 つでもある場合、3 つのパーセンタイル値は異なりますが、同じバケットの 50、95、および 99 パーセンタイルのみが表示されます。測定値が不明なため、推定値と実際の測定値の間の誤差を特定できません。
たとえば、次の表に示すような測定値のヒストグラムがあるとします。
| バケット番号 | 下限 | 上限 | カウント | パーセンタイル範囲 |
|---|---|---|---|---|
| 0 | 1 | 0 | 0 | |
| 1 | 1 | 2 | 0 | 0 |
| 2 | 2 | 4 | 0 | 0 |
| 3 | 4 | 8 | 0 | 0 |
| 4 | 8 | 16 | 0 | 0 |
| 5 | 16 | 32 | 0 | 0 |
| 6 | 32 | 64 | 0 | 0 |
| 7 | 64 | 128 | 0 | 0 |
| 8 | 128 | 256 | 1 | 0 - 100 |
| 9 | 256 | 512 | 0 | 0 |
| 10 | 512 | 1024 | 0 | 0 |
| 11 | 1024 | 0 | 0 |
50 パーセンタイルを計算するには、次のようにします。
- バケット カウントを使用して、50 パーセンタイルを含むバケットを特定します。この例では、バケット番号 8 に 50 パーセンタイルが含まれます。
次のルールを使用して推定値を計算します。
pth percentage = bucket_low + (bucket_up - bucket_low)*(p - p_low)/(p_up - p_low)前の式では、
p_lowとp_upはバケットのパーセンタイル範囲の下限と上限です。同様に、bucket_lowとbucket_upはバケットの下限と上限です。p_lowとp_upの値は、異なるバケット間でカウントが分配される方法によって異なります。
たとえば、50 パーセンタイルは次のように計算されます。
50th percentile = 128 + (256-128)*(50-0)/(100-0)
= 128 + 128 * 50 / 100
= 128 + 64
= 192
95 パーセンタイルを計算するには、前の式の 50 を 95 に置き換えます。サンプルが 1 つだけのこの例の場合、パーセンタイルは次のようになります。
| パーセンタイル | バケット番号 | 値 |
|---|---|---|
| 50 | 8 | 192 |
| 95 | 8 | 249.6 |
| 99 | 8 | 254.7 |
推定値と実際の測定値との間の誤差は制限できますが、測定値が不明なため特定はできません。
ケース 2: サンプルの総数は 10 です。
サンプルが 10 ある場合、50 パーセンタイルは 95 パーセンタイルや 99 パーセンタイルとは異なるバケットに入る場合があります。ただし、95 パーセンタイルと 99 パーセンタイルを異なるバケットに入れるには、まだ十分な測定結果がありません。
たとえば、次の表に示すような測定値のヒストグラムがあるとします。
| バケット番号 | 下限 | 上限 | カウント | パーセンタイル範囲 |
|---|---|---|---|---|
| 0 | 1 | 4 | 0 - 40 | |
| 1 | 1 | 2 | 2 | 40 - 60 |
| 2 | 2 | 4 | 1 | 60 - 70 |
| 3 | 4 | 8 | 1 | 70 - 80 |
| 4 | 8 | 16 | 1 | 80 - 90 |
| 5 | 16 | 32 | 0 | 0 |
| 6 | 32 | 64 | 0 | 0 |
| 7 | 64 | 128 | 0 | 0 |
| 8 | 128 | 256 | 1 | 90 - 100 |
| 9 | 256 | 512 | 0 | 0 |
| 10 | 512 | 1024 | 0 | 0 |
| 11 | 1024 | 0 | 0 |
前述の手順を使用して、50、95、99 パーセンタイルを計算できます。たとえば、バケット番号 1 の 50 パーセンタイルは次のように計算されます。
50th percentile = 1 + (2-1)*(50-40)/(60-40)
= 1 + (1 * 10 / 20)
= 1 + 0.5
= 1.5
同様に、95 パーセンタイルは次のように計算されます。
95th percentile = 128 + (256-128)*(95-90)/(100-90)
= 128 + 128 * 5 / 10
= 128 + 64
= 192
前に説明したプロセスを使用することで、パーセンタイルを計算できます。次の表の各行には、パーセンタイル、対応するバケット、計算された値が一覧表示されています。
| パーセンタイル | バケット番号 | 値 | 最大誤差 |
|---|---|---|---|
| 50 | 1 | 1.5 | 0.5 |
| 95 | 8 | 192 | 74 |
| 99 | 8 | 243.2 | 115.2 |
この例と前の例では、95 パーセンタイルはバケット番号 8 です。ただし、パーセンタイルの計算は異なります。違いは、サンプルの分布方法によるものです。最初の例では、すべてのサンプルが同じバケットにありますが、最新の例では、サンプルは異なるバケットにあります。
実際のデータを使用した例
このセクションでは、特定の指標で使用されるバケットモデルを決定する方法についての例を示します。また、計算されたパーセンタイル値で潜在的なエラーを評価する方法についても説明します。
バケットモデルを識別する
特定の時間間隔で指標に使用されるバケットを決定するには、Cloud Monitoring API の projects.timeSeries/list メソッドを呼び出します。
たとえば、指標のバケットモデルを特定するには、次のようにします。
- ウェブページ
projects.timeSeries/listに移動します。 API Explorer に、指標、開始時間、終了時間を指定するフィルタを入力します。
たとえば、API リクエストのレイテンシを保存する指標に関する情報を取得するには、次のように入力します。
metric.type="serviceruntime.googleapis.com/api/request_latencies" resource.type="consumed_api"この例では、フィルタ フィールドで指標タイプとリソースタイプが指定されています。これらのフィルタの詳細については、モニタリング フィルタをご覧ください。
Enter キーを押します。
1 つの Google Cloud プロジェクトで使用可能な分布値の指標の list API レスポンスは次のとおりです。
{
"timeSeries": [
{
"metric": {...},
"resource": {...},
},
"metricKind": "DELTA",
"valueType": "DISTRIBUTION",
"points": [
{
"interval": {
"startTime": "2020-11-03T15:05:00Z",
"endTime": "2020-11-03T15:06:00Z"
},
"value": {
"distributionValue": {
"count": "3",
"mean": 25.889,
"bucketOptions": {
"exponentialBuckets": {
"numFiniteBuckets": 66,
"growthFactor": 1.4,
"scale": 1
}
},
"bucketCounts": [
"0",
"0",
"0",
"0",
"0",
"0",
"0",
"0",
"0",
"0",
"3"
]
}
}
},
API のレスポンスで、value フィールドは points 配列に格納されるデータを表します。count フィールドと mean フィールドは、指定された期間に 3 つの測定値が存在し、平均値が 25.889 であったとレポートします。bucketOptions フィールドは、指数モデルが 66 バケットを持ち、スケールが 1、増加係数が 1.4 であることを示しています。
インデックス n のバケットの下限と上限を計算するには、次のルールを使用します。
- 下限（1 ≤ n < N）= スケール *（増加係数）（n-1）
- 上限（0 ≤ n < N-1） = スケール *（増加係数）n
前の式では、N はバケットの合計数です。
次の表に、この指標のバケットと各バケットの中間値を示します。
| n 番目のバケット | 下限 | 上限 | 中間値 |
|---|---|---|---|
| 0 | 1 | 該当なし | |
| 1 | 1 | 1.40 | 1.20 |
| 2 | 1.40 | 1.96 | 1.68 |
| ... | |||
| 9 | 14.76 | 20.66 | 17.71 |
| 10 | 20.66 | 28.93 | 24.79 |
| 11 | 28.93 | 40.50 | 34.71 |
| ... |
パーセンタイルの計算を確認する
バケットの構成が把握できたので、すべての測定結果で、50、95、99 パーセンタイルの値を予測できます。たとえば、サンプルが 1 つあり、バケット番号 10 にある場合、50 パーセンタイル値は 24.79 になります。
指標の 50、95、99 パーセンタイル値を取得するには、API メソッド projects.timeSeries/list を使用して、アライメント期間と整列指定子を指定します。この例では、次の設定が選択されています。
- アライナー:
ALIGN_PERCENTILE_50、ALIGN_PERCENTILE_95、またはALIGN_PERCENTILE_99 - アライメント期間: 60 秒
ALIGN_PERCENTILE_50 の選択の場合、時系列の各値はバケットの 50 パーセンタイルです。
{
"timeSeries": [
{
"metric": {...},
"resource": {...},
"metricKind": "GAUGE",
"valueType": "DOUBLE",
"points": [
{
"interval": {
"startTime": "2020-11-03T15:06:36Z",
"endTime": "2020-11-03T15:06:36Z"
},
"value": {
"doubleValue": 24.793256140799986
}
},
{
"interval": {
"startTime": "2020-11-03T15:05:36Z",
"endTime": "2020-11-03T15:05:36Z"
},
"value": {
"doubleValue": 34.710558597119977
}
},
{
"interval": {
"startTime": "2020-11-03T15:04:36Z",
"endTime": "2020-11-03T15:04:36Z"
},
"value": {
"doubleValue": 24.793256140799986
}
}
]
},
2 つのサンプルでは、50 パーセンタイルはバケット 10 にあり、もう一つのサンプルはバケット 11 にあります。
次の表は、異なる整列指定子を使用して projects.timeSeries/list メソッドを実行した結果を示しています。最初の行は、整列指定子が指定されていないケースに対応します。再列指定子を指定しない場合、バケットモデルと平均値が返されます。次の 3 行には、整列指定子が ALIGN_PERCENTILE_50、ALIGN_PERCENTILE_95、ALIGN_PERCENTILE_99 に設定されている場合に返されるデータが一覧表示されます。
| 統計情報 | Sample @ 15:06 | Sample @ 15:05 | Sample @ 15:04 |
|---|---|---|---|
| mean | 25.889 | 33.7435 | 利用できません。 |
| 50 パーセンタイル | 24.79 | 34.71 | 24.79 |
| 95 パーセンタイル | 28.51 | 39.91 | 28.51 |
| 99 パーセンタイル | 28.84 | 40.37 | 28.84 |
合成データを使用した 2 つの例が示すように、パーセンタイルの値は、サンプルの分布方法によって異なります。すべてのサンプルがサンプル バケットにある場合、50 パーセンタイルはそのバケットの中間点になります。ただし、サンプルが異なるバケットにある場合、その分布は推定値に影響します。
50 パーセンタイルが平均の妥当な推定値であるかどうかを判断するには、平均値を 50 パーセンタイルと比較します。平均値はバケットの詳細とともに返されます。
次のステップ
分布値の指標を可視化する方法については、分布値の指標についてをご覧ください。