DQL 関数リファレンス¶
DQL は、データの集約、変換、マッチングに使用する豊富な関数を提供します。本ドキュメントでは、各関数のセマンティクス、パラメータ、使用方法について詳しく説明します。
集約関数¶
集約関数は複数行のデータを単一の値に集約するために使用し、通常は時間ウィンドウ(time-expr)とグループ化(BY 句)と組み合わせて使用します。
基本集約¶
sum¶
フィールド値の合計を計算します。
構文:
パラメータ:
field: 数値フィールド
例:
// 各ホストの NIC 受信総バイト数を計算
M::net:(sum(bytes_recv) AS total_recv_bytes) [1h] BY host
// 各 APM サービスの総所要時間を計算
T::*:(sum(duration) AS total_duration_ns) [1h] BY service
avg¶
フィールド値の平均値を計算します。
構文:
パラメータ:
field: 数値フィールド
例:
// 各ホストの平均 CPU 総使用率を計算
M::cpu:(avg(usage_total) AS avg_cpu) [1h] BY host
// 各 APM サービスの平均応答時間を計算
T::*:(avg(duration) AS avg_duration_ns) [1h] BY service
count¶
データ行数または非 NULL フィールド値の数を計算します。
構文:
パラメータ:
field: 任意のフィールド。非 NULL 値の数を計算distinct(field): フィールドの正確な重複排除値数を計算*: すべての行数を計算(ログL、トレースT、オブジェクトO、RUMR、イベントEなどの非メトリクス名前空間にのみ適用。Mメトリクス名前空間では具体的なメトリクスフィールド名を指定してください)
例:
// 直近 1 時間のログ総件数を計算
L::*:(count(*) AS log_count) [1h]
// サービスごとに APM 呼び出し Span 数を集計
T::*:(count(duration) AS span_count) [1h] BY service
// ページにアクセスした異なるユーザー ID 数を正確に集計
R::view:(count(distinct(userid)) AS exact_uv) [1h] BY app_id
min / max¶
フィールドの最小値または最大値を計算します。
構文:
パラメータ:
field: 数値フィールド
例:
// 各サービスの最大応答時間を検出
T::*:(max(duration) AS max_duration_ns) [1h] BY service
// 各ホストの CPU 使用率の最小値と最大値を検出
M::cpu:(min(usage_total) AS min_cpu, max(usage_total) AS max_cpu) [1h] BY host
first / last¶
最初または最後の値(時系列順)を取得します。
構文:
パラメータ:
field: 任意のフィールド
説明:
first: 時間ウィンドウ内で最も早い時点の値を返すlast: 時間ウィンドウ内で最も遅い時点の値を返す。フィールドが配列型の場合は展開されるlast_row: 時間ウィンドウ内で最も遅い時点の値を返す。配列型は展開しない
例:
// 各ホストの最新システム 1 分間ロード値を取得
M::system:(last(load1) AS latest_load1) [1h] BY host
// 各ホストのウィンドウ開始時と終了時のメモリ使用率を取得
M::mem:(first(used_percent) AS start_mem, last(used_percent) AS end_mem) [1h] BY host
any¶
任意の非 NULL 値を返します。グループ集約時にサンプルデータ(例:サンプルエラーメッセージ 1 件)を取得する場合や、特定の時間順序が不要な場合に適しています。
構文:
パラメータ:
field: 任意のフィールド
例:
// サービスごとにエラーログ数を集計し、ログサンプルを 1 件付加
L::*:(count(*) AS err_cnt, any(message) AS sample_message) {status = 'error'} [1h] BY service
// エラータイプごとにフロントエンドエラーを集計し、サンプルエラー詳細を 1 件取得
R::error:(count(*) AS cnt, any(error_message) AS sample_error) [1h] BY error_type
SHIFT¶
式レベルの SHIFT は、プロジェクション内で履歴ウィンドウの集約値を参照し、現在の集約結果と整列して表示します:
現在値、履歴値、派生計算はすべてプロジェクション式で明示します。同じ履歴値を複数回参照する場合は、同じ SHIFT 式を繰り返し記述します:
L::*:(
service,
count(*) AS requests,
count(*) SHIFT 7d AS requests_last_week,
CASE
WHEN (count(*) SHIFT 7d) = nil OR (count(*) SHIFT 7d) = 0 THEN nil
ELSE count(*) / (count(*) SHIFT 7d)
END AS requests_ratio
) [1d:1h] BY service
duration は 1h、7d など、正の固定時間である必要があります。
使用上の制限:
- プロジェクション内にのみ記述でき、現在のプロジェクション内で行の識別情報がウィンドウ間で安定している集約式、またはそのような集約を由来とするサブクエリの measure にのみ適用できます。
- 同じ
SELECTで宣言したばかりのプロジェクション別名、ディメンション列、WHERE、BY、HAVING、ORDER BY、SORDER BYには適用できません。また、SHIFTをネストすることもできません。 distinct、distinct_by_collapse、field_values、histogramなど、出力行が各ウィンドウのデータによって決まる集約は operand にできません。uint(field)など元のフィールドだけを変換する式は集約 measure ではありません。abs(sum(field))など、安定した集約をラップするスカラー変換は使用できます。- 履歴値に基づくフィルタやソートが必要な場合は、外側の
SELECTで行います。 - 同じ
SELECT内のすべての式レベルSHIFTは、合計で最大 16 個の異なる offset を含めることができます。
クエリレベルの SHIFT(DQL メインドキュメントの時間シフトを参照)と式レベルの SHIFT は組み合わせられます。クエリレベルのオフセットがまずクエリ全体の基準ウィンドウを決定し、式レベルのオフセットはその基準ウィンドウに対してさらに前の集約値を読み取ります。
spread¶
範囲(最大値と最小値の差)を計算します。
構文:
パラメータ:
field: 数値フィールド
例:
// 各ホストの 1 時間内の CPU 使用率の変動範囲(最大値 - 最小値)を計算
M::cpu:(spread(usage_total) AS cpu_spread) [1h] BY host
// 各 APM サービスの応答時間の範囲を計算
T::*:(spread(duration) AS duration_spread) [1h] BY service
stddev¶
標準偏差を計算し、メトリクスまたは所要時間のばらつきの度合いを測定します。
構文:
パラメータ:
field: 数値フィールド
例:
// 各ホストの CPU 使用率の標準偏差を計算
M::cpu:(stddev(usage_total) AS cpu_stddev) [1h] BY host
// 各サービスの応答時間の標準偏差を計算
T::*:(stddev(duration) AS duration_stddev) [1h] BY service
mode¶
最頻値(最も多く出現する値)を計算します。
構文:
パラメータ:
field: 任意のフィールド
例:
// 各サービスの APM 呼び出しで最も多く出現する HTTP ステータスコードを検出
T::*:(mode(http_status_code) AS most_common_status) [1h] BY service
count_series¶
時系列(Series)の数を計算し、現在のクエリ範囲内に独立した時系列がいくつあるかを返します。
構文:
パラメータ:
field: 具体的なメトリクスフィールド名(注意:Mメトリクス名前空間では*ワイルドカードはサポートされません。usage_total、used_percentなどの実際のフィールド名を指定する必要があります)
例:
// 現在 CPU usage_total メトリクスをレポートしている時系列の総数を集計
M::cpu:(count_series(usage_total) AS total_series) [1h]
// ホストごとにディスクメトリクスの時系列数を集計(例:各ホストにマウントされているディスクパーティション数)
M::disk:(count_series(used_percent) AS disk_series_cnt) [1h] BY host
統計集約(推定関数)¶
以下の関数は確率データ構造を使用して推定し、大量データのシナリオに適しており、精度とパフォーマンスのバランスを取ることができます。
count_distinct¶
フィールドの異なる値の数を計算します(推定値)。
構文:
パラメータ:
field: 任意のフィールド
アルゴリズム説明:
HyperLogLog アルゴリズムを使用して基数を推定します: - レジスタ数:2¹⁶ = 65536 - LogLog-Beta 推定手法を使用 - 標準誤差:約 0.4%
ユースケース:
- 独立ユーザー数(UV)を集計
- ログをレポートしている異なるホストまたは Pod 数を計算
- 一意な Trace ID 数を分析
重複排除カウントの選択に関する説明: -
count(distinct(field)):正確な重複排除カウント。フィールド値に対して正確な重複排除集計を行い、結果に誤差はありません。数値精度が厳密に求められる課金照合やレポート統計に適しています。 -count_distinct(field):近似重複排除カウント。HyperLogLog 基数推定法に基づき、メモリ使用量が非常に少なく、クエリ速度が非常に高速です。大量のログ、独立ユーザー数(UV)など、微小な誤差が許容される大基数分析シナリオに適しています。
例:
// 過去 24 時間の各ページの独立訪問者数(UV)を集計
R::view:(count_distinct(userid) AS uv) [24h] BY view_path
// 過去 1 時間に各サービスが生成したログの異なる Pod 数を集計
L::*:(count_distinct(pod_name) AS pod_cnt) [1h] BY service
percentile¶
フィールドのパーセンタイル(推定値)を計算します。
構文:
パラメータ:
field: 数値フィールドn: パーセンタイル。範囲は 0〜100
短縮形式:
p50(field)はpercentile(field, 50)と等価p95(field)はpercentile(field, 95)と等価p99(field)はpercentile(field, 99)と等価
アルゴリズム説明:
対数線形補間ヒストグラムを使用して推定します: - バケット範囲:10⁻⁹ から 10¹⁸。ほとんどの数値シナリオをカバー - 各桁を 128 個のバケットに分割 - 対数空間の線形補間を使用して精度を向上
ユースケース:
- APM の応答時間または RUM のページロード時間の P99、P95 を計算
- パフォーマンスメトリクスのテールレイテンシを分析
- サービスレベルアグリーメント(SLA)の達成状況を評価
例:
// 各 APM サービスの応答時間の P99 を計算
T::*:(percentile(duration, 99) AS p99_duration) [1h] BY service
// 短縮形式を使用して P50、P95、P99 を同時に計算
T::*:(p50(duration) AS p50_ns, p95(duration) AS p95_ns, p99(duration) AS p99_ns) [1h] BY service
// Rollup 関数として呼び出す:まず各 CPU 時系列で P95 を計算し、次に host ごとに平均
M::cpu:(avg(usage_total)) [1h::5m:percentile(95)] BY host
median¶
中央値を計算します。percentile(field, 50) と等価です。
構文:
例:
ヒストグラム関数¶
DQL は 3 種類のヒストグラム関連関数を提供しており、異なるデータソースとシナリオに適しています:
| 関数 | ユースケース | データソースタイプ | 推奨度 |
|---|---|---|---|
histogram_auto |
ログ、Trace などの明細データの数値分布統計 | 明細モデル(ログ/Trace) | ⭐⭐⭐ 推奨 |
histogram |
固定バケット境界が必要なヒストグラム | 明細モデル(ログ/Trace) | ⭐⭐ Deprecated |
histogram_quantile |
Prometheus ヒストグラムメトリクスからパーセンタイルを計算 | Prometheus メトリクス | ⭐⭐⭐ 推奨 |
histogram_auto(推奨)¶
分布ヒストグラムを自動生成し、ログ、Trace などの明細データの数値分布統計向けに設計されています。
特徴:
- バケット境界の指定が不要で、データ分布に自動適応
- 対数線形補間ヒストグラムアルゴリズムを使用し、10⁻⁹ から 10¹⁸ の数値範囲をカバー
- パーセンタイル統計とバケット分布情報を同時に返す
構文:
パラメータ:
field: 数値フィールド
戻り値:
| 列名 | 説明 |
| -------------- | ---------------- |
| lower_bounds | 各バケットの下限配列 |
| upper_bounds | 各バケットの上限配列 |
| counts | 各バケットのカウント配列 |
| min | 最小値 |
| p50 | 中央値 |
| p75 | 75 パーセンタイル |
| p90 | 90 パーセンタイル |
| p95 | 95 パーセンタイル |
| p99 | 99 パーセンタイル |
| max | 最大値 |
アルゴリズム説明: 推定ヒストグラム(対数線形補間)を使用し、各桁を 128 個のバケットに分割します。大量データの分布統計に適しています。
ユースケース:
- ログ内の応答時間分布を分析
- Trace 内の所要時間分布を集計
- 探索的データ分析。バケット境界の事前設定が不要
例:
// APM トレース呼び出しの所要時間分布を分析
T::*:(histogram_auto(duration)) [1h] BY service
// RUM ページロード時間の分布を分析
R::view:(histogram_auto(loading_time)) [24h] BY view_path
結果例:
| lower_bounds | upper_bounds | counts | min | p50 | p75 | p90 | p95 | p99 | max |
|---|---|---|---|---|---|---|---|---|---|
| [0, 10, 100] | [10, 100, 1000] | [1000, 500, 100] | 0.5 | 45 | 120 | 280 | 450 | 850 | 1200 |
注:
lower_bounds、upper_bounds、countsは配列型で、各バケットの境界とカウントを表します。
histogram(Deprecated)¶
指定したバケット境界のヒストグラムを生成します。この関数は Deprecated であり、histogram_auto の使用を推奨します。
説明:
histogram はバケット境界パラメータを手動で指定する必要があり、柔軟性に欠けます。histogram_auto はデータ分布に自動適応し、より広範な数値範囲をカバーし、より豊富な統計情報を返します。
構文:
パラメータ:
field: 数値フィールドleft_bound: 左境界right_bound: 右境界bucket_size: バケットサイズthreshold(省略可能): 単一バケットの最小カウント。この値未満のバケットは返されません
戻り値:
2 列を返します:bucket_le(バケットの右境界)と count(カウント)
例:
// 0〜1000 の範囲で 100 ごとに 1 バケットのヒストグラムを生成
R::view:(histogram(loading_time, 0, 1000, 100)) [1h]
// histogram_auto の使用を推奨
R::view:(histogram_auto(loading_time)) [1h]
結果例:
| bucket_le | count |
|---|---|
| 100 | 1500 |
| 200 | 2800 |
| 300 | 3500 |
| ... | ... |
| 1000 | 5000 |
histogram_quantile¶
Prometheus ヒストグラムメトリクスからパーセンタイルを計算します。
特徴:
- Prometheus がレポートするヒストグラム型メトリクスの処理に特化
leタグ(または VictoriaMetrics のvmrangeタグ)に依存して bucket 境界を識別- 入力データは累積カウント(cumulative)である必要があります
構文:
パラメータ:
field: ヒストグラムカウントフィールド(例:http_request_duration_bucket)q: パーセンタイル。範囲は 0〜1(例:0.99 は P99 を表す)
使用シナリオの比較:
| シナリオ | 推奨関数 | 説明 |
|---|---|---|
| ログ内の応答時間分布を分析 | histogram_auto |
ログは明細データであり、事前集約されたヒストグラムはない |
| Prometheus ヒストグラムメトリクスの P99 を分析 | histogram_quantile |
メトリクスは le タグで事前集約済み |
| Trace 呼び出しの所要時間分布を集計 | histogram_auto |
Trace は明細データ |
le タグの処理メカニズム:
histogram_quantile は le タグ(less than or equal)に依存してヒストグラム bucket の境界を識別します:
- Prometheus 形式(デフォルト):
leタグで bucket の上限を直接表現 leの値は数値(例:"0.1"、"1"、"10")または "+Inf"(無限大)-
データは累積カウント(cumulative)である必要があります
-
VictoriaMetrics 形式:
vmrangeタグで範囲を表現 - 形式は
"下限...上限"(例:"0.1...0.2") - データは範囲カウント(非累積)
- 関数は範囲カウントを自動的に累積カウントに変換
計算プロセス:
1. le の値で全 bucket をソート
2. vmrange 形式の場合は、カウントを累積して累積分布に変換
3. bucket カウントが単調増加であることを保証(異常データの可能性を補正)
4. 線形補間を使用して対象のパーセンタイルを計算
PromQL との違い:
| 特性 | DQL | PromQL |
|---|---|---|
| 関数タイプ | 集約関数 | 変換関数 |
| 入力データ | le タグ付きメトリクスを直接読み取る |
sum(rate(...)) by (le) と組み合わせる必要がある |
| 使用方法 | histogram_quantile(field, 0.99) |
histogram_quantile(0.99, sum(rate(...)) by (le)) |
| データ形式 | le と vmrange の 2 種類のタグをサポート |
le タグのみをサポート |
| グループ化方法 | DQL の BY 句を使用 | by (le) で明示的にグループ化 |
等価例:
ヒストグラムメトリクス http_request_duration_bucket があり、le タグ(例:0.1、0.5、1、5、+Inf)と service タグを含むと仮定します。
シナリオ 1:P99 レイテンシを計算
DQL:
PromQL 等価:
シナリオ 2:各サービスの P95 レイテンシを計算(複数グループ化)
DQL:
PromQL 等価:
シナリオ 3:P50(中央値)と P99 を計算
DQL:
M::http_request_duration:(
histogram_quantile(duration_bucket, 0.50) AS p50,
histogram_quantile(duration_bucket, 0.99) AS p99
) [1h] BY service
PromQL 等価:
label_join(
histogram_quantile(0.50, sum(rate(http_request_duration_bucket[1h])) by (le, service)), "quantile", "", "0.50"
)
or
label_join(
histogram_quantile(0.99, sum(rate(http_request_duration_bucket[1h])) by (le, service)), "quantile", "", "0.99"
)
注:PromQL では
label_joinまたはlabel_replaceを使用して、異なるパーセンタイルの結果を区別する必要があります。
注意事項:
- 入力データには
leまたはvmrangeタグが必須です。ない場合は計算できません +Infbucket がない場合、最後の bucket の上限が最大値として使用されます- カウントが 0 または NaN の bucket はスキップされます
- パーセンタイル < 0 の場合は -Inf、> 1 の場合は +Inf を返します
TopN 関数¶
top¶
グループ内で上位 N 個の最大値を取得します。
構文:
パラメータ:
field: 数値フィールドn: 返す値の数
例:
// 各サービスの応答時間が最も長い 5 個の値を取得
T::*:(top(duration, 5)) [1h] BY service
// CPU 使用率が最も高い 10 個のサンプル値を取得
M::cpu:(top(usage_total, 10)) [1h] BY host
結果例:
| service | top(duration, 5) |
|---|---|
| api | 1250 |
| api | 1180 |
| api | 1050 |
| api | 980 |
| api | 920 |
注:複数行を返し、各行に TopN 値が 1 つ含まれます。グループ(Series)間でソートして上位 N グループを取得する必要がある場合は、
SORDER BY ... DESC SLIMIT Nを使用してください(DQL メインドキュメントのグループ間ソートを参照)。
bottom¶
グループ内で上位 N 個の最小値を取得します。
構文:
パラメータ:
field: 数値フィールドn: 返す値の数
例:
// 各サービスの応答時間が最も短い 5 個の値を取得
T::*:(bottom(duration, 5)) [1h] BY service
// 各ホストの利用可能メモリ割合が最も低い 5 個のサンプル値を取得
M::mem:(bottom(available_percent, 5)) [1h] BY host
結果例:
| service | bottom(duration, 5) |
|---|---|
| api | 12 |
| api | 18 |
| api | 25 |
| api | 32 |
| api | 45 |
注:複数行を返し、各行に BottomN 値が 1 つ含まれます。
値収集関数¶
distinct¶
フィールドのすべての異なる値(異なる値ごとに 1 行)を返します。
構文:
例:
結果例:
| service | distinct(status) |
|---|---|
| api | info |
| api | warn |
| api | error |
| web | info |
注:複数行を返し、各行に異なる値が 1 つ含まれます。
distinct_by_collapse¶
折りたたみ戦略に従ってフィールドの異なる値を取得し、重複排除時に指定した他のフィールドの最後の値を保持します。
構文:
パラメータ:
field: 重複排除の基準となるフィールドlast_fields(省略可能): 最後の値を保持するフィールドのリスト
説明:
distinct と異なり、distinct_by_collapse は重複排除時に他の関連フィールドの情報(最後の値)を保持します。コンテキスト情報を保持する必要があるシナリオに適しています。
例:
// 異なるサービス名を取得し、各サービスの最新エラーログの内容とホスト名を保持
L::*:(distinct_by_collapse(service, [host, message])) {status = 'error'} [1h]
// 異なるホストを取得し、最後の OS、状態、CPU 使用率を保持
O::HOST:(distinct_by_collapse(host, [os, state, cpu_usage])) [1h]
結果例:
| service | last(host) | last(message) |
|---|---|---|
| payment | node-01 | "connection reset by peer" |
| order | node-02 | "query timeout" |
注:重複排除後の主フィールド値と、
last_fieldsで指定した他のフィールドの最後の値を返します。
collect¶
すべての値(重複を含む)を収集し、配列型を返します。
構文:
パラメータ:
field: 任意のフィールドlimit(省略可能): 最大収集数
例:
// サービスごとに最大 20 個の遅いリクエストの所要時間値を収集
T::*:(collect(duration, 20)) {duration > 1000000000} [1h] BY service
結果例:
| service | collect(duration, 20) |
|---|---|
| api | [1200000000, 1350000000, 1100000000] |
| web | [1500000000, 1800000000] |
注:配列型を返し、収集されたすべての値(重複を含む可能性がある)を含みます。
collect_distinct¶
すべての異なる値を収集し、重複排除後の配列を返します。
構文:
パラメータ:
field: 任意のフィールドlimit(省略可能): 最大収集数
例:
// サービスごとにエラーログを生成したことのあるホストのリストを収集
L::*:(collect_distinct(host)) {status = 'error'} [1h] BY service
結果例:
| service | collect_distinct(host) |
|---|---|
| api | ["node-01", "node-02"] |
| web | ["node-03"] |
注:配列型を返し、重複排除後のすべての値を含みます。
field_values¶
フィールドのすべての異なる値とその出現回数(hits)を集計し、重複排除値の列と対応する hits カウント列を返します。
構文:
パラメータ:
field: 任意のフィールド(スカラーまたは配列フィールド。配列フィールドは自動的に展開され、各要素の出現回数を集計)
例:
結果例:
| field_values(status) | hits |
|---|---|
| "info" | 15420 |
| "warn" | 320 |
| "error" | 45 |
注:複数行を返し、重複排除後のフィールド値列
field_values(field)と対応する出現回数列hitsを含みます。
フィルタ集約¶
count_filter¶
フィールド値が指定リストに含まれる数量を集計します。
構文:
パラメータ:
field: 任意のフィールドvalues: 値のリスト
例:
// 特定の HTTP ステータスコードの APM リクエスト数を集計
T::*:(count_filter(http_status_code, ["200", "201", "204"])) [1h] BY service
// error および critical レベルのログ件数を集計
L::*:(count_filter(status, ["error", "critical"])) [1h] BY service
補助関数¶
default¶
フィールドにデフォルト値を設定し、集約結果が空の場合にデフォルト値を返します。
構文:
パラメータ:
field: 任意のフィールドdefault_value: デフォルト値(数値、文字列、ブール値、または null を指定可能)
例:
時系列関数¶
時系列関数は、時間とともに変化するデータ、特に Counter 型のメトリクスを処理するために使用します。
Rollup 関数¶
Rollup 関数は、時間ウィンドウ内で生の時系列データを前処理するために使用します。詳細は 本ドキュメント内の Rollup 関数 を参照してください。
記述方法:
- Rollup は時間句に記述します。例:
[rate]、[1h::5m:rate]。 - クエリの外側に記述する(例:
rate(DQL))場合はアウター関数であり、Rollup ではありません。 - Rollup 短縮、Rollup 関数呼び出し、明示的な集約呼び出しの実行フェーズとパラメータの違いについては、DQL メインドキュメントの Rollup 関数 を参照してください。
時間句は Rollup 短縮をサポートし、Rollup 関数に追加のアルゴリズムパラメータを渡すこともできます(例:
[1h::1m:ewma(0.3)])。時間句中のパラメータはアルゴリズムパラメータのみを表し、入力フィールドは引き続き Select フィールドによって決まります。複数の入力フィールドが必要な関数は、Select 句で明示的な集約呼び出しを使用する必要があります。
Rollup 短縮をサポートする関数:
| 関数 | 説明 |
|---|---|
rate |
増加率(毎秒)を計算 |
irate |
瞬間増加率を計算 |
increase |
増加量を計算 |
deriv |
導関数(変化率)を計算 |
difference |
差分を計算 |
non_negative_derivative |
非負導関数を計算 |
non_negative_difference |
非負差分を計算 |
rate_over_sum |
毎秒平均値を計算 |
rate_over_count |
毎秒カウントを計算 |
sum |
合計 |
avg |
平均値 |
min |
最小値 |
max |
最大値 |
count |
カウント |
first |
最初の値 |
last |
最後の値 |
stddev |
標準偏差 |
mode |
最頻値 |
spread |
範囲 |
any |
任意の値 |
slope |
線形トレンドの傾き |
zscore |
最新点の Z-Score |
mad_score |
最新点の MAD 異常スコア |
change_score |
系列の変化点スコア |
Rollup 関数呼び出しをサポートする関数:
| 関数 | 説明 |
|---|---|
ewma(alpha) |
指数加重移動平均 |
moving_average(n) |
移動平均 |
percentile(p) |
パーセンタイル |
例:
// 各ホストの NIC 受信の毎秒レート(バイト/秒)を計算
M::net:(sum(bytes_recv)) [1h::5m:rate] BY host
// 短縮形式(Rollup 関数のみを指定し、時間範囲は外部リクエストで渡す)
M::net:(sum(bytes_recv)) [rate] BY host
// アルゴリズムパラメータ付きの Rollup 関数呼び出し
M::cpu:(avg(usage_total)) [1h::1m:ewma(0.3)] BY host
増加率計算¶
rate¶
Counter メトリクスの毎秒平均増加率を計算します。
構文:
説明:
rate は、Counter メトリクスの時間ウィンドウ内における毎秒平均増加率を計算します(プロセス再起動によるカウンタリセットを自動処理)。単調増加する Counter 型メトリクス(例:net の bytes_recv、bytes_sent、packets_recv)では、元の値をそのまま集約しても意味がないため、先に増加率を計算する必要があります。
ユースケース:
- ネットワークトラフィックのスループット(バイト/秒、パケット/秒)を計算
- リクエスト QPS を計算
- 累積カウンタの増加傾向を分析
例:
// 各ホストの NIC の毎秒受信バイト数を計算(Rollup と組み合わせた使用を推奨)
M::net:(sum(bytes_recv) AS recv_bps) [1h::5m:rate] BY host
// Select 句で rate を直接呼び出す
M::net:(rate(bytes_recv) AS recv_bps) [1h::5m] BY host
irate¶
Counter メトリクスの瞬間増加率(毎秒)を計算します。
構文:
説明:
rate と異なり、irate はウィンドウ内の最後の 2 つのデータポイントのみを使用して増加率を計算します。瞬間的な変化率を反映し、短期的なスパイクに敏感です。
例:
increase¶
Counter メトリクスの時間ウィンドウ内の総増加量を計算します。
構文:
説明:
increase は毎秒レートではなく、時間ウィンドウ内の累積増分を返します。
例:
// 各ホストの過去 1 時間における 5 分ごとの受信パケット増加数を計算
M::net:(sum(packets_recv) AS new_packets) [1h::5m:increase] BY host
rate_over_sum¶
毎秒の平均値(sum(field) / 時間ウィンドウの秒数)を計算します。
構文:
説明:
sum(field) / 時間ウィンドウ(秒) と等価で、ウィンドウ内でレポートされた非累積増分値を毎秒レートに変換するために使用します。
rate との違い:
rate:単調増加する Counter の増加率を計算(先頭と末尾の差分を時間差で割り、リセットを処理)rate_over_sum:ウィンドウ内のすべてのサンプル値を合計し、時間ウィンドウの秒数で割る
例:
rate_over_count¶
毎秒のイベント発生回数(count(field) / 時間ウィンドウの秒数)を計算します。
構文:
説明:
count(field) / 時間ウィンドウ(秒) と等価で、ログやトレースの明細データから毎秒リクエスト数(QPS)を計算する際によく使用します。
例:
// 各サービスが毎秒生成するエラーログ件数を計算
L::*:(rate_over_count(*) AS err_qps) {status = 'error'} [1h::5m] BY service
差分計算¶
本節では関数のセマンティクスについて説明します。同じ関数は Rollup として使用することも(例:[rate]、[increase])、クエリ内の式として記述することもできます(例:rate(field)、increase(field))。両者は実行フェーズが異なるため、業務要件に応じて配置を選択してください。
rate / deriv¶
変化率(導関数)を計算します。rate は Counter 型メトリクス(負の値を無視)に、deriv は Gauge 型メトリクス(負の値を保持)に使用します。
エイリアス:
rateのエイリアスはnon_negative_derivative、derivのエイリアスはderivative(PromQL スタイル)です。
構文:
関数の選択:
| 関数 | 説明 | ユースケース |
|---|---|---|
rate |
非負の変化率のみを計算 | Counter 型メトリクス(単調増加) |
deriv |
完全な変化率を計算(負の値を含む) | Gauge 型メトリクス(増減可能) |
例:
// Counter メトリクス:NIC の毎秒送信バイトレートを計算
M::net:(rate(bytes_sent)) [1h::5m] BY host
// Gauge メトリクス:使用済みメモリの変化率(毎秒増加または解放されるバイト数)を計算
M::mem:(deriv(used)) [1h::5m] BY host
increase / difference¶
隣接値の差分を計算します。increase は Counter 型メトリクス(負の値を無視)に、difference は Gauge 型メトリクス(負の値を保持)に使用します。
説明:
increaseとdifferenceは 2 つの独立した関数であり、動作が異なります。エイリアスの関係ではありません。
構文:
// Counter メトリクス:非負の差分を計算(リセットによる負の値を無視)
increase(field)
// Gauge メトリクス:完全な差分を計算(負の値を含む)
difference(field)
関数の選択:
| 関数 | 説明 | ユースケース |
|---|---|---|
increase |
非負の差分のみを計算 | Counter 型メトリクス(単調増加) |
difference |
完全な差分を計算(負の値を含む) | Gauge 型メトリクス(増減可能) |
例:
// Counter メトリクス:NIC 受信パケット数の増加量を計算
M::net:(increase(packets_recv)) [1h::5m] BY host
// Gauge メトリクス:ホストのプロセス数の増減変化量(増加または減少する可能性がある)を計算
M::system:(difference(process_count)) [1h::5m] BY host
移動計算¶
moving_average¶
移動平均値を計算します。
構文:
パラメータ:
field: 数値フィールドn: ウィンドウサイズ(データポイント数)
例:
// CPU 使用率の 5 点移動平均を計算
M::cpu:(moving_average(usage_total, 5)) [1h::1m] BY host
// Rollup 関数として呼び出す:まず各時系列で 5 点移動平均を計算し、次に host ごとに集約
M::cpu:(avg(usage_total)) [1h::1m:moving_average(5)] BY host
時系列分析集約¶
以下の関数はクエリ内で集約関数として使用し、各時間ウィンドウおよびグループ内の数値シーケンスに対して 1 つの数値結果を計算します。
ewma¶
指数加重移動平均(Exponentially Weighted Moving Average)を計算します。alpha は平滑化係数で、明示的に渡す必要があります。
構文:
パラメータ:
field: 数値フィールドalpha: 平滑化係数。範囲は(0, 1]。値が大きいほど、最新データポイントの重みが高くなります
説明:
ewmaには暗黙のデフォルトalphaがないため、ewma(field)はエラーになります。- 時間句で Rollup として使用する場合は
[...:ewma(alpha)]と記述します。時間句のパラメータではalphaのみを渡し、フィールド名は渡しません。 ewmaはalphaを必要とするため、[...:ewma]のような引数なしの Rollup 短縮はサポートされません。
例:
// 明示的な集約呼び出し:Select 集約フェーズで EWMA を計算
M::cpu:(ewma(usage_total, 0.3)) [1h::1m] BY host
// Rollup 関数呼び出し:まず各時系列で EWMA を計算し、次に host ごとに集約
M::cpu:(avg(usage_total)) [1h::1m:ewma(0.3)] BY host
slope¶
シーケンスの時間変化に対する線形トレンドの傾きを計算します。時間単位は秒です。
構文:
説明:
- 少なくとも 2 つの有効な点が必要です。
- 時間が変化していない場合、または有効な点が不足している場合は NULL を返します。
例:
zscore¶
最新点の、ウィンドウ内の平均値と標準偏差に対する Z-Score を計算します。
構文:
説明:
- 結果は
(latest - mean) / stddevです。 - 少なくとも 2 つの有効な点が必要です。標準偏差が 0 の場合は NULL を返します。
例:
mad_score¶
最新点の MAD(Median Absolute Deviation)異常スコアを計算します。
構文:
説明:
- 中央値と MAD を使用して最新点の逸脱度を測定します。平均値/標準偏差よりも極端値に対して堅牢です。
- 少なくとも 2 つの有効な点が必要です。MAD が 0 の場合は NULL を返します。
例:
change_score¶
ウィンドウ内のシーケンスの変化点スコアを計算し、平均値が明らかに切り替わる時系列を検出するために使用します。
構文:
説明:
- 考えられる分割点を列挙し、分割点の左右 2 区間の平均値の差を比較して、プールされた標準偏差で正規化します。
- 少なくとも 4 つの有効な点が必要です。有効な点が不足している場合は NULL を返します。
例:
corr¶
2 つの数値フィールド間の Pearson 相関係数を計算します。
構文:
説明:
- 戻り値の範囲は通常
[-1, 1]です。 - 少なくとも 2 組の有効な点が必要です。いずれかのフィールドに変化がない場合は NULL を返します。
corrは 2 つの入力フィールドを必要とし、時間句の Rollup 記法はサポートされません。
例:
cumsum¶
累積和(アウター関数)を計算します。
構文:
例:
変換関数¶
変換関数は、フィールド値に対する数学演算、型変換、文字列処理に使用します。
数学関数¶
abs¶
絶対値を計算します。
構文:
例:
round / ceil / floor¶
丸め関数です。
構文:
round(field) // 整数に四捨五入
round(field, digits) // 指定した小数桁に四捨五入
ceil(field) // 切り上げ
floor(field) // 切り捨て
例:
// ディスク使用率を切り上げ
M::disk:(ceil(used_percent)) [1h] BY host
// CPU 使用率を整数に四捨五入
M::cpu:(round(usage_total)) [1h] BY host
// 平均 CPU 使用率を小数第 2 位まで保持
M::cpu:(round(avg(usage_total), 2) AS avg_cpu) [1h] BY host
log / log2 / log10¶
対数関数です。
構文:
例:
型変換¶
int / uint / float / string / bool¶
型変換関数です。
構文:
int(field) // 符号付き整数型に変換
uint(field) // 符号なし整数型に変換
float(field) // 浮動小数点型に変換
string(field) // 文字列に変換
bool(field) // ブール型に変換
例:
// 文字列型の HTTP ステータスコードを整数型に変換してフィルタまたは表示に使用
T::*:(service, int(http_status_code) AS status_num) [15m] LIMIT 10
// 数値フィールドを文字列に変換
O::HOST:(host, string(cpu_usage) AS cpu_str) LIMIT 10
文字列関数¶
lower¶
文字列を小文字に変換します。
構文:
パラメータ:
field: 文字列フィールド
戻り値: 変換後の小文字文字列を返します。
例:
upper¶
文字列を大文字に変換します。
構文:
パラメータ:
field: 文字列フィールド
戻り値: 変換後の大文字文字列を返します。
例:
trim¶
文字列の両端の空白文字を除去します。
構文:
パラメータ:
field: 文字列フィールド
戻り値: 両端の空白を除去した文字列を返します。
例:
ltrim¶
文字列の左側の空白文字を除去します。
構文:
パラメータ:
field: 文字列フィールド
戻り値: 左側の空白を除去した文字列を返します。
例:
rtrim¶
文字列の右側の空白文字を除去します。
構文:
パラメータ:
field: 文字列フィールド
戻り値: 右側の空白を除去した文字列を返します。
例:
length¶
文字列の長さ(文字数)を返します。
構文:
パラメータ:
field: 文字列フィールド
戻り値: 文字列の長さを返します。
例:
// ログ本文の文字数を確認し、長すぎるログをフィルタ
L::*:(service, length(message) AS msg_len) {CASE WHEN length(message) > 1000 THEN true ELSE false END} [15m] LIMIT 10
substr¶
部分文字列を切り出します。
構文:
パラメータ:
field: 文字列フィールドstart: 開始位置(0 から開始。負の値は末尾からの位置を表す)length(省略可能): 部分文字列の長さ
戻り値: 切り出した部分文字列を返します。
例:
// ログメッセージの先頭 100 文字を切り出してプレビュー
L::*:(service, substr(message, 0, 100) AS msg_preview) [15m] LIMIT 20
// ログメッセージの最後の 10 文字を切り出す
L::*:(substr(message, -10) AS msg_tail) [15m] LIMIT 20
結果例:
| message | substr(message, 0, 10) | substr(message, -5) |
|---|---|---|
| "Error: connection timeout" | "Error: con" | "eout" |
regexp_extract¶
正規表現で抽出します。
構文:
パラメータ:
field: 文字列フィールドpattern: 正規表現n(省略可能): n 番目のキャプチャグループを抽出。デフォルトは 0(マッチ全体)
戻り値: 単一の文字列を返し、n 番目のキャプチャグループの内容を抽出します。マッチしない場合は null を返します。
例:
// ログ本文からエラーコードを抽出
L::*:(regexp_extract(message, 'error_code: (\\d+)', 1) AS err_code) [15m] LIMIT 20
// ログ本文から最初の IPv4 アドレスを抽出
L::*:(regexp_extract(message, '(\\d+\\.\\d+\\.\\d+\\.\\d+)', 1) AS ip) [15m] LIMIT 20
結果例:
| service | regexp_extract(message, 'error_code: (\d+)', 1) |
|---|---|
| api | "404" |
| api | "500" |
| web | null |
regexp_extract_all¶
すべてのマッチ結果を抽出します。
構文:
戻り値: すべてのマッチした部分文字列を含む文字列配列を返します。
例:
// ログメッセージ内のすべての数字シーケンスを抽出
L::*:(regexp_extract_all(message, '\\d+', 0) AS numbers) [15m] LIMIT 20
// ログメッセージ内のすべての IPv4 アドレスを抽出
L::*:(regexp_extract_all(message, '\\d+\\.\\d+\\.\\d+\\.\\d+', 0) AS ips) [15m] LIMIT 20
結果例:
| message | regexp_extract_all(message, '\d+\.\d+\.\d+\.\d+', 0) |
|---|---|
| Request from 192.168.1.1 to 10.0.0.1 | ["192.168.1.1", "10.0.0.1"] |
regexp_replace¶
正規表現を使用してマッチしたテキストを置換します。
構文:
パラメータ:
field: 文字列フィールドpattern: 正規表現replacement: 置換文字列。キャプチャグループを参照する場合は$1、${1}、$2などの記法を使用します。キャプチャグループの直後に英字、数字、アンダースコアが続く場合は${1}を使用して曖昧さを解消します(例:${1}_suffix)。リテラル$を出力する場合は$$を使用します
戻り値: 置換後の文字列を返します。マッチしない場合は元の文字列を返します。
例:
// メッセージ内の数字を削除し、先頭 20 文字のプレフィックスでグループ集約
L::*:(count(*)) [1h] BY substr(regexp_replace(message, '\\d+', ''), 0, 20) AS prefix
// キャプチャグループを使用してユーザー ID をマスキングまたは正規化
L::*:(regexp_replace(message, 'user=([0-9]+)', 'uid=$1') AS normalized) [15m] LIMIT 20
md5¶
MD5 ハッシュ値を計算します。
構文:
戻り値: 32 文字の 16 進文字列(小文字)を返します。
例:
結果例:
| service | md5(message) |
|---|---|
| api | 5d41402abc4b2a76b9719d911017c592 |
| web | 098f6bcd4621d373cade4e832627b4f6 |
concat¶
文字列を連結します。
構文:
戻り値: 連結後の単一文字列を返します。
例:
// サービス名とログステータスを連結(例:"api:error")
L::*:(concat(service, ":", status) AS service_status, message) [15m] LIMIT 20
結果例:
| service | status | concat(service, ":", status) |
|---|---|---|
| api | error | "api:error" |
| web | info | "web:info" |
set¶
配列フィールドの重複を排除してソートします。
構文:
戻り値: 重複排除およびソート後の配列を返します。
例:
結果例:
| service | set(collect(status)) |
|---|---|
| api | ["error", "info", "warn"] |
| web | ["info", "warn"] |
ログクラスタリング¶
drain¶
Drain アルゴリズムを使用して類似ログを同じクラスタにまとめ、そのクラスタのログテンプレートを返します。
構文:
パラメータ:
field: 文字列フィールドまたは文字列式。通常はmessagesimilarity_threshold: 類似度しきい値。範囲は(0, 1]。値が大きいほど、より類似したログのみが同じクラスタにまとめられますmax_clusters: 省略可能。最大クラスタ数で、範囲は[1, 10000]。省略時はデフォルトで1000
戻り値:
文字列型のログテンプレートを返します。テンプレートはクラスタ作成時の元のログを骨格とし、元の空白と句読点を保持し、クラスタ内で値が異なる token をプレースホルダーに置き換えます:<num>(数値)、<hex>(16 進数)、<id>(識別子)、<*>(分類できない可変部分)。
アルゴリズム説明:
Drain はパースツリーに基づくログクラスタリングアルゴリズムです。関数は実行過程に従ってクラスタラを継続的に学習します。新しいログが既存クラスタにヒットした場合はそのクラスタに統合し、ヒットしない場合は新しいクラスタを作成します。テンプレートは新しいログの統合に伴って継続的に一般化されるため、同じクラスタでも学習の初期と後期で返されるテンプレートが異なる場合があります。
ユースケース:
- 類似ログごとにグループ集計
- 異常ログのクラスタ分析
- ログノイズ除去
例:
// 類似ログでクラスタリングして集計。類似度 0.7、最大 1000 クラスタ
L::*:(count(*)) [1h] BY drain(message, 0.7, 1000) AS template
// max_clusters を省略した場合はデフォルトで最大 1000 クラスタ
L::*:(count(*)) [1h] BY drain(message, 0.9) AS template
// 複数フィールドを連結してからクラスタリングすることも可能
L::*:(count(*)) [1h] BY drain(concat(service, " ", message), 0.7) AS template
結果例:
| template | count(*) |
|---|---|
| "Request from |
128 |
| "Query SELECT * FROM orders executed in |
42 |
マッチング関数¶
マッチング関数は WHERE 句でテキストマッチングを行うために使用します。
部分文字列マッチング¶
match¶
フィールドに指定した部分文字列が含まれるか確認します。
構文:
パラメータ:
pattern: マッチ対象の部分文字列field: フィールド名(省略可能。WHERE 句で省略した場合はデフォルトでmessageをマッチ)
例:
// WHERE でフィールドを指定してマッチ
L::*:(service, message) {match(message, "error")} [15m] LIMIT 20
// 短縮形式(デフォルトで message フィールドをマッチ)
L::*:(service, message) {match("error")} [15m] LIMIT 20
フレーズマッチング¶
search¶
トークン化フレーズマッチングで、中国語と英語の混在をサポートします。
構文:
パラメータ:
query: クエリフレーズfield: フィールド名(省略可能)
マッチングとトークン化のルール:
- 英字と数字:連続する英字と数字は 1 つのトークン(Token)にまとめられ、大文字と小文字は区別されません(例:
Error、error、ERRORはすべて同じトークンerrorと見なされ、http2は 1 つのトークンと見なされます)。 - 中国語:一般的な語句または単字でトークン化してマッチングします(例:
连接超时は连接、超时に分割されます)。 - 句読点と区切り文字:空白、タブ、改行、およびすべての一般的な句読点(
.、_、:、/、-、@、?、=、&など)は単語境界の区切り文字と見なされます。例: user_nameはuser、nameに分割api.example.comはapi、example、comに分割host-01:8080はhost、01、8080に分割- キーワードマッチング(デフォルト):クエリ文字列に複数のトークンが含まれる場合(例:
search("connection timeout"))、デフォルトでは対象テキストがすべてのトークンを同時に含むことが要求されます。トークンの出現順序や隣接は要求されません。 - フレーズマッチング(
#"..."):値が#で始まり二重引用符で囲まれている場合(例:#"build error")はフレーズマッチングとなり、分割された各トークンが原文中で順番に隣接して出現することが要求されます(トークン間には空白または句読点の区切り文字のみを挟むことができます)。#と両端の二重引用符はマッチ内容に含まれません。 - 旧形式の二重引用符表記(
"..."):値が二重引用符で始まり二重引用符で終わる場合(例:"build error")、モニター(referer=func)では引き続きフレーズマッチングのセマンティクスが維持されます。その他のクエリ入口では引用符なしのキーワードマッチングと等価です。#"..."に統一することを推奨します。 - 純粋な句読点と特殊境界:
- 上記の引用符の特殊形式で、空白または句読点のみを含む場合(英字、数字、漢字を一切含まない。例:
#"---")、連続するリテラル部分文字列のマッチングにフォールバックします。 - 空のクエリ
""は何にもマッチしません。 - 片側のみに二重引用符がある形式、または二重引用符が両端にない形式は、通常のトークン化検索パラメータとして処理され、特殊な解釈は行われません。
matchまたはreに切り替えるべきケース:- 句読点を厳密に区別する必要がある場合(例:
user_nameとuser-nameを区別する、@や/を完全に含む元の部分文字列をマッチする):match(field, "user_name")を使用してください。 - 単語内部の部分文字列をマッチする必要がある場合(例:
anaでbananaをマッチする。トークン検索では単語内部の断片にヒットしない):match(field, "ana")またはwildcard(field, "*ana*")を使用してください。 - 大文字と小文字を区別する、または複雑な形式でマッチする必要がある場合:
re(field, "...")を使用してください。 - トークン化の詳細と一般的な例については、DQL 全文検索とトークン化ルール を参照してください。
例:
// 「connection」と「timeout」のトークンを含むログをマッチ
L::*:(message) {search("connection timeout")} [15m] LIMIT 20
// 中国語マッチング
L::*:(message) {search("连接超时")} [15m] LIMIT 20
// 中国語と英語の混在
L::*:(message) {search("error 错误")} [15m] LIMIT 20
// 隣接して順序が一致するフレーズマッチング。"build succeeded, parse error" にはマッチしない
L::*:(message) {search("#\"build error\"")} [15m] LIMIT 20
// 旧形式の二重引用符表記。referer=func の場合は引き続きフレーズマッチング
L::*:(message) {search("\"build error\"")} [15m] LIMIT 20
// 句読点のみを含む場合は連続するリテラル部分文字列で直接マッチ
L::*:(message) {search("#\"---\"")} [15m] LIMIT 20
正規表現マッチング¶
re / regex / regexp¶
正規表現マッチング。大文字と小文字を区別します。
構文:
re(pattern)
re(field, pattern)
regex(pattern)
regex(field, pattern)
regexp(pattern)
regexp(field, pattern)
パラメータ:
pattern: 正規表現(PromRegex 構文をサポート)field: フィールド名(省略可能)
例:
// error を含むログをマッチ(大文字と小文字を区別するため ERROR にはマッチしない)
L::*:(message) {re("error.*")} [15m] LIMIT 20
// 特定の形式のエラーコードをマッチ
L::*:(message) {regexp(message, "ERR-\\d{4}")} [15m] LIMIT 20
// データソースで正規表現を使用してメジャーメントをマッチ
M::re('cpu.*'):(avg(usage_total)) [1h] BY host
ワイルドカードマッチング¶
wildcard¶
ワイルドカードパターンマッチング。大文字と小文字を区別します。
構文:
パラメータ:
pattern: ワイルドカードパターン*: 任意の複数文字にマッチ?: 単一文字にマッチfield: フィールド名(省略可能)
例:
// error で始まるメッセージをマッチ(大文字と小文字を区別するため ERROR にはマッチしない)
L::*:(message) {wildcard("error*")} [15m] LIMIT 20
// 特定の形式をマッチ
L::*:(message) {wildcard(message, "ERR-????")} [15m] LIMIT 20
CIDR マッチング¶
cidr¶
IP アドレスのネットワークセグメントマッチング。
構文:
パラメータ:
cidr: CIDR で表されるネットワークセグメント(例:192.168.1.0/24)field: IP アドレスフィールド(省略可能)
例:
// プライベート IP にマッチ
L::nginx:(*) {cidr(client_ip, "10.0.0.0/8")} [15m] LIMIT 20
// 特定のネットワークセグメントにマッチ
L::nginx:(*) {cidr(client_ip, "192.168.1.0/24")} [15m] LIMIT 20
フィールド存在チェック¶
exists¶
フィールドが存在するか確認します。exists() は特殊なプレースホルダーで、通常は比較式の右側に置いて使用します。
構文:
推奨用法:
例:
// pod_name フィールドが存在するコンテナログを検索
L::*:(service, pod_name, message) {pod_name = exists()} [15m] LIMIT 20
// pod_name フィールドが存在しないホストログを検索
L::*:(service, host, message) {pod_name != exists()} [15m] LIMIT 20
クエリ文字列構文¶
query_string¶
クエリ文字列構文を使用して複雑なマッチングを行います。
構文:
パラメータ:
query: クエリ文字列field: フィールド名(省略可能。デフォルトでは全文をマッチ)
クエリ文字列構文:
1. トークンマッチング¶
foo # foo を含む内容にマッチ
"foo bar" # 正確なフレーズマッチング。連続して出現する必要がある
foo\ bar # 空白をエスケープし、"foo bar" というまとまりにマッチ
2. ワイルドカード¶
3. 正規表現¶
4. ブール演算子¶
foo AND bar # 論理 AND。両方を含む必要がある
foo OR bar # 論理 OR。少なくとも一方を含む
NOT foo # 論理 NOT。foo を含まない
# 短縮形式
foo && bar # foo AND bar と等価
foo || bar # foo OR bar と等価
!foo # NOT foo と等価
5. グループ化¶
6. デフォルト演算子¶
空白で複数のトークンを区切る場合、デフォルトでは AND で連結されます(すべてのトークンを同時に含むことが要求されます):
7. トークン化とマッチングルール¶
query_string 内の各通常トークンとフレーズは、search と同じトークン化ルールに従います:
- トークン分割:連続する英字と数字は 1 つのトークン(大文字と小文字は無視)、中国語は語または字で分割されます。空白と各種句読点(
.、_、:、/、-、@、=など)はすべて区切り文字として扱われます。例:query_string("user_name")はuserとnameの両方のトークンを含むデータを検索します。 - フレーズマッチング:二重引用符で囲む(例:
query_string("\"connection reset\""))か、空白をエスケープする(例:query_string("connection\\ reset"))場合、トークン化後のトークンが順番に隣接して出現することが要求されます。 - 句読点や単語内の部分文字列をマッチする場合:句読点はトークン化段階で区切り文字として処理されるため、句読点を厳密に区別する(例:
user_nameとuser.nameを区別する)必要がある場合や、単語内部の部分文字列をマッチする必要がある場合は、match関数に切り替えるか、query_string内で/.../正規表現を使用してください。 - 詳細な分割ルールと一般的な例については、DQL 全文検索とトークン化ルール を参照してください。
例:
// 単純なトークンマッチング
L::*:(message) {query_string("error timeout")} [15m] LIMIT 20
// ブール組み合わせ
L::*:(message) {query_string("error AND NOT timeout")} [15m] LIMIT 20
// 正規表現
L::*:(message) {query_string("/ERR-\\d{4}/")} [15m] LIMIT 20
// 複雑なクエリ
L::*:(message) {query_string("(error OR warn) AND timeout")} [15m] LIMIT 20
// フィールドを指定
L::*:(*) {query_string(message, "error AND timeout")} [15m] LIMIT 20
// 中国語クエリ
L::*:(message) {query_string("错误 AND 超时")} [15m] LIMIT 20
アウター関数¶
使用推奨: 単純な計算を Rollup + 集約関数(例:
[rate]、[last]、[increase]など)で解決できるシナリオでは、Rollup 方式を優先してください。高度な時系列分析(anomalies、outliers、forecastなど、完全な履歴ウォームアップや Series 間のクロスセクション整列が必要な関数)には等価な Rollup 記法がありません。アウター関数として使用し、eval(...)内で名前付きデータソースとして組み合わせることができます。
アウター関数は DQL クエリ結果全体に作用し、クエリが出力する時系列データに対して二次計算を行うために使用します。アウター関数は Select 句の内部に記述するのではなく、DQL 式全体をラップします。
クエリ内関数とアウター関数¶
- クエリ内関数:DQL 式の内部で使用します(例:
sum、avg、maxなど) - アウター関数:DQL クエリ結果全体をラップし、出力される時系列を後処理します
記法の比較:
// Rollup(時間句):まず各時系列で増加率を計算し、次に集約
M::net:(sum(bytes_recv)) [1h::1m:rate] BY host
// アウター関数:まずクエリ結果を取得し、次に二次計算
rate(M::net:(sum(bytes_recv)) [1h::1m] BY host)
構文:
重要な構文上の注意:アウター関数が複数の引数(
moving_average、fill、top、bottomなど)を含み、内側の DQL にBY句が含まれる場合、内側の DQL は括弧(...)で囲む必要があります(例:fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0))。そうしないと、カンマ,がBY句の 2 番目のグループ化フィールドとして優先的に解析され、引数の数エラーが発生します。
例:
// クエリ内関数:元データの平均を計算
M::cpu:(avg(usage_total)) [1h::5m] BY host
// アウター関数:クエリ結果の移動平均を計算(BY 句があり追加引数がある場合は、内側のクエリを括弧で囲む)
moving_average((M::cpu:(avg(usage_total)) [1h::5m] BY host), 5)
累積計算¶
cumsum¶
累積和を計算し、時系列の各点についてそれ以前のすべての点の累積値を計算します。
構文:
例:
差分と導関数¶
使用推奨: これらの関数は Rollup 関数(例:
[rate]、[deriv])として使用することを優先し、アウター関数形式は集約結果に対する二次計算にのみ使用します。
以下の関数はアウター関数として使用できます:
| 関数 | 説明 |
|---|---|
derivative(DQL) |
導関数(変化率)を計算 |
difference(DQL) |
前の値との差分を計算 |
non_negative_derivative(DQL) |
非負導関数を計算 |
non_negative_difference(DQL) |
非負差分を計算 |
rate(DQL) |
増加率(毎秒)を計算 |
irate(DQL) |
瞬間増加率を計算 |
例:
// アウター関数:クエリ結果の導関数を計算
derivative(M::cpu:(avg(usage_total)) [1h::5m] BY host)
// 推奨:クエリ内集約 / Rollup 方式を使用
M::cpu:(deriv(usage_total)) [1h::5m] BY host
移動計算¶
moving_average¶
クエリ結果の移動平均を計算します。
使用推奨: クエリ内 / Rollup 方式
moving_average(field, n)を優先し、アウター関数形式は集約結果に対する二次平滑化にのみ使用します。
構文:
パラメータ:
DQL_expression: DQL クエリ式(BY句を含む場合は括弧(...)で囲む必要があります)n: ウィンドウサイズ(データポイント数)
注意:
- この形式では、数値シーケンスの結果セットに少なくとも
n個の非 NULL データポイントがないと値が出力されません。最初のn-1個の点はnullになります。点数が不足している場合、シーケンス全体がnullになります。 - モニターのように集約間隔を指定しないクエリでは、検出範囲全体が 1 つの点に集約され、各グループにはデータポイントが 1 つしかありません。この場合は、DQL 内で集約ステップを明示的に記述する必要があります(例:
moving_average((L::*:(count(*)) [1m::10s] BY host), 3))。そうしないとウィンドウが埋まらず、値を取得できません。
例:
// アウター関数:クエリ結果の移動平均を計算
moving_average((M::cpu:(avg(usage_total)) [1h::1m] BY host), 5)
// 推奨:クエリ内方式を使用
M::cpu:(moving_average(usage_total, 5)) [1h::1m] BY host
時系列分析と異常検知¶
anomalies¶
1 つの時系列を自身の履歴ベースラインと比較し、履歴パターンから逸脱した時系列異常点を識別します。周期なしのローリングベースライン、日次/週次/時間次の周期ベースライン、レベル適応、自動選択をサポートします。
構文:
anomalies((<metrics-dql>), algorithm='basic|robust|agile|auto', seasonality='hourly|daily|weekly|auto', history='auto'|<duration>, band='mad|quantile', deviation=3, lower_q=0.01, upper_q=0.99, recent_window=30m)
パラメータ:
(<metrics-dql>): 内側のネイティブ Metrics DQL クエリ(時間ウィンドウと固定 step が必須。単一の数値 measure)。algorithm: アルゴリズムタイプ。省略可能。デフォルトはbasic:basic: 周期なしのローリングベースライン。安定している、または固定周期がないメトリクスに適しています。robust: 周期的な堅牢ベースライン(スロットごとの中央値 + MAD で計算)。強い周期性を持つメトリクスに適しています。agile: 周期的な適応ベースライン。直近のステップ状のレベルドリフトに迅速に適応できます。auto: 自動選択。履歴の自己相関係数に基づいて最適な周期を自動選択するか、basicにダウングレードします。seasonality: 周期スロットのタイプ:hourly、daily、weekly、auto。robustとagileでは明示的に指定する必要があります。history: 履歴ウォームアップウィンドウの長さ。デフォルトはauto(basicはmax(12*step, 1h)、robust/agileは 6 つの完全な周期)。band: 正常区間のアルゴリズム:mad(デフォルト)またはquantile(basicのみ)。deviation: 正常区間幅の倍数(MAD ブランチのデフォルトは3)。lower_q/upper_q: 下側/上側パーセンタイル(quantile ブランチのデフォルトは0.01/0.99)。recent_window: レベル調整ウィンドウ(agileのデフォルトは30m)。
戻り値(標準化されたワイドテーブル):
| 列名 | 型 | 説明 |
|---|---|---|
time |
int64 | タイムスタンプ |
value |
float64/null | 実際の観測値 |
expected |
float64/null | モデルが期待するベースライン値 |
lower / upper |
float64/null | 正常区間の下限と上限 |
residual |
float64/null | 実際の値と期待値の残差 |
score |
float64/null | 逸脱度スコア |
is_anomaly |
int64/null | 異常フラグ:1(異常)または 0(正常) |
status |
string | ステータス:ok、missing、insufficient_history、undefined_model など |
algorithm |
string | 実際に適用されたアルゴリズム |
例:
// 日次周期の履歴異常検知
anomalies((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='robust', seasonality='daily')
// eval で複合条件アラートを実行(値が上限を超え、かつ逸脱スコア > 1)
eval(
A.value > A.upper AND A.score > 1,
A=anomalies((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='robust', seasonality='daily')
)
outliers¶
同一時点で同じ Peer 集合内の異なる Series(例:クラスタ内の異なる Pod または Host)を横断比較し、ピアから逸脱した外れ値を識別します。
構文:
outliers((<metrics-dql>), algorithm='mad|dbscan', peer_by=['tag1', ...], tolerance=3, eps=0.5, min_peers=3, scaled=false)
パラメータ:
(<metrics-dql>): 内側のネイティブ Metrics DQL クエリ。peer_by: 必須。文字列配列。Peer 集合を分割するBYタグのサブセットを指定します(例:['cluster']は同じクラスタ内でマシンを比較することを表す)。algorithm: 外れ値アルゴリズム。mad(クロスセクション中央絶対偏差、デフォルト)またはdbscan(1 次元密度クラスタリング)。tolerance: MAD 逸脱の許容倍数。デフォルトは3。eps: DBSCAN の近傍距離。デフォルトは0.5。min_peers: 判定に必要な最小ピア数。デフォルトは3(不足時はinsufficient_peersとマーク)。scaled: スケール正規化を使用するか。デフォルトはfalse。
戻り値(標準化されたワイドテーブル):
| 列名 | 型 | 説明 |
|---|---|---|
time |
int64 | タイムスタンプ |
value |
float64/null | 現在の Peer の実値 |
expected |
float64/null | 同じグループの Peer の中央値(DBSCAN の場合は null) |
lower / upper |
float64/null | 同じグループの正常範囲の下限/上限 |
score |
float64/null | 外れ値スコア |
is_outlier |
int64/null | 外れ値フラグ:1(外れ値)または 0(非外れ値) |
peer_count |
int64/null | 比較に参加した有効な Peer 数 |
status |
string | ステータス:ok、insufficient_peers など |
例:
// 同じ cluster 内で CPU がピアから逸脱している host を検出
outliers((M::cpu:(avg(usage_total) AS value) [1h::5m] BY cluster, host), peer_by=['cluster'], algorithm='mad')
forecast¶
時系列の将来トレンドと周期を予測し、将来時点の予測値と動的信頼区間を出力します。
構文:
// 拡張された正規形式
forecast((<metrics-dql>), algorithm='linear|seasonal|auto', seasonality='hourly|daily|weekly|auto', history='auto'|<duration>, steps=5, deviations=3)
// 互換性のある短縮形式
forecast(DQL_expression, steps)
パラメータ:
(<metrics-dql>): 内側のネイティブ Metrics DQL クエリ。algorithm: 予測アルゴリズム。デフォルトはlinear:linear: 線形トレンド外挿と発散する信頼帯。seasonal: 周期スロットベースライン + レベルドリフト補正 + 線形トレンド外挿。auto: 自動選択。有意な自己相関がある場合はseasonalを選択し、それ以外はlinearにダウングレードします。seasonality: 周期タイプ(hourly、daily、weekly、auto)。history: 履歴ウォームアップウィンドウ。デフォルトはauto(linearはmax(12*step, 1h)、seasonalは 6 周期)。steps: 将来の予測点数。省略可能。デフォルトは5で、正の整数である必要があります。deviations: 信頼帯幅の倍数。デフォルトは3。
戻り値(標準化されたワイドテーブル):
| 列名 | 型 | 説明 |
|---|---|---|
time |
int64 | 将来の予測タイムスタンプ列($To + k \cdot step$) |
forecast |
float64/null | 将来点の予測値 |
lower / upper |
float64/null | 動的信頼区間の下限と上限(ステップ数に応じて自然に発散) |
status |
string | ステータス:ok、insufficient_history、zero_variance |
algorithm |
string | 実際に適用されたアルゴリズム |
例:
// 日次周期性を考慮して、将来 12 点(1 時間)の CPU 推移を予測
forecast((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='seasonal', seasonality='daily', steps=12)
// eval で容量超過予測アラートを実行(将来の平均値が 90% を超える、または上限が 95% を超える)
eval(
F.forecast > 90 OR F.upper > 95,
F=forecast((M::cpu:(avg(usage_total) AS value) [2h::5m] BY host), algorithm='seasonal', seasonality='daily', steps=12)
)
dbscan¶
クエリ結果内の数値時系列に対して DBSCAN 外れ値検出を実行し、数値型の異常フラグを出力します。
構文:
パラメータ:
DQL_expression: DQL クエリ式。通常、時間ウィンドウとBYグループ化を含む複数シリーズのクエリ結果に使用します。eps: 近傍距離のしきい値。省略可能。デフォルトは0.5、範囲は(0, 3.0]。
戻り値:
- 各数値列に対して対応する
dbscan(column)数値列を出力します。 1は外れ値を表し、0は非外れ値を表します。- 有効な数値点が 5 個未満の場合は NULL を返し、サンプル不足で検出未実施であることを表します。
説明:
- 少なくとも 5 つの有効な数値点が必要です。有効な点が不足している場合は NULL を返します。
- 現在の実装では、入力テーブルの各数値列に対して個別に 1 次元 DBSCAN を実行し、時間列を保持します。
例:
// デフォルト eps=0.5 を使用して CPU 使用率の外れ値を検出
dbscan(M::cpu:(avg(usage_total)) [1h::5m] BY host)
// eps を明示的に指定
dbscan(M::cpu:(avg(usage_total)) [1h::5m] BY host, 0.8)
TopN¶
top / bottom¶
使用推奨: クエリ内方式
top(field, n)またはbottom(field, n)を優先し、アウター関数形式は集約結果に対する二次フィルタにのみ使用します。
クエリ結果から TopN または BottomN を取得します。
構文:
例:
// アウター関数:クエリ結果から TopN を取得(内側に BY 句がある場合は括弧で囲む)
top((T::*:(max(duration)) [1h::5m] BY service), 5)
// 推奨:クエリ内方式を使用
T::*:(top(duration, 5)) [1h::5m] BY service
NULL 値の補完¶
fill¶
クエリ結果内の NULL 値を補完します。
詳細は fill 関数 を参照してください。
例:
// 0 で NULL 値を補完(内側に BY 句がある場合は括弧で囲む)
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0)
// 線形補間で補完
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), LINEAR)
その他のアウター関数¶
以下の関数もアウター関数として使用できます:
| 関数 | 説明 |
|---|---|
abs(DQL) |
絶対値を取得 |
round(DQL) / ceil(DQL) / floor(DQL) |
丸め |
log(DQL) / log2(DQL) / log10(DQL) |
対数変換 |
set(DQL) |
重複排除とソート |
concat(DQL) |
文字列連結 |
series_sum(DQL [, ['tag1', ...]]) |
時系列(Series)間の二次合計 |
組み合わせて使用¶
アウター関数は組み合わせてネストできます:
// 移動平均を計算して四捨五入
round(moving_average((M::cpu:(avg(usage_total)) [1h::1m] BY host), 5))
// 増加率の移動平均を計算
moving_average(rate(M::net:(sum(bytes_recv)) [1h::5m] BY host), 3)
eval 式の計算¶
eval は特殊な関数で、クエリの外部で式の計算を実行できます。複数のサブクエリ結果を参照して複合演算を行うことができます。
構文¶
パラメータ:
expression: 数学式。name.field(または単一列の別名name)を使用してサブクエリ結果を参照name=(query): 名前付きサブクエリalias: 結果の別名(省略可能)
説明:
evalはname="query"という従来の記法にも互換性がありますが、型表現と可読性の観点からname=(query)の使用を推奨します。
動作原理¶
- すべての名前付きサブクエリを実行
- 時間とグループ化タグで各サブクエリの結果を整列
- 各時点で式を計算
- 計算結果を返す
ユースケース¶
- 複数のメトリクスまたは異なるデータソースの比率を計算(例:エラー率、メモリ使用率)
- 複数のメジャーメント(例:
cpuとmem)を組み合わせて総合スコアを算出 anomaliesまたはforecastと組み合わせて複数条件の複合アラート判定を行う
例¶
APM サービスのエラー率(パーセント)を計算¶
// エラー率 = エラーリクエスト数 / 総リクエスト数 * 100
eval(a / b * 100,
a=(T::*:(count(*)) {status = 'error'} [1h] BY service),
b=(T::*:(count(*)) [1h] BY service),
alias="error_rate_pct")
ホストのメモリ使用率を計算¶
// 使用率 = used / total * 100
eval(used / total * 100,
used=(M::mem:(avg(used)) [1h] BY host),
total=(M::mem:(avg(total)) [1h] BY host),
alias="memory_usage_percent")
ネットワークパケットエラー率を計算¶
// 受信エラー率 = err_in / packets_recv * 100
eval(err / pkt * 100,
err=(M::net:(sum(err_in)) [1h::5m:increase] BY host),
pkt=(M::net:(sum(packets_recv)) [1h::5m:increase] BY host),
alias="packet_error_rate")
サブクエリの特定フィールドを参照¶
// 同じサブクエリまたは異なるサブクエリの特定の別名フィールドを参照
eval(a.user_cpu / b.total_cpu * 100,
a=(M::cpu:(avg(usage_user) AS user_cpu) [1h] BY host),
b=(M::cpu:(avg(usage_total) AS total_cpu) [1h] BY host),
alias="user_cpu_share_pct")
注意事項¶
- すべてのサブクエリの時間ウィンドウは互換性がある必要があります
- サブクエリのグループ化ディメンションは一致している必要があります
- 式内で参照するフィールド名は
name.field形式を使用します(サブクエリのプロジェクション列が 1 つだけの場合、nameで直接参照することもできます)
その他の関数¶
fill¶
クエリ結果内の NULL 値を指定値で補完します。
推奨使用方式:
fillはアウター関数として使用することを推奨します。クエリ結果全体に作用します(注意:内側の DQL にBY句が含まれる場合は、内側のクエリを括弧(...)で囲む必要があります):また、Select 句内でも
fill(avg(usage_total), 0)のクエリ内記法をサポートします:
構文(アウター関数):
パラメータ:
DQL_expression: DQL クエリ式(BY句を含む場合は括弧で囲む必要があります)value: 補完値。複数のモードをサポート:- 具体値:数値、文字列、null
LINEAR:線形補間PREVIOUS:直前の非 NULL 値で補完
例:
// 推奨:アウター関数として使用し、空のバケットを 0 で補完
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0)
// 線形補間で補完
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), LINEAR)
// 直前の非 NULL 値で補完
fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), PREVIOUS)
now¶
現在のタイムスタンプ(ミリ秒)を返します。
構文:
例:
// 直近 10 分間(600000 ミリ秒)にレポートがあるホストオブジェクトをクエリ
O::HOST:(host, state, cpu_usage) {last_update_time > now() - 600000} LIMIT 20
unwrap¶
集約関数の出力列名の外側にある関数名ラップを除去し、結果の列名を内部フィールド名のままにします(例:avg(usage_total) の出力列名を usage_total に戻す。これは avg(usage_total) AS usage_total と等価)。
構文:
例:
Show 関数¶
Show 関数はメタデータ(measurement、tag、field、基数、系列カウントなど)を確認するために使用し、モデリング調査やクエリ前の確認によく使用します。
共通構文¶
where、time_window、LIMIT、OFFSETはすべてオプションです。LIMIT/OFFSETは負の値にできません。
M 名前空間の組み込み Show 関数¶
| 関数 | パラメータ | 返却列 | 説明 |
|---|---|---|---|
show_measurement |
省略可能 re('pattern') |
name |
measurement を一覧表示 |
show_tag_key |
省略可能 from=['measurement']、省略可能 by='field' |
tagKey;by='field' の場合は name、field、tagKey |
tag key を一覧表示。by='field' はフィールドごとにグループ化して返し、1 回のスキャンでメジャーメント全体をカバー |
show_field_key |
省略可能 from=['measurement'] |
fieldKey, fieldType |
field key を一覧表示(現在の fieldType は float) |
show_tag_value |
keyin=['tagKey'](必須)、省略可能 from、省略可能 by='field' |
key, value;by='field' の場合は name、field、key、value |
tag value を一覧表示。by='field' はフィールドごとにグループ化して返し、1 回のスキャンでメジャーメント全体をカバー |
show_measurement_cardinality |
必須パラメータなし | count |
measurement 数 |
show_series_cardinality |
必須パラメータなし | count |
series 基数(推定) |
show_tag_key_cardinality |
必須パラメータなし | count |
tag key 基数(推定) |
show_tag_value_cardinality |
keyin=['tagKey'](必須) |
count |
指定した tag key の value 基数(推定) |
show_field_key_cardinality |
必須パラメータなし | count |
field key 基数(推定) |
show_series_count_by_field_key |
from=['measurement'](推奨) |
name, count |
field key ごとに series 数を集計 |
show_series_count_by_tag_key |
from=['measurement'](推奨) |
name, count, value_count |
tag key ごとに series 数と value 数を集計 |
show_series_count_by_tag_value |
keyin=['tagKey'](必須)、from=['measurement'](推奨) |
name, count |
指定した tag key の value ごとに series 数を集計 |
基数(cardinality)関連の関数は内部で HyperLogLog をマージし、戻り値は推定値です。
M 以外の名前空間の Show 関数¶
M 以外の名前空間(ログ L、トレース T、オブジェクト O、RUM R、ネットワーク N、セキュリティイベント E、計量 metering など)では、明示的な namespace パラメータの使用を推奨します:
show_source(namespace='L')show_field(namespace='L', source='mysql')show_label(namespace='L', name='env')show_index(namespace='L')show_class(namespace='L')show_type(namespace='L')
例:
show_source(namespace='L')
show_field(namespace='L')
show_field(namespace='T', source='mysql')
show_label(namespace='L', name='env')
show_label(namespace='L', names=['env', 'team'])
show_index(namespace='L')
show_field(namespace='metering')
後方互換の記法(サフィックスモード)¶
既存のクライアントとクエリ履歴との互換性のため、システムは以下のサフィックスモードを引き続き保持します:
show_<namespace>_sourceshow_<namespace>_classshow_<namespace>_typeshow_<namespace>_fieldshow_<namespace>_labelshow_<namespace>_index
ここで <namespace> は関数名の中間部分から自動マッピングされます。例:
show_logging_source->Lshow_tracing_field->Tshow_object_source->O
一般的な例:
show_logging_source()
show_tracing_field('mysql')
show_logging_field('*')
show_logging_label(name='env')
show_logging_label(names=['env', 'team'])
パラメータと動作の説明¶
from:measurement のリスト。文字列または文字列配列をサポート。keyin:tag key のリスト。文字列または文字列配列をサポート。field:field のリスト。文字列または文字列配列をサポート(metric show の field フィルタに使用)。show_fieldの場合:source(または別名from):データソース名。単一の文字列または文字列配列をサポート(例:source='mysql'またはsource=['mysql', 'redis'])。指定しない場合、またはsource='*'を指定した場合は全データソースのフィールドをクエリすることを表します。- 新しい関数では名前なし位置引数を渡せません。明示的に名前付きパラメータを使用する必要があります。
- その他の名前付きパラメータ(例:
env='prod')は、基盤データクエリの where フィルタ条件に変換されます。 - 後方互換関数
show_<namespace>_fieldの場合: - 従来の位置引数のロジックを保持します。最初の名前なし引数(例:
'mysql')は source フィルタとして扱われ、'*'は source を指定しない場合と等価です。 - 名前付きパラメータは where フィルタ条件に変換されます。
isVariantFieldは、そのフィールドが独立した物理列ではなく variant(var object)列に格納されていることを表します。複数の index にまたがるクエリでは、いずれか 1 つの index が variant 列に格納していればtrueを返します。show_*_labelの場合:- 名前付きパラメータが必要です。
namesはnameの別名として扱われます。
制約と注意事項¶
show_tag_valueとshow_tag_value_cardinalityではkeyinが必須です。show_tag_key(..., by='field')とshow_tag_value(..., by='field')は(name, field)でグループ化して返します。LIMIT/OFFSETは各グループにそれぞれ作用し、すべてのフィールドで 1 つのページング割り当てを共有することはありません。結果はさらに独立したサーバー側の総量上限の制約を受け、この上限はLIMIT/OFFSETによって縮小されません。- グループ化された tag key は
tagKeyでソートしてからページングします。グループ化された tag value は、まずkeyinと各 key の値を重複排除し、次に(key, value)でソートします。各フィールドは 1 回だけページングされます。例:keyin=['host', 'zone'] LIMIT 1 OFFSET 1は各フィールドのソート後の 2 行目を返し、各 key ごとに 1 行を返すわけではありません。 by='field'の結果には、フィールドに紐づけられるデータのみが含まれます。結果に特定のフィールドがない場合は、show_field_keyでそのフィールドが存在するか確認できます。show_tag_value(..., by='field')のkey列は、keyinで指定した tag key です。- グループ化された tag value クエリは、時間範囲内にサンプルが存在するか検証します。候補シリーズが多すぎる場合はインデックスクエリにフォールバックし、結果に指定時間範囲外にのみ出現する値が含まれる可能性があります。
show_series_count_by_tag_valueではkeyinが必須です。show_series_count_by_*ではfromを指定するか、where で等価な source 制約(例:@__source__条件)を指定する必要があります。show_<namespace>_source、show_<namespace>_class、show_<namespace>_typeは現在同じ実行パスを共有し、source の重複排除リストを返します。- Query API が show の時間範囲を提供しない場合、一部のログ show クエリは直近 30 分のウィンドウで実行されるようにフォールバックします。
返却例¶
以下の例は典型的な列構造と例示行のみを示しています。実際の結果はテナントデータ、フィルタ条件、時間範囲、LIMIT/OFFSET の影響を受けます。
| クエリ | 典型的な列 | 例示行(イメージ) |
|---|---|---|
show_measurement() |
name |
cpu、disk、memory |
show_tag_key(from=['windows'], by='field') |
name, field, tagKey |
windows, usage, host;windows, idle, device |
show_tag_value(from=['windows'], keyin=['host'], by='field') |
name, field, key, value |
windows, usage, host, node-1;windows, idle, host, node-3 |
show_tag_value(from=['cpu'], keyin=['host']) |
key, value |
host, web-01;host, web-02 |
show_series_count_by_tag_key(from=['cpu']) |
name, count, value_count |
host, 3200, 120;service, 2800, 35 |
show_tag_value_cardinality(keyin=['host']) |
count |
120 |
show_logging_field('*') |
fieldKey, fieldType, fieldIndices, isVariantField |
service, keyword, [{"type":"inverted"}], false |
show_logging_source() |
source |
nginx、mysql、redis |
関数分類クイックリファレンス¶
基本集約¶
| 関数 | 説明 | 正確/推定 |
|---|---|---|
| sum | 合計 | 正確 |
| avg | 平均値 | 正確 |
| count | カウント | 正確 |
| count(distinct) | 正確な重複排除カウント | 正確 |
| count_distinct | 重複排除カウント | 推定 (HyperLogLog, 誤差≈0.4%) |
| min / max | 最小/最大値 | 正確 |
| first / last | 最初/最後の値 | 正確 |
| any | 任意の値 | 正確 |
統計集約¶
| 関数 | 説明 | 正確/推定 |
|---|---|---|
| percentile / pXX | パーセンタイル | 推定 (対数ヒストグラム) |
| median |