パーセンタイルと分布値の指標

このドキュメントでは、型が Distribution 値の指標データのパーセンタイルとヒストグラム モデルを理解する方法について説明します。分布指標は、バケットと呼ばれる値の範囲を定義し、各バケットに分類される測定値の数を記録します。分布指標は、個々の測定値をレポートしません。バケット内のカウントのヒストグラムをレポートします。この値の型は、個別測定値があまりに多すぎて収集できないが、測定値に関する統計情報（平均やパーセンタイルなど）に価値がある場合にサービスによって使用されます。

このページの次のセクションでは、パーセンタイルの決定方法を示す合成例を使用します。この例は、パーセンタイル値がバケット数、バケットの幅、測定値の分布、サンプルの総数に依存することを示しています。パーセンタイル値はヒストグラムで使用できないため、この値は実際の測定値に依存しません。

合成データを使用した例

スケールが 1、増加係数が 2、有限バケット数が 10 の Exponential バケットモデルについて考えてみます。このヒストグラムには 12 個のバケットが含まれています。有限バケットが 10 個、上限のみを指定するバケットが 1 個、下限のみを指定するバケットが 1 個です。この例では、インデックスが n+1 の有限バケットの幅は、インデックスが n の有限バケットの 2 倍になります。

次の例は、計算されたパーセンタイルと測定値の間の最大誤差がバケットの幅によって決まることを示しています。また、ヒストグラム内のサンプル数の重要性も示しています。たとえば、サンプル数が 20 未満の場合、95 パーセンタイルと 99 パーセンタイルは常に同じバケットに配置されます。

ケース 1: サンプルの総数は 1 です。

測定値が 1 つでもある場合、3 つのパーセンタイル値は異なりますが、同じバケットの 50、95、および 99 の各パーセンタイルのみが表示されます。測定値が不明なため、推定値と実際の測定値の間の誤差を特定できません。

たとえば、次の表に示すような測定値のヒストグラムがあるとします。

50 パーセンタイルを計算する手順は次のとおりです。

1. バケット カウントを使用して、50 パーセンタイルを含むバケットを特定します。この例では、バケット番号 8 に 50 パーセンタイルが含まれています。

2. 次のルールを使用して推定値を計算します。

   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 つだけのこの例の場合、パーセンタイルは次のようになります。

推定値と実際の測定値との間の誤差は制限できますが、測定値が不明なため特定はできません。

ケース 2: サンプルの総数は 10 です。

サンプルが 10 ある場合、50 パーセンタイルは 95 パーセンタイルや 99 パーセンタイルとは異なるバケットに入る場合があります。ただし、95 パーセンタイルと 99 パーセンタイルを異なるバケットに入れるには、まだ十分な測定結果がありません。

たとえば、次の表に示すような測定値のヒストグラムがあるとします。

前述の手順を使用して、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

前に説明したプロセスを使用することで、パーセンタイルを計算できます。次の表の各行には、パーセンタイル、対応するバケット、計算された値が一覧表示されています。

この例と前の例では、95 パーセンタイルはバケット番号 8 にありますが、パーセンタイルの計算は異なります。違いは、サンプルの分布の仕方によるものです。最初の例では、すべてのサンプルが同じバケットにありますが、最新の例では、サンプルは異なるバケットにあります。

実際のデータを使用した例

このセクションでは、特定の指標で使用されるバケットモデルを決定する方法についての例を示します。また、計算されたパーセンタイル値の潜在的な誤差を評価する方法についても説明します。

バケットモデルを識別する

特定の時間間隔で指標に使用されるバケットを決定するには、Cloud Monitoring API の projects.timeSeries/list メソッドを呼び出します。

たとえば、指標のバケットモデルを特定する手順は次のとおりです。

1. ウェブページ projects.timeSeries/list に移動します。

2. API Explorer に、指標、開始時間、終了時間を指定するフィルタを入力します。

   たとえば、API リクエストのレイテンシを格納する指標に関する情報を取得するには、次のように入力します。

   metric.type="serviceruntime.googleapis.com/api/request_latencies"
   resource.type="consumed_api"
   

   この例では、フィルタ フィールドで指標タイプとリソースタイプが指定されています。これらのフィルタの詳細については、モニタリング フィルタをご覧ください。

3. 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 はバケットの総数です。

次の表に、この指標のバケットと各バケットの中間値を示します。

パーセンタイルの計算を確認する

バケットの構成が判明したので、どのような測定結果でも、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 にあり、もう一つのサンプルでは 50 パーセンタイルはバケット 11 にあります。

次の表は、異なる整列指定子を使用して projects.timeSeries/list メソッドを実行した結果を示しています。最初の行は、整列指定子が指定されていないケースに対応します。整列指定子を指定しない場合、バケットモデルと平均値が返されます。次の 3 行には、整列指定子が ALIGN_PERCENTILE_50、ALIGN_PERCENTILE_95、ALIGN_PERCENTILE_99 に設定されている場合に返されるデータが一覧表示されています。

合成データを使用した 2 つの例が示すように、パーセンタイルの値は、サンプルの分布の仕方によって異なります。すべてのサンプルがサンプル バケットにある場合、50 パーセンタイルはそのバケットの中間点になります。ただし、サンプルが異なるバケットにある場合、その分布は推定値に影響します。

50 パーセンタイルが平均の妥当な推定値であるかどうかを判断するには、平均値を 50 パーセンタイルと比較します。平均値はバケットの詳細とともに返されます。

次のステップ

分布値の指標を可視化する方法については、分布値の指標についてをご覧ください。