コンテンツにスキップ

DQL 関数リファレンス


DQL は、データの集約、変換、マッチングに使用する豊富な関数を提供します。本ドキュメントでは、各関数のセマンティクス、パラメータ、使用方法について詳しく説明します。

集約関数

集約関数は複数行のデータを単一の値に集約するために使用し、通常は時間ウィンドウ(time-expr)とグループ化(BY 句)と組み合わせて使用します。

基本集約

sum

フィールド値の合計を計算します。

構文:

sum(field)

パラメータ:

  • 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

フィールド値の平均値を計算します。

構文:

avg(field)

パラメータ:

  • 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 フィールド値の数を計算します。

構文:

count(field)
count(distinct(field))
count(*)

パラメータ:

  • field: 任意のフィールド。非 NULL 値の数を計算
  • distinct(field): フィールドの正確な重複排除値数を計算
  • *: すべての行数を計算(ログ L、トレース T、オブジェクト O、RUM R、イベント 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

フィールドの最小値または最大値を計算します。

構文:

min(field)
max(field)

パラメータ:

  • 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

最初または最後の値(時系列順)を取得します。

構文:

first(field)
last(field)
last_row(field)

パラメータ:

  • 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 件)を取得する場合や、特定の時間順序が不要な場合に適しています。

構文:

any(field)

パラメータ:

  • 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 は、プロジェクション内で履歴ウィンドウの集約値を参照し、現在の集約結果と整列して表示します:

<aggregate-or-subquery-measure> SHIFT <duration>

現在値、履歴値、派生計算はすべてプロジェクション式で明示します。同じ履歴値を複数回参照する場合は、同じ 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

範囲(最大値と最小値の差)を計算します。

構文:

spread(field)

パラメータ:

  • 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

標準偏差を計算し、メトリクスまたは所要時間のばらつきの度合いを測定します。

構文:

stddev(field)

パラメータ:

  • field: 数値フィールド

例:

// 各ホストの CPU 使用率の標準偏差を計算
M::cpu:(stddev(usage_total) AS cpu_stddev) [1h] BY host

// 各サービスの応答時間の標準偏差を計算
T::*:(stddev(duration) AS duration_stddev) [1h] BY service

mode

最頻値(最も多く出現する値)を計算します。

構文:

mode(field)

パラメータ:

  • field: 任意のフィールド

例:

// 各サービスの APM 呼び出しで最も多く出現する HTTP ステータスコードを検出
T::*:(mode(http_status_code) AS most_common_status) [1h] BY service

count_series

時系列(Series)の数を計算し、現在のクエリ範囲内に独立した時系列がいくつあるかを返します。

構文:

count_series(field)

パラメータ:

  • 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

フィールドの異なる値の数を計算します(推定値)。

構文:

count_distinct(field)

パラメータ:

  • 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

フィールドのパーセンタイル(推定値)を計算します。

構文:

percentile(field, n)
pXX(field)  // 短縮形式(XX は 1〜99 の整数)

パラメータ:

  • 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) と等価です。

構文:

median(field)

例:

// 各サービスの応答時間の中央値を計算
T::*:(median(duration) AS median_duration) [1h] BY service

ヒストグラム関数

DQL は 3 種類のヒストグラム関連関数を提供しており、異なるデータソースとシナリオに適しています:

関数 ユースケース データソースタイプ 推奨度
histogram_auto ログ、Trace などの明細データの数値分布統計 明細モデル(ログ/Trace) ⭐⭐⭐ 推奨
histogram 固定バケット境界が必要なヒストグラム 明細モデル(ログ/Trace) ⭐⭐ Deprecated
histogram_quantile Prometheus ヒストグラムメトリクスからパーセンタイルを計算 Prometheus メトリクス ⭐⭐⭐ 推奨

histogram_auto(推奨)

分布ヒストグラムを自動生成し、ログ、Trace などの明細データの数値分布統計向けに設計されています。

特徴:

  • バケット境界の指定が不要で、データ分布に自動適応
  • 対数線形補間ヒストグラムアルゴリズムを使用し、10⁻⁹ から 10¹⁸ の数値範囲をカバー
  • パーセンタイル統計とバケット分布情報を同時に返す

構文:

histogram_auto(field)

パラメータ:

  • 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 はデータ分布に自動適応し、より広範な数値範囲をカバーし、より豊富な統計情報を返します。

構文:

histogram(field, left_bound, right_bound, bucket_size [, threshold])

パラメータ:

  • 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)である必要があります

構文:

histogram_quantile(field, q)

パラメータ:

  • 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 の境界を識別します:

  1. Prometheus 形式(デフォルト):le タグで bucket の上限を直接表現
  2. le の値は数値(例:"0.1"、"1"、"10")または "+Inf"(無限大)
  3. データは累積カウント(cumulative)である必要があります

  4. VictoriaMetrics 形式:vmrange タグで範囲を表現

  5. 形式は "下限...上限"(例:"0.1...0.2")
  6. データは範囲カウント(非累積)
  7. 関数は範囲カウントを自動的に累積カウントに変換

計算プロセス: 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:

M::http_request_duration:(histogram_quantile(duration_bucket, 0.99)) [1h] BY service

PromQL 等価:

histogram_quantile(0.99, sum(rate(http_request_duration_bucket[1h])) by (le, service))

シナリオ 2:各サービスの P95 レイテンシを計算(複数グループ化)

DQL:

M::http_request_duration:(
    histogram_quantile(duration_bucket, 0.95)
) [1h] BY service, endpoint

PromQL 等価:

histogram_quantile(0.95, sum(rate(http_request_duration_bucket[1h])) by (le, service, endpoint))

シナリオ 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 タグが必須です。ない場合は計算できません
  • +Inf bucket がない場合、最後の bucket の上限が最大値として使用されます
  • カウントが 0 または NaN の bucket はスキップされます
  • パーセンタイル < 0 の場合は -Inf、> 1 の場合は +Inf を返します

TopN 関数

top

グループ内で上位 N 個の最大値を取得します。

構文:

top(field, 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 個の最小値を取得します。

構文:

bottom(field, 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 行)を返します。

構文:

distinct(field)

例:

// 各サービスでログに出現したすべてのログステータスレベルを取得
L::*:(distinct(status)) [1h] BY service

結果例:

service distinct(status)
api info
api warn
api error
web info

注:複数行を返し、各行に異なる値が 1 つ含まれます。


distinct_by_collapse

折りたたみ戦略に従ってフィールドの異なる値を取得し、重複排除時に指定した他のフィールドの最後の値を保持します。

構文:

distinct_by_collapse(field, [last_field1, last_field2, ...])

パラメータ:

  • 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

すべての値(重複を含む)を収集し、配列型を返します。

構文:

collect(field [, limit])

パラメータ:

  • 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

すべての異なる値を収集し、重複排除後の配列を返します。

構文:

collect_distinct(field [, limit])

パラメータ:

  • 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_values(field)

パラメータ:

  • field: 任意のフィールド(スカラーまたは配列フィールド。配列フィールドは自動的に展開され、各要素の出現回数を集計)

例:

// ログ内の status フィールドのすべての値と、各値のログ件数を集計
L::*:(field_values(status)) [1h]

結果例:

field_values(status) hits
"info" 15420
"warn" 320
"error" 45

注:複数行を返し、重複排除後のフィールド値列 field_values(field) と対応する出現回数列 hits を含みます。


フィルタ集約

count_filter

フィールド値が指定リストに含まれる数量を集計します。

構文:

count_filter(field, [value1, value2, ...])

パラメータ:

  • 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

フィールドにデフォルト値を設定し、集約結果が空の場合にデフォルト値を返します。

構文:

default(field, default_value)

パラメータ:

  • field: 任意のフィールド
  • default_value: デフォルト値(数値、文字列、ブール値、または null を指定可能)

例:

// NULL 値に対してデフォルトの所要時間 0 を設定
T::*:(default(duration, 0)) [1h] BY service

時系列関数

時系列関数は、時間とともに変化するデータ、特に 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(field)

説明: 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 メトリクスの瞬間増加率(毎秒)を計算します。

構文:

irate(field)

説明: rate と異なり、irate はウィンドウ内の最後の 2 つのデータポイントのみを使用して増加率を計算します。瞬間的な変化率を反映し、短期的なスパイクに敏感です。

例:

// 各ホストの NIC の瞬間受信バイトレートを計算
M::net:(sum(bytes_recv) AS instant_recv_bps) [1h::1m:irate] BY host

increase

Counter メトリクスの時間ウィンドウ内の総増加量を計算します。

構文:

increase(field)

説明: increase は毎秒レートではなく、時間ウィンドウ内の累積増分を返します。

例:

// 各ホストの過去 1 時間における 5 分ごとの受信パケット増加数を計算
M::net:(sum(packets_recv) AS new_packets) [1h::5m:increase] BY host

rate_over_sum

毎秒の平均値(sum(field) / 時間ウィンドウの秒数)を計算します。

構文:

rate_over_sum(field)

説明: sum(field) / 時間ウィンドウ(秒) と等価で、ウィンドウ内でレポートされた非累積増分値を毎秒レートに変換するために使用します。

rate との違い:

  • rate:単調増加する Counter の増加率を計算(先頭と末尾の差分を時間差で割り、リセットを処理)
  • rate_over_sum:ウィンドウ内のすべてのサンプル値を合計し、時間ウィンドウの秒数で割る

例:

// ウィンドウ内のバイト数を合計し、ウィンドウの秒数で割る
M::net:(rate_over_sum(bytes_recv)) [1h] BY host

rate_over_count

毎秒のイベント発生回数(count(field) / 時間ウィンドウの秒数)を計算します。

構文:

rate_over_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 スタイル)です。

構文:

// Counter メトリクス:非負の変化率を計算(リセットによる負の値を無視)
rate(field)

// Gauge メトリクス:完全な変化率を計算(負の値を含む)
deriv(field)

関数の選択:

関数 説明 ユースケース
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

移動平均値を計算します。

構文:

moving_average(field, n)

パラメータ:

  • 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 は平滑化係数で、明示的に渡す必要があります。

構文:

ewma(field, 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

シーケンスの時間変化に対する線形トレンドの傾きを計算します。時間単位は秒です。

構文:

slope(field)

説明:

  • 少なくとも 2 つの有効な点が必要です。
  • 時間が変化していない場合、または有効な点が不足している場合は NULL を返します。

例:

// メモリ使用量の線形成長の傾きを計算(メモリリークの傾向評価に使用)
M::mem:(slope(used)) [1h::5m] BY host

zscore

最新点の、ウィンドウ内の平均値と標準偏差に対する Z-Score を計算します。

構文:

zscore(field)

説明:

  • 結果は (latest - mean) / stddev です。
  • 少なくとも 2 つの有効な点が必要です。標準偏差が 0 の場合は NULL を返します。

例:

// 各ホストの最新 CPU 使用率が履歴ウィンドウからどの程度逸脱しているかを評価
M::cpu:(zscore(usage_total)) [1h::5m] BY host

mad_score

最新点の MAD(Median Absolute Deviation)異常スコアを計算します。

構文:

mad_score(field)

説明:

  • 中央値と MAD を使用して最新点の逸脱度を測定します。平均値/標準偏差よりも極端値に対して堅牢です。
  • 少なくとも 2 つの有効な点が必要です。MAD が 0 の場合は NULL を返します。

例:

// 堅牢な異常スコアで最新の CPU 使用率点を検出
M::cpu:(mad_score(usage_total)) [1h::5m] BY host

change_score

ウィンドウ内のシーケンスの変化点スコアを計算し、平均値が明らかに切り替わる時系列を検出するために使用します。

構文:

change_score(field)

説明:

  • 考えられる分割点を列挙し、分割点の左右 2 区間の平均値の差を比較して、プールされた標準偏差で正規化します。
  • 少なくとも 4 つの有効な点が必要です。有効な点が不足している場合は NULL を返します。

例:

// メモリ使用率がウィンドウ内でステップ状の変化を起こしているか検出
M::mem:(change_score(used_percent)) [1h::5m] BY host

corr

2 つの数値フィールド間の Pearson 相関係数を計算します。

構文:

corr(left_field, right_field)

説明:

  • 戻り値の範囲は通常 [-1, 1] です。
  • 少なくとも 2 組の有効な点が必要です。いずれかのフィールドに変化がない場合は NULL を返します。
  • corr は 2 つの入力フィールドを必要とし、時間句の Rollup 記法はサポートされません。

例:

// ユーザー空間 CPU とカーネル空間 CPU 使用率の相関を計算
M::cpu:(corr(usage_user, usage_system)) [1h::5m] BY host

cumsum

累積和(アウター関数)を計算します。

構文:

cumsum(DQL_expression)

例:

// 各サービスのログ件数の累積和を計算
cumsum(L::*:(count(*)) [1h::5m] BY service)

変換関数

変換関数は、フィールド値に対する数学演算、型変換、文字列処理に使用します。

数学関数

abs

絶対値を計算します。

構文:

abs(field)

例:

// メモリ変化率の絶対値を計算
M::mem:(abs(deriv(used))) [1h::5m] BY host

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

対数関数です。

構文:

log(field)    // 自然対数
log2(field)   // 底 2
log10(field)  // 底 10

例:

// 応答時間の底 10 の対数変換値を計算
T::*:(log10(duration)) [1h] BY service

型変換

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

文字列を小文字に変換します。

構文:

lower(field)

パラメータ:

  • field: 文字列フィールド

戻り値: 変換後の小文字文字列を返します。

例:

// ログの status を小文字に統一してグループ集計
L::*:(count(*)) [1h] BY lower(status) AS norm_status

upper

文字列を大文字に変換します。

構文:

upper(field)

パラメータ:

  • field: 文字列フィールド

戻り値: 変換後の大文字文字列を返します。

例:

// ログの status を大文字に統一して表示
L::*:(service, upper(status) AS status_upper, message) [15m] LIMIT 10

trim

文字列の両端の空白文字を除去します。

構文:

trim(field)

パラメータ:

  • field: 文字列フィールド

戻り値: 両端の空白を除去した文字列を返します。

例:

// service フィールドの両端に存在する可能性のある空白文字を除去してグループ化
L::*:(count(*)) [1h] BY trim(service) AS clean_service

ltrim

文字列の左側の空白文字を除去します。

構文:

ltrim(field)

パラメータ:

  • field: 文字列フィールド

戻り値: 左側の空白を除去した文字列を返します。

例:

// ログメッセージの左側の空白文字を除去
L::*:(ltrim(message) AS trimmed_msg) [15m] LIMIT 10

rtrim

文字列の右側の空白文字を除去します。

構文:

rtrim(field)

パラメータ:

  • field: 文字列フィールド

戻り値: 右側の空白を除去した文字列を返します。

例:

// ログメッセージの右側の空白または改行文字を除去
L::*:(rtrim(message) AS trimmed_msg) [15m] LIMIT 10

length

文字列の長さ(文字数)を返します。

構文:

length(field)

パラメータ:

  • field: 文字列フィールド

戻り値: 文字列の長さを返します。

例:

// ログ本文の文字数を確認し、長すぎるログをフィルタ
L::*:(service, length(message) AS msg_len) {CASE WHEN length(message) > 1000 THEN true ELSE false END} [15m] LIMIT 10

substr

部分文字列を切り出します。

構文:

substr(field, start)
substr(field, start, length)

パラメータ:

  • 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

正規表現で抽出します。

構文:

regexp_extract(field, pattern)
regexp_extract(field, pattern, n)

パラメータ:

  • 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

すべてのマッチ結果を抽出します。

構文:

regexp_extract_all(field, pattern)
regexp_extract_all(field, pattern, n)

戻り値: すべてのマッチした部分文字列を含む文字列配列を返します。

例:

// ログメッセージ内のすべての数字シーケンスを抽出
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

正規表現を使用してマッチしたテキストを置換します。

構文:

regexp_replace(field, pattern, replacement)

パラメータ:

  • 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 ハッシュ値を計算します。

構文:

md5(field)

戻り値: 32 文字の 16 進文字列(小文字)を返します。

例:

// ログメッセージの MD5 フィンガープリントを計算
L::*:(service, md5(message) AS msg_md5) [15m] LIMIT 20

結果例:

service md5(message)
api 5d41402abc4b2a76b9719d911017c592
web 098f6bcd4621d373cade4e832627b4f6

concat

文字列を連結します。

構文:

concat(field, ...)

戻り値: 連結後の単一文字列を返します。

例:

// サービス名とログステータスを連結(例:"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

配列フィールドの重複を排除してソートします。

構文:

set(DQL_expression)

戻り値: 重複排除およびソート後の配列を返します。

例:

// collect で収集したステータスリストの重複を排除してソート
set(L::*:(collect(status)) [1h] BY service)

結果例:

service set(collect(status))
api ["error", "info", "warn"]
web ["info", "warn"]

ログクラスタリング

drain

Drain アルゴリズムを使用して類似ログを同じクラスタにまとめ、そのクラスタのログテンプレートを返します。

構文:

drain(field, similarity_threshold)
drain(field, similarity_threshold, max_clusters)

パラメータ:

  • field: 文字列フィールドまたは文字列式。通常は message
  • similarity_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 ... to /api/users took ms" 128
"Query SELECT * FROM orders executed in ms" 42

マッチング関数

マッチング関数は WHERE 句でテキストマッチングを行うために使用します。

部分文字列マッチング

match

フィールドに指定した部分文字列が含まれるか確認します。

構文:

match(pattern)
match(field, pattern)

パラメータ:

  • 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)
search(field, query)

パラメータ:

  • 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

ワイルドカードパターンマッチング。大文字と小文字を区別します。

構文:

wildcard(pattern)
wildcard(field, pattern)

パラメータ:

  • pattern: ワイルドカードパターン
  • *: 任意の複数文字にマッチ
  • ?: 単一文字にマッチ
  • field: フィールド名(省略可能)

例:

// error で始まるメッセージをマッチ(大文字と小文字を区別するため ERROR にはマッチしない)
L::*:(message) {wildcard("error*")} [15m] LIMIT 20

// 特定の形式をマッチ
L::*:(message) {wildcard(message, "ERR-????")} [15m] LIMIT 20

CIDR マッチング

cidr

IP アドレスのネットワークセグメントマッチング。

構文:

cidr(cidr)
cidr(field, cidr)

パラメータ:

  • 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() は特殊なプレースホルダーで、通常は比較式の右側に置いて使用します。

構文:

exists()

推奨用法:

field = exists()   // フィールドが存在(非 NULL)
field != 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_string(query)
query_string(field, query)

パラメータ:

  • query: クエリ文字列
  • field: フィールド名(省略可能。デフォルトでは全文をマッチ)

クエリ文字列構文:

1. トークンマッチング
foo              # foo を含む内容にマッチ
"foo bar"        # 正確なフレーズマッチング。連続して出現する必要がある
foo\ bar         # 空白をエスケープし、"foo bar" というまとまりにマッチ
2. ワイルドカード
foo*             # foo で始まる内容にマッチ
foo?bar          # ? は単一文字にマッチ
"foo*bar"        # 引用符内のワイルドカードは解析されず、リテラルとしてマッチ
3. 正規表現
/foo.*bar/       # スラッシュで囲まれた正規表現
/joh?n(ath[oa]n)/  # 複雑な正規表現
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. グループ化
(foo OR bar) AND baz       # 括弧を使用して優先順位を変更
!(status 429 reading)      # 式全体を否定
6. デフォルト演算子

空白で複数のトークンを区切る場合、デフォルトでは AND で連結されます(すべてのトークンを同時に含むことが要求されます):

foo bar          # foo AND bar と等価
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)

構文:

outer_function((DQL_expression) [, arg2, ...])

重要な構文上の注意:アウター関数が複数の引数(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

累積和を計算し、時系列の各点についてそれ以前のすべての点の累積値を計算します。

構文:

cumsum(DQL_expression)

例:

// 各サービスのログ件数の累積和を計算
cumsum(L::*:(count(*)) [1h::5m] BY service)

差分と導関数

使用推奨: これらの関数は 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) を優先し、アウター関数形式は集約結果に対する二次平滑化にのみ使用します。

構文:

moving_average((DQL_expression), 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 外れ値検出を実行し、数値型の異常フラグを出力します。

構文:

dbscan(DQL_expression)
dbscan(DQL_expression, eps)

パラメータ:

  • 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 を取得します。

構文:

top((DQL_expression), n)
bottom((DQL_expression), n)

例:

// アウター関数:クエリ結果から 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 は特殊な関数で、クエリの外部で式の計算を実行できます。複数のサブクエリ結果を参照して複合演算を行うことができます。

構文

eval(expression, name1=(query1), name2=(query2), ..., alias="result_name")

パラメータ:

  • expression: 数学式。name.field(または単一列の別名 name)を使用してサブクエリ結果を参照
  • name=(query): 名前付きサブクエリ
  • alias: 結果の別名(省略可能)

説明:eval は name="query" という従来の記法にも互換性がありますが、型表現と可読性の観点から name=(query) の使用を推奨します。

動作原理

  1. すべての名前付きサブクエリを実行
  2. 時間とグループ化タグで各サブクエリの結果を整列
  3. 各時点で式を計算
  4. 計算結果を返す

ユースケース

  • 複数のメトリクスまたは異なるデータソースの比率を計算(例:エラー率、メモリ使用率)
  • 複数のメジャーメント(例: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 句が含まれる場合は、内側のクエリを括弧 (...) で囲む必要があります):

fill((M::cpu:(avg(usage_total)) [1h::5m] BY host), 0)

また、Select 句内でも fill(avg(usage_total), 0) のクエリ内記法をサポートします:

M::cpu:(fill(avg(usage_total), 0)) [1h::5m] BY host

構文(アウター関数):

fill((DQL_expression), value)
fill((DQL_expression), LINEAR)
fill((DQL_expression), PREVIOUS)

パラメータ:

  • 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

現在のタイムスタンプ(ミリ秒)を返します。

構文:

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 と等価)。

構文:

unwrap(aggregate_expression)

例:

// avg(usage_total) を計算し、返却列名を usage_total に簡略化
M::cpu:(unwrap(avg(usage_total))) [1h] BY host

Show 関数

Show 関数はメタデータ(measurement、tag、field、基数、系列カウントなど)を確認するために使用し、モデリング調査やクエリ前の確認によく使用します。

共通構文

show_xxx(arg1=..., arg2=...){ where_conditions } [time_window] LIMIT n OFFSET m
  • 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>_source
  • show_<namespace>_class
  • show_<namespace>_type
  • show_<namespace>_field
  • show_<namespace>_label
  • show_<namespace>_index

ここで <namespace> は関数名の中間部分から自動マッピングされます。例:

  • show_logging_source -> L
  • show_tracing_field -> T
  • show_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

フィードバック

このページは役に立ちましたか?