パーセンタイルランク（Percentile ranks）

パーセンタイルランクの集約

集約されたドキュメントから抽出された数値に対して1つ以上のパーセンタイルランクを計算する multi-value メトリクス集約です。これらの値は、ドキュメント内の特定の数値または ヒストグラムフィールド から抽出できます。

パーセンタイルランクの集約に関する近似、パフォーマンス、およびメモリ使用に関するアドバイスについては、パーセンタイルは（通常）近似です、圧縮、および実行ヒントを参照してください。

パーセンタイルランクは、特定の値未満の観測値の割合を示します。たとえば、ある値が観測された値の95％以上である場合、それは95パーセンタイルランクにあると言います。

データがウェブサイトの読み込み時間で構成されていると仮定します。ページの95％の読み込みが500ms以内に完了し、99％の読み込みが600ms以内に完了するというサービス契約があるかもしれません。

読み込み時間を表す一連のパーセンタイルを見てみましょう：

Python

resp = client.search(
   index="latency",
   size=0,
   aggs={
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [
   500,
   600
   ]
   }
   }
   },
)
print(resp)

Ruby

response = client.search(
  index: 'latency',
  body: {
   size: 0,
   aggregations: {
   load_time_ranks: {
   percentile_ranks: {
   field: 'load_time',
   values: [
   500,
   600
   ]
   }
   }
   }
  }
)
puts response

Js

const response = await client.search({
  index: "latency",
  size: 0,
  aggs: {
   load_time_ranks: {
   percentile_ranks: {
   field: "load_time",
   values: [500, 600],
   },
   },
  },
});
console.log(response);

コンソール

GET latency/_search
{
  "size": 0,
  "aggs": {
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [ 500, 600 ]
   }
   }
  }
}

レスポンスは次のようになります：

コンソール-結果

{
  ...
 "aggregations": {
   "load_time_ranks": {
   "values": {
   "500.0": 55.0,
   "600.0": 64.0
   }
   }
  }
}

この情報から、99％の読み込み時間の目標には達しているが、95％の読み込み時間の目標には達していないことがわかります。

キー付きレスポンス

デフォルトでは、keyed フラグは true に設定されており、各バケットに一意の文字列キーを関連付け、範囲を配列ではなくハッシュとして返します。 keyed フラグを false に設定すると、この動作が無効になります：

Python

resp = client.search(
   index="latency",
   size=0,
   aggs={
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [
   500,
   600
   ],
   "keyed": False
   }
   }
   },
)
print(resp)

Ruby

response = client.search(
  index: 'latency',
  body: {
   size: 0,
   aggregations: {
   load_time_ranks: {
   percentile_ranks: {
   field: 'load_time',
   values: [
   500,
   600
   ],
   keyed: false
   }
   }
   }
  }
)
puts response

Js

const response = await client.search({
  index: "latency",
  size: 0,
  aggs: {
   load_time_ranks: {
   percentile_ranks: {
   field: "load_time",
   values: [500, 600],
   keyed: false,
   },
   },
  },
});
console.log(response);

コンソール

GET latency/_search
{
  "size": 0,
  "aggs": {
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [ 500, 600 ],
   "keyed": false
   }
   }
  }
}

レスポンス：

コンソール-結果

{
  ...
  "aggregations": {
   "load_time_ranks": {
   "values": [
   {
   "key": 500.0,
   "value": 55.0
   },
   {
   "key": 600.0,
   "value": 64.0
   }
   ]
   }
  }
}

スクリプト

インデックスされていない値に対して集約を実行する必要がある場合は、ランタイムフィールドを使用してください。たとえば、読み込み時間がミリ秒単位であるが、パーセンタイルを秒単位で計算したい場合：

Python

resp = client.search(
   index="latency",
   size=0,
   runtime_mappings={
   "load_time.seconds": {
   "type": "long",
   "script": {
   "source": "emit(doc['load_time'].value / params.timeUnit)",
   "params": {
   "timeUnit": 1000
   }
   }
   }
   },
   aggs={
   "load_time_ranks": {
   "percentile_ranks": {
   "values": [
   500,
   600
   ],
   "field": "load_time.seconds"
   }
   }
   },
)
print(resp)

Ruby

response = client.search(
  index: 'latency',
  body: {
   size: 0,
   runtime_mappings: {
   'load_time.seconds' => {
   type: 'long',
   script: {
   source: "emit(doc['load_time'].value / params.timeUnit)",
   params: {
   "timeUnit": 1000
   }
   }
   }
   },
   aggregations: {
   load_time_ranks: {
   percentile_ranks: {
   values: [
   500,
   600
   ],
   field: 'load_time.seconds'
   }
   }
   }
  }
)
puts response

Js

const response = await client.search({
  index: "latency",
  size: 0,
  runtime_mappings: {
   "load_time.seconds": {
   type: "long",
   script: {
   source: "emit(doc['load_time'].value / params.timeUnit)",
   params: {
   timeUnit: 1000,
   },
   },
   },
  },
  aggs: {
   load_time_ranks: {
   percentile_ranks: {
   values: [500, 600],
   field: "load_time.seconds",
   },
   },
  },
});
console.log(response);

コンソール

GET latency/_search
{
  "size": 0,
  "runtime_mappings": {
   "load_time.seconds": {
   "type": "long",
   "script": {
   "source": "emit(doc['load_time'].value / params.timeUnit)",
   "params": {
   "timeUnit": 1000
   }
   }
   }
  },
  "aggs": {
   "load_time_ranks": {
   "percentile_ranks": {
   "values": [ 500, 600 ],
   "field": "load_time.seconds"
   }
   }
  }
}

HDRヒストグラム

HDRヒストグラム（高ダイナミックレンジヒストグラム）は、レイテンシ測定のパーセンタイルランクを計算する際に便利な代替実装であり、t-digest実装よりも高速である可能性がありますが、より大きなメモリフットプリントのトレードオフがあります。この実装は、固定の最悪ケースのパーセンテージ誤差（指定された有効数字の数）を維持します。これは、データが1マイクロ秒から1時間（3,600,000,000マイクロ秒）の値で記録され、ヒストグラムが3桁の有効数字に設定されている場合、1ミリ秒までの値に対して1マイクロ秒の値解像度を維持し、最大追跡値（1時間）に対して3.6秒（またはそれ以上）を維持することを意味します。

HDRヒストグラムは、リクエスト内で hdr オブジェクトを指定することによって使用できます：

Python

resp = client.search(
   index="latency",
   size=0,
   aggs={
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [
   500,
   600
   ],
   "hdr": {
   "number_of_significant_value_digits": 3
   }
   }
   }
   },
)
print(resp)

Ruby

response = client.search(
  index: 'latency',
  body: {
   size: 0,
   aggregations: {
   load_time_ranks: {
   percentile_ranks: {
   field: 'load_time',
   values: [
   500,
   600
   ],
   hdr: {
   number_of_significant_value_digits: 3
   }
   }
   }
   }
  }
)
puts response

Js

const response = await client.search({
  index: "latency",
  size: 0,
  aggs: {
   load_time_ranks: {
   percentile_ranks: {
   field: "load_time",
   values: [500, 600],
   hdr: {
   number_of_significant_value_digits: 3,
   },
   },
   },
  },
});
console.log(response);

コンソール

GET latency/_search
{
  "size": 0,
  "aggs": {
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [ 500, 600 ],
   "hdr": {
   "number_of_significant_value_digits": 3
   }
   }
   }
  }
}

HDRヒストグラムは正の値のみをサポートし、負の値が渡されるとエラーが発生します。また、値の範囲が不明な場合にHDRヒストグラムを使用することはお勧めできません。これは高いメモリ使用量につながる可能性があります。

欠損値

missing パラメータは、値が欠落しているドキュメントがどのように扱われるべきかを定義します。デフォルトでは無視されますが、値があるかのように扱うことも可能です。

Python

resp = client.search(
   index="latency",
   size=0,
   aggs={
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [
   500,
   600
   ],
   "missing": 10
   }
   }
   },
)
print(resp)

Ruby

response = client.search(
  index: 'latency',
  body: {
   size: 0,
   aggregations: {
   load_time_ranks: {
   percentile_ranks: {
   field: 'load_time',
   values: [
   500,
   600
   ],
   missing: 10
   }
   }
   }
  }
)
puts response

Js

const response = await client.search({
  index: "latency",
  size: 0,
  aggs: {
   load_time_ranks: {
   percentile_ranks: {
   field: "load_time",
   values: [500, 600],
   missing: 10,
   },
   },
  },
});
console.log(response);

コンソール

GET latency/_search
{
  "size": 0,
  "aggs": {
   "load_time_ranks": {
   "percentile_ranks": {
   "field": "load_time",
   "values": [ 500, 600 ],
   "missing": 10
   }
   }
  }
}