DQL¶
DQL(Debug Query Language)は Guance プラットフォームの中核となるクエリ言語であり、時系列データ、ログデータ、イベントデータなどを効率的にクエリおよび分析するために設計されています。DQL は SQL の意味表現と PromQL の構文構造を組み合わせ、ユーザーに柔軟で強力なクエリツールを提供することを目的としています。
本文書では、DQL の基本構文と設計思想をすばやく理解し、例を通して DQL クエリの記述方法を示します。
基本クエリ構造¶
DQL の基本クエリ構造は次のとおりです:
namespace[index]::datasource[:select-clause] [{where-clause}] [time-expr] [group-by-clause] [having-clause] [order-by-clause] [limit-clause] [sorder-by-clause] [slimit-clause] [soffset-clause]
index は省略可能です。省略した場合はデフォルトで default インデックスが使用されます。
データソースを省略する場合、括弧を直接使用してプロジェクションを指定できます:
例:
括弧がない場合、:: の後の式は引き続きデータソースを表します(注: メトリクスクエリ M はデフォルトの全フィールド * をサポートせず、フィールドを明示的に指定する必要があります。ログ L などの非メトリクス名前空間では、フィールドを省略した場合デフォルトで全フィールド * を返します):
したがって、M::(cpu) はフィールド cpu を選択することを表し、データソース cpu を表すものではありません。
括弧形式のデータソースにフィールドを明示的に指定する必要がある場合は、L::(nginx):(*) または M::(cpu):(usage_total) と記述します。
派生テーブルをデータソースとして使用する場合も、明示的なプロジェクション区切り文字を使用します:
外側の (...) はサブクエリのデータソースで、その直後の :(...) は外側のプロジェクションです。
実行順序¶
DQL クエリの実行順序は非常に重要で、クエリのセマンティクスとパフォーマンスを決定します。
-
データフィルタリング:
namespace::datasource、where-clause、time-exprに基づいてデータをフィルタリング- データソースとインデックスを決定
WHERE条件を適用して元のデータ行をフィルタリング- 時間範囲のフィルタリングを適用
- この段階でできるだけ早くデータをフィルタリングし、後続処理の効率を高める
-
時間前処理(Rollup):
time-exprに Rollup が含まれる場合、まず各元の時系列に対して Rollup を実行- Rollup 関数は時間次元で単一の元タイムラインに対して前処理を行う
- Counter 型メトリクスの場合、通常は元の累積値を直接使用せず、レート(
rate)または増分(increase)を計算する - Gauge 型メトリクスの場合、
last、avgなどの関数を使用できる
-
グループ集計:
group-by-clauseのグループ化を実行し、グループ内でselect-clauseの集計関数を実行BY句の式に従ってデータをグループ化- 各グループ内で集計関数(
sum、count、avg、max、minなど)を計算 - 時間ウィンドウのステップ(例:
[1h::5m])も指定されている場合、「グループ × 時間バケット」の二次元データ構造が形成される
-
グループフィルタリング:
having-clauseを実行して集計後の結果をフィルタリングHAVING句は集計後の結果(または時間バケット)に作用- 集計関数のエイリアスまたは結果を使用してフィルタリングできる
- これが
WHERE句(元の行をフィルタリング)との重要な違い
-
スカラーと後処理計算:
select-clauseのスカラー変換関数または集計算術式を実行- 集計結果に対してさらに計算(例:
round(avg(usage_total), 2)、(avg(used) / avg(total)) * 100)
- 集計結果に対してさらに計算(例:
-
グループ間ソートとページング:
sorder-by-clause、slimit-clause、soffset-clauseを実行してグループ(Series)をソートおよびページングSORDER BYはグループ自体をソート(単一ウィンドウでは区間全体の集計値、ステップ付きの複数時点では最新時間バケットの値)SLIMIT/SOFFSETは返すグループ数とグループオフセットを制限
-
グループ内ソートとページング:
order-by-clause、limit-clause、offset-clauseを実行して各グループ内部のデータ行をソートおよびページングORDER BYは選択された各グループの内部で独立して実行LIMIT/OFFSETは各グループが返すデータ行数と行オフセットを制限
完全な例¶
DataKit のデフォルト収集による cpu メジャーメントを使用して、完全な例で DQL の構造を理解しましょう:
M::cpu:(avg(usage_total) AS avg_usage, max(usage_total) AS max_usage) {host =~ '.*', usage_total > 10} [1h::5m] BY host HAVING avg_usage > 20 ORDER BY time DESC LIMIT 12 SORDER BY avg_usage DESC SLIMIT 10
このクエリの意味は次のとおりです:
- データ前提:ホスト CPU コレクターが有効(メジャーメント
cpu、フィールドusage_totalとタグhostを含む) - 名前空間:
M(メトリクスデータ) - インデックス:省略時はデフォルトで
defaultインデックスを使用 - データソース:
cpu - 選択フィールド:
usage_totalフィールドの平均値(エイリアスavg_usage)と最大値(エイリアスmax_usage) - フィルター条件:ホスト名に一致し、元のサンプルの CPU 総使用率が 10% より大きい
- 時間範囲:過去 1 時間、5 分ステップで集計
- グループ化:ホスト名
hostでグループ化 - グループフィルタリング:ウィンドウ内の平均 CPU 使用率が 20% より大きい時間バケットを抽出
- グループ内ソートとページング:各ホストグループ内で時間降順に並べ、各グループ最大 12 個の時点を返す
- グループ間ソートとページング:最新時間バケットの
avg_usageで降順に並べ、上位 10 台のホストを返す
名前空間(namespace)¶
名前空間は異なるタイプのデータを区別するために使用され、各データタイプには特定のクエリ方法と保存ポリシーがあります。DQL はさまざまなビジネスデータタイプのクエリをサポートしています:
| 名前空間 | 説明 | 典型的な用途 |
|---|---|---|
| M | Metric、時系列メトリクスデータ | CPU 使用率、メモリ使用量、リクエスト数など |
| L | Logging、ログデータ | アプリケーションログ、システムログ、エラーログなど |
| O | Object、インフラストラクチャオブジェクトデータ | サーバー情報、コンテナ情報、ネットワークデバイスなど |
| OH | History object、オブジェクト履歴データ | サーバー設定変更履歴、パフォーマンスメトリクス履歴など |
| CO | Custom object、カスタムオブジェクトデータ | ビジネスでカスタマイズしたオブジェクト情報 |
| COH | History custom object、カスタムオブジェクト履歴データ | カスタムオブジェクトの履歴変更レコード |
| N | Network、ネットワークデータ | ネットワークトラフィック、DNS クエリ、HTTP リクエストなど |
| T | Trace、トレース呼び出しデータ | 分散型トレーシング、呼び出しチェーン分析など |
| P | Profile、プロファイリングデータ | パフォーマンスプロファイリング、CPU フレームグラフなど |
| R | RUM、ユーザーアクセスデータ | フロントエンドパフォーマンス、ユーザー行動分析など |
| E | Event、イベントデータ | アラートイベント、デプロイイベント、システムイベントなど |
| UE | Unrecovered Event、未復旧イベントデータ | 未解決のアラートとイベント |
| B | Cloud billing、クラウド請求 | クラウドサービス料金と請求分析 |
プラットフォームのデフォルトデータソースと汎用フィールド早見表¶
ワークスペースで DataKit のデフォルト収集を有効にすると、以下の組み込みデータソースと汎用フィールドは追加設定なしで直接クエリにコピーして実行できます:
| 名前空間 | 一般的なデフォルトデータソース(source / measurement) |
よく使う標準フィールド / タグ |
|---|---|---|
M(メトリクス) |
cpu、mem、disk、diskio、net、system |
cpu: usage_total、usage_user、usage_system、usage_idle、usage_iowaitmem: used_percent、available_percent、used、total、availabledisk: used_percent、free、used、total、inodes_used_percent(タグ: device、fstype)net: bytes_recv、bytes_sent、packets_recv、packets_sent、err_in、err_out(タグ: interface)system: load1、load5、load15、load1_per_core、n_cpus、uptime汎用タグ: host |
L(ログ) |
*(すべてのログ)、nginx、system など |
message(ログ本文)、status(ログレベル: error/warn/info など)、service、source、host、pod_name、container_name、filepath |
O(オブジェクト) |
HOST、docker_containers、kubelet_pod、host_processes |
HOST: host、name、state、os、arch、cpu_usage、mem_used_percent、disk_used_percent、load、cloud_provider、last_update_time |
T(トレース) |
*(すべてのサービス)または具体的な service 名 |
service、resource、operation、duration(所要時間、通常はナノ秒またはマイクロ秒)、status(ok/error)、span_type(entry/local/exit)、trace_id、span_id、parent_id、http_status_code、http_method、env |
R(RUM) |
view、resource、error、action、long_task、session |
app_id、env、version、view_path、loading_time、lcp、fcp、fid、cls、error_message、error_type、browser、os、country、city、userid |
E / UE(イベント) |
monitor、system、custom_event |
df_title、df_message、df_status(critical/error/warning/info/ok)、df_event_id、df_monitor_checker_name、df_dimension_tags |
ワークスペースにどのデータソースやフィールドがあるかわからない場合 は、以下のメタデータ調査ステートメントを直接コピーして実行できます(詳細は Show 関数リファレンス を参照): - すべてのメジャーメントを表示:
show_measurement()-cpuメジャーメントのすべてのフィールドを表示:show_field_key(from=['cpu'])- ログデータソースの一覧とフィールドを表示:show_source(namespace='L')、show_field(namespace='L')- インフラストラクチャオブジェクトの分類を表示:show_source(namespace='O')
インデックス(index)¶
インデックスは DQL クエリ最適化の重要なメカニズムであり、従来のデータベースにおけるテーブルまたはパーティションと理解できます。単一の名前空間下で、システムはデータソース、データ量、アクセスパターンなどの要因によってデータを分割し、クエリパフォーマンスと管理効率を向上させる場合があります。
インデックスの役割¶
- パフォーマンス最適化: インデックスによってデータを分散保存し、1 回のクエリでスキャンするデータ量を削減
- データ分離: 異なるビジネス、環境、時間範囲のデータを異なるインデックスに保存可能
- 権限管理: インデックスごとに異なるアクセス権限を設定可能
- ライフサイクル管理: インデックスごとに異なるデータ保持ポリシーを設定可能
インデックスの命名規則¶
- インデックス名は明示的に宣言できます。明示しない場合はデフォルトで
defaultを使用 - インデックス名を明示する場合、ワイルドカードや正規表現によるマッチングはサポートされません(ログなどでは
L("*")を使用してすべてのインデックスをクエリ可能) - インデックス名は通常、データのビジネス属性を表します。例:
default、production、staging、web-logs
基本構文¶
// デフォルトインデックスを使用(指定しない場合は自動的に default を使用)
M::cpu:(avg(usage_total)) [1h] // M("default")::cpu:(avg(usage_total)) [1h] と等価
L::*:(count(*)) [1h] // L("default")::*:(count(*)) [1h] と等価
// 単一インデックスを指定
M("default")::cpu:(avg(usage_total)) [1h] // default インデックス内の CPU メトリクスをクエリ
L("default")::*:(count(*)) [1h] // default インデックス内のログをクエリ
// 複数インデックスクエリ(複数のインデックスのデータを同時にクエリ)
L("default", "web-logs")::*:(count(*)) [1h] // 複数のログインデックスを同時にクエリ
インデックスとパフォーマンス¶
インデックスを適切に使用すると、クエリパフォーマンスを大幅に向上できます:
- 正確なインデックス: データがどのインデックスにあるか明確な場合は、そのインデックスを直接指定
- 複数インデックスクエリ: 複数のインデックスをまたいでクエリする必要がある場合は、全量スキャンではなく複数インデックス構文を使用
- 全インデックススキャンを避ける: インデックスと WHERE 条件の組み合わせによってデータスキャン範囲をできるだけ削減
互換構文(非推奨)¶
歴史的な理由により、DQL は where 句でインデックスを指定する構文もサポートしていますが、推奨されません:
// 旧構文、非推奨
L::*:(count(*)) { index = "default" } [1h]
L::*:(count(*)) { index IN ["default", "web-logs"] } [1h]
使用例¶
// デフォルトインデックス下の各ホストの平均 CPU 使用率をクエリ
M::cpu:(avg(usage_total)) [1h] BY host
// デフォルトインデックス下のログステータス別ログ件数をクエリ
L("default")::*:(count(*)) [1h] BY status
// 複数インデックスのエラーログ数を比較
L("default", "web-logs")::*:(count(*)) {status = 'error'} [1h] BY index
データソース(datasource)¶
データソースはクエリの具体的なデータソースを指定し、データセット名、ワイルドカードパターン、正規表現、またはサブクエリを使用できます。
基本データソース¶
名前空間ごとにデータソースの定義が異なります:
| 名前空間 | データソースタイプ | 例 |
|---|---|---|
| M | メジャーメント(measurement) | cpu, mem, disk, net, system |
| L | データソース(source) | *, nginx, system, redis |
| O | インフラストラクチャオブジェクト分類 | HOST, docker_containers, kubelet_pod |
| T | サービス名(service) | *, `user-service`, `order-service` |
| R | RUM データタイプ | session, view, resource, error, action, long_task |
データソース構文¶
注意: データソース名にハイフン
-またはその他の特殊文字(例:user-service)が含まれる場合は、バッククォートで囲む必要があります(例:T::`user-service`:(count(*)))。そうしない場合、-は減算演算子として解析されます。
データソース名を指定¶
M::cpu:(avg(usage_total)) [1h] // cpu メジャーメントをクエリ
L::nginx:(count(*)) [1h] // nginx ログデータソースをクエリ
O::HOST:(host, cpu_usage, mem_used_percent) // HOST ホストオブジェクトをクエリ
T::`user-service`:(count(*)) [1h] // ハイフンを含むサービス名をクエリ(バッククォートで囲む)
R::view:(count(*)) [1h] // RUM ページビュー(view)データをクエリ
ワイルドカードマッチング¶
L::*:(count(*)) [1h] BY source // すべてのログデータソースをクエリし source 別に集計
T::*:(count(*)) [1h] BY service // すべての APM サービスをクエリし service 別に集計
正規表現マッチング¶
M::re('cpu|mem'):(avg(usage_total), avg(used_percent)) [1h] // 正規表現にマッチするメジャーメントをクエリ
L::re('nginx.*'):(count(*)) [1h] // nginx で始まるログソースをクエリ
T::re('.*-service'):(count(*)) [1h] BY service // -service で終わるサービスをクエリ
サブクエリデータソース¶
サブクエリは DQL で複雑な分析を実現する重要な機能であり、あるクエリの結果を別のクエリのデータソースとして使用できます。このネストされたクエリメカニズムは多層的な分析要件をサポートします。
実行メカニズム¶
サブクエリの実行は以下の原則に従います:
- 直列実行:内側のサブクエリが先に実行され、完了後にその結果が外側のクエリのデータソースとして使用される
- 結果のカプセル化:サブクエリ結果は一時テーブル構造にカプセル化され、外側のクエリで使用される
- 名前空間の混在:サブクエリは異なる名前空間の混合クエリをサポートし、データタイプをまたぐ分析を実現する
- パフォーマンスの考慮:サブクエリは計算の複雑さを増加させるため、クエリロジックを適切に設計する必要がある
基本構文¶
実行プロセス¶
典型的なサブクエリの例(過去 1 時間にエラーログを生成した独立サービスの数を集計):
L::(L::*:(count(*) AS err_cnt) {status = 'error'} [1h] BY service):(count(service) AS affected_services) [1h]
実行プロセスは次のとおりです:
-
内側のサブクエリ:
L::*:(count(*) AS err_cnt) {status = 'error'} [1h] BY service- 過去 1 時間のログデータをスキャン
status = 'error'のエラーログを抽出serviceごとにエラー数を集計- 一時テーブルを生成:
service | err_cnt
-
外側のクエリ:
L::(...):(count(service) AS affected_services) [1h]- サブクエリ結果をデータソースとして使用
- 異なる
serviceグループの数を集計 - 最終結果: エラーログが発生したサービスの総数
使用例¶
// 過去 1 時間にエラーログがあるサービスの数を集計
L::(L::*:(count(*) AS err_cnt) {status = 'error'} [1h] BY service):(count(service) AS affected_services) [1h]
// 平均 CPU 使用率が 80% を超える高負荷ホストの数を集計(注意: 集計結果のフィルタリングには HAVING を使用)
M::(M::cpu:(avg(usage_total) AS avg_cpu) [1h] BY host HAVING avg_cpu > 80):(count(host) AS high_load_hosts) [1h]
// まずホストごとに 5 分粒度のピーク CPU を計算し、その後すべてのホストのピークの平均水準を求める
M::(M::cpu:(max(usage_total) AS peak_cpu) [1h::5m] BY host):(avg(peak_cpu) AS cluster_avg_peak) [1h::5m]
Select 句(select-clause)¶
Select 句はクエリが返すフィールドまたは式を指定するために使用され、DQL クエリの中で最も基本かつ重要な部分の 1 つです。
フィールド選択¶
基本構文¶
// 単一のメトリクスフィールドを選択(集計または明細時間ウィンドウと組み合わせる)
M::cpu:(usage_total) [1h]
// 複数のメトリクスフィールドを選択
M::cpu:(usage_total, usage_system, usage_user) [1h]
// 非メトリクス名前空間のすべてのフィールドを選択(注: M メトリクス名前空間は * ワイルドカードフィールドをサポートせず、フィールド名を明示的に列挙する必要があります)
L::*:(*) [15m] LIMIT 10
O::HOST:(*) LIMIT 10
フィールド名の規則¶
フィールド名には以下の記述形式があります:
-
名前を直接記述:英字、数字、アンダースコア
_、ドット.、または@のみを含む通常の識別子に適用- ✅
message - ✅
usage_total - ✅
df_status
- ✅
-
バッククォート(
`)で囲む:ハイフン-、スラッシュ/、空白を含む場合、またはキーワードと同じ名前のフィールド名に適用- ✅
`bytes_recv/sec` - ✅
`limit` - ✅
`host-name` - ✅
`column with spaces`
- ✅
-
避けるべき記述:シングルクォートとダブルクォートで囲まれたものは文字列リテラルであり、フィールド名ではありません
- ❌
'message' - ❌
"message"
- ❌
JSON フィールド抽出¶
データフィールドに JSON 形式の内容が含まれる場合、JSON Path 構文のサブセットを使用して内部フィールドのデータを抽出できます。
基本構文¶
JSON Path 構文¶
- ドットでオブジェクトプロパティを取得:
.field_name - 角括弧でオブジェクトプロパティを取得:
["key"](空白や特殊文字を含むキーに適用) - 配列インデックスで値を取得:
[index]
使用例¶
以下の JSON ログデータがあるとします:
{
"message": "User login attempt",
"request": {
"method": "POST",
"path": "/api/login",
"headers": {
"user-agent": "Mozilla/5.0",
"content-type": "application/json"
},
"body": {
"username": "john.doe",
"password": "***",
"permissions": ["read", "write", "admin"]
}
},
"response": {
"status": 200,
"time": 156,
"data": [
{"id": 1, "name": "user1"},
{"id": 2, "name": "user2"}
]
}
}
// リクエストメソッドを抽出
L::auth_logs:(message@request.method)
// リクエストパスを抽出
L::auth_logs:(message@request.path)
// ユーザー名を抽出
L::auth_logs:(message@request.body.username)
// レスポンスステータスを抽出
L::auth_logs:(message@response.status)
// User-Agent を抽出(ハイフンを含むため、角括弧を使用する必要があります)
L::auth_logs:(message@request.headers["user-agent"])
// 権限配列の最初の要素を抽出
L::auth_logs:(message@request.body.permissions[0])
// レスポンスデータの最初のオブジェクトの name を抽出
L::auth_logs:(message@response.data[0].name)
// 異なるリクエストメソッドの数を集計
L::auth_logs:(count(*)) [1h] BY message@request.method
// レスポンス時間の分布を分析
L::auth_logs:(avg(message@response.time), max(message@response.time)) [1h] BY message@request.method
// 複数のフィールドを抽出
L::auth_logs:(
message,
message@request.method as method,
message@request.path as path,
message@response.status as status,
message@response.time as response_time
) {message@response.status >= 400} [1h]
計算フィールド¶
式計算¶
基本的な算術演算をサポートします。注意: BY グループ化または時間ウィンドウのステップを含む集計クエリでは、算術演算のオペランドは明示的に集計関数で囲む必要があります(例: (avg(used) / avg(total)) * 100)。非集計の明細クエリでのみ、元のフィールドに直接算術演算を実行できます。
// 明細クエリ: 単位変換(ナノ秒からミリ秒)
T::*:(service, resource, duration / 1000000 AS duration_ms) [15m] LIMIT 10
// 集計クエリ: メモリ使用率を計算(オペランドは集計関数で囲む必要があります)
M::mem:((avg(used) / avg(total)) * 100 AS usage_percentage) [1h] BY host
// 集計クエリ: ネットワークインターフェースの総スループットを計算(バイトから MB)
M::net:((max(bytes_recv) + max(bytes_sent)) / 1024 / 1024 AS total_traffic_mb) [1h] BY host
関数計算¶
さまざまな集計関数と変換関数をサポートします:
// 集計関数: CPU 使用率の最大値、最小値、平均値を同時に確認
M::cpu:(max(usage_total), min(usage_total), avg(usage_total)) [1h] BY host
// 変換関数: メトリクス平均値を四捨五入
M::cpu:(round(avg(usage_total), 2) AS avg_cpu_pct) [1h] BY host
条件式¶
CASE WHEN はクエリ内で条件に応じて異なる値を選択するために使用します。通常、集計関数と一緒に使用され、条件付きカウント、条件付き合計、または条件に応じたフィールドの正規化を行います。
基本構文¶
同じフィールドに対して複数値のマッチングを行う単純 CASE 構文も使用できます:
WHEN は記述順にマッチし、最初に一致した条件の THEN 値を返します。いずれにも一致しない場合は ELSE 値を返します。ELSE を明示的に記述しない場合、デフォルトで nil を返します。
使用例¶
条件付きカウント: エラーログ数と総ログ数を集計
L::*:(
count(*) AS total_logs,
count(CASE WHEN status = 'error' THEN 1 ELSE nil END) AS error_logs
) [1h] BY service
注意:
count(expr)は非nil値をカウントします。0も非nilであるため、count(CASE WHEN condition THEN 1 ELSE 0 END)は条件に一致した行だけではなくすべての行をカウントします。条件付きカウントを行う場合はELSE nilの使用を推奨します。またはsum(CASE WHEN condition THEN 1 ELSE 0 END)を使用してください。
条件付き合計: 遅いリクエスト(所要時間 > 1 秒)の総所要時間のみを集計
T::*:(
sum(CASE WHEN duration > 1000000000 THEN duration ELSE 0 END) AS slow_duration_ns
) [1h] BY service
複数分岐分類: ログレベルに応じて重大度分類を生成
L::*:(
max(CASE
WHEN status = 'critical' THEN 3
WHEN status = 'error' THEN 2
WHEN status = 'warn' THEN 1
ELSE 0
END) AS max_severity
) [1h] BY service
フィールドクリーニング後に判定: 大文字小文字を無視してエラーログを集計
型変換後に集計: フィールドが文字列の場合に数値へ変換して合計に参加
L::nginx:(
sum(CASE WHEN status = 'error' THEN int(message_length) ELSE 0 END) AS error_msg_bytes
) [1h] BY host
サポート範囲¶
CASE WHEN は現在、制限付きの行レベル条件式であり、高性能なプッシュダウン実行をサポートすることを設計目標としています。sum(CASE ...)、count(CASE ...)、max(CASE ...) など、集計関数の内部に配置できます。
CASE 内部でサポート:
- フィールド
- リテラルと
nil - ブール条件(
=、!=、>、>=、<、<=、AND、OR。INはサポートされません。複数値マッチングにはORまたは単純なCASE field WHEN ...構文を使用してください) - 以下のスカラー関数:
bool、int、uint、float、string、md5、lower、upper、trim、ltrim、rtrim、length、regexp_replace
CASE 内で集計関数を使用することはサポートされていません。集計関数は CASE の外側に置く必要があります:
// 推奨: まず行ごとに CASE を計算し、その後集計
L::*:(
sum(CASE WHEN status = 'error' THEN 1 ELSE 0 END) AS error_count
) [1h] BY host
// 非サポート(エラーになる): CASE 内部に集計関数を直接含めることはできません
L::*:(
CASE WHEN count(*) > 0 THEN "has_logs" ELSE "empty" END
) [1h] BY host
また、CASE 内でサポート範囲に含まれない複雑なスカラー関数(例: regexp_extract)を使用することもサポートされていません。その他の複雑な処理が必要な場合は、クエリ条件、フィールドクリーニング、またはサブクエリでロジックを分割し、CASE 内で大範囲の明細スキャンを引き起こさないようにすることを推奨します。
エイリアス¶
フィールドまたは式にエイリアスを指定すると、結果が読みやすくなり、後続で参照しやすくなります。
基本構文¶
使用例¶
// 単純なエイリアス
M::cpu:(avg(usage_total) AS avg_usage, max(usage_total) AS max_usage) [1h] BY host
// 集計算術式のエイリアス
M::mem:((avg(used) / avg(total)) * 100 AS usage_percent) [1h] BY host
// 関数のエイリアス
L::*:(count(*) AS error_count) {status = 'error'} [1h] BY service
// JSON 抽出のエイリアス
L::*:(
message@request.method AS http_method,
message@response.status AS http_status,
message@response.time AS response_time_ms
) [15m] LIMIT 20
使用のヒント¶
DQL では、単一の集計関数の結果は元のフィールド名で直接参照できるため、エイリアスの使用を減らせます:
M::cpu:(max(usage_total)) [1h] BY host
// サブクエリ結果には max(usage_total) 列が含まれ、外側では usage_total で直接その列を参照できます:
M::(M::cpu:(max(usage_total)) [1h] BY host):(max(usage_total)) { usage_total > 80 } [1h]
ただし、複数の集計関数が同じフィールドを使用する場合は、後続で正しく区別するためにエイリアスを使用する必要があります:
時間句(time-clause)¶
時間句は DQL の中核機能の 1 つであり、クエリの時間区間、集計時間ウィンドウ、Rollup 集計関数を指定するために使用します。
使用習慣のヒント: コンソールの「クイッククエリ」、ダッシュボードのグラフ、またはクエリ API を呼び出す場合、クエリの開始時刻と終了時刻(
start_time/end_time)は通常、画面右上の時間セレクターまたは API リクエストパラメータによって一律に渡されます。この場合、DQL では集計ステップまたは Rollup(例:[::5m]、[::1m:rate])のみを指定すればよく、[1h]をハードコードする必要はありません。これにより、同じ DQL がページの時間セレクターに応じて時間範囲を動的に切り替えられます。固定のクエリウィンドウが必要な場合、または異なるウィンドウを比較する場合にのみ、DQL で開始時刻と終了時刻を明示的に記述します(例:[1h::5m])。
基本構文¶
時間範囲¶
絶対タイムスタンプ¶
相対時間¶
さまざまな期間単位をサポートし、混合使用できます:
[1h] // 過去 1 時間から現在まで
[1h:5m] // 過去 1 時間から過去 5 分まで
[1h30m] // 過去 1 時間 30 分
[2h15m30s] // 過去 2 時間 15 分 30 秒
期間式の説明¶
| 単位 | 説明 | 例 |
|---|---|---|
| s | 秒 | 30s |
| m | 分 | 5m |
| h | 時間 | 2h |
| d | 日 | 7d |
| w | 週 | 4w |
| y | 年 | 1y |
期間式が時間句で使用される場合、現在時刻からの過去方向へのオフセットを表します。Select 句や Where 句などで使用される場合、ミリ秒整数として計算に参加します。
集計クエリで使用される場合、さらに 2 種類の期間単位をサポートします:
| 単位 | 説明 | 例 |
|---|---|---|
| i、is | 集計時間ウィンドウの倍数、戻り値は浮動小数点の秒 | 1i、1is |
| ims | 集計時間ウィンドウの倍数、戻り値は整数のミリ秒 | 1ims |
O::HOST:(count(*)) { `last_update_time` > (now() - 10m) } // 10m は 600,000 ミリ秒の整数として計算に参加
L::*:(count(*) / 1i AS log_qps) [1h::1m] // 時間ウィンドウのステップ(1m = 60s)で除算し、ログ書き込み QPS を計算
プリセット時間範囲¶
よく使う時間範囲キーワードを提供します:
| キーワード | 説明 | 時間範囲 |
|---|---|---|
| TODAY | 今日 | 今日 0 時から現在まで |
| YESTERDAY | 昨日 | 昨日 0 時から今日 0 時まで |
| THIS WEEK | 今週 | 今週月曜 0 時から現在まで |
| LAST WEEK | 先週 | 先週月曜 0 時から今週月曜 0 時まで |
| THIS MONTH | 今月 | 今月 1 日 0 時から現在まで |
| LAST MONTH | 先月 | 先月 1 日 0 時から今月 1 日 0 時まで |
[TODAY] // 今日のデータ
[YESTERDAY] // 昨日のデータ
[THIS WEEK] // 今週のデータ
[LAST WEEK] // 先週のデータ
[THIS MONTH] // 今月のデータ
[LAST MONTH] // 先月のデータ
時間範囲キーワードを使用する場合は、ワークスペースのタイムゾーン設定が正しいことを確認してください。ユーザーリクエストのタイムゾーンに厳密に従って変換する必要があります。
時間ウィンドウ集計¶
時間ウィンドウはデータを指定した時間間隔でグループ集計し、返却結果の time 列は各時間ウィンドウの開始時刻を表します。
単一時間ウィンドウ¶
時間範囲全体を 1 つの値に集計:
クエリ結果:
時間ウィンドウ集計¶
時間間隔ごとにグループ集計:
クエリ結果:
{
"columns": ["time", "max(usage_total)"],
"values": [
[1721059200000, 37.46],
[1721058600000, 34.12],
[1721058000000, 33.81],
[1721057400000, 30.92],
[1721056800000, 34.53],
[1721056200000, 36.11]
]
}
Rollup 関数¶
Rollup 関数は DQL の重要な前処理ステップであり、グループ集計の前に実行され、元の時系列データを前処理します。
実行タイミング¶
Rollup のクエリ実行フローにおける位置:
実行メカニズム¶
Rollup の実行プロセスは 2 つの段階に分かれます:
- タイムラインごとの処理:各独立した時系列に個別に Rollup 関数を適用
- 集計計算:Rollup 処理後の結果に対してグループ集計を実行
Rollup 省略記法、Rollup 関数呼び出し、明示的集計呼び出し¶
DQL には混同しやすい時系列関数の記法が 3 つあります:
- Rollup 省略記法:時間句に関数名のみを記述。例:
[rate]、[1h::5m:slope]。 - Rollup 関数呼び出し:時間句で Rollup 関数にアルゴリズムパラメータを渡す。例:
[1h::1m:ewma(0.3)]、[1h::1m:moving_average(5)]、[1h::1m:percentile(95)]。 - 明示的集計呼び出し:Select 句に完全な関数呼び出しを記述。例:
rate(bytes_recv)、ewma(usage_total, 0.3)、corr(usage_user, usage_system)。
3 つの記法の主な違いは実行フェーズとパラメータ能力です:
| 記法 | 例 | 実行フェーズ | ユースケース |
|---|---|---|---|
| Rollup 省略記法 | [1h::5m:rate] |
グループ集計の前、元のタイムラインごとに実行 | 各タイムラインを前処理してからグループ集計 |
| Rollup 関数呼び出し | [1h::1m:ewma(0.3)] |
グループ集計の前、元のタイムラインごとに実行 | Rollup 関数に追加のアルゴリズムパラメータが必要 |
| 明示的集計呼び出し | ewma(usage_total, 0.3) |
Select 句の集計フェーズ | フィールド、追加パラメータ、または複数の入力フィールドを指定する必要がある |
時間句の Rollup 入力フィールドは、Select フィールド、時間ウィンドウ、元のタイムラインによって共同で決定されます。そのため、Rollup 関数呼び出しでは追加のアルゴリズムパラメータのみを渡し、時間句にフィールド名を渡しません。単一入力で追加パラメータのない時系列関数は通常 Rollup 省略記法をサポートできます。追加のアルゴリズムパラメータが必要な単一入力関数は Rollup 関数呼び出しをサポートできます。複数の入力フィールドが必要な関数は明示的集計呼び出しを使用する必要があります。
例: Counter メトリクスを先に Rollup してから集計
Counter メトリクス(例: 累積ネットワーク受信バイト bytes_recv)は、まず各元のタイムラインで毎秒の増加率を計算し、その後ホスト次元で合計する必要があります:
// 推奨: まず各ネットワークインターフェースのタイムラインで rate(毎秒レート)を計算し、その後 host ごとに合計してマシン全体の総スループットレートを得る
M::net:(sum(bytes_recv)) [1h::5m:rate] BY host
// 非推奨: Counter の元の累積値を直接集計すると、現在のスループットレートではなく過去の累積総量が得られる
M::net:(sum(bytes_recv)) [1h::5m] BY host
例: 追加のアルゴリズムパラメータが必要な場合に Rollup 関数呼び出しを使用
ewma は平滑化係数 alpha を明示的に渡す必要があります。各元のタイムラインで先に EWMA を実行し、その後グループ集計に進みたい場合は、時間句に記述できます:
// Rollup 関数呼び出し: まず各タイムラインで EWMA を実行し、その後 host ごとに平均を計算
M::cpu:(avg(usage_total)) [1h::1m:ewma(0.3)] BY host
以下の 2 つはよくある誤った記法です:
// エラー: ewma には alpha が必要で、関数名だけを記述できません
M::cpu:(avg(usage_total)) [1h::1m:ewma] BY host
// エラー: 時間句の Rollup パラメータにはアルゴリズムパラメータのみを記述し、フィールド名は記述しません
M::cpu:(avg(usage_total)) [1h::1m:ewma(usage_total, 0.3)] BY host
Select 集計フェーズで EWMA を計算したい場合は、明示的集計呼び出しも使用できます:
// 明示的集計呼び出し: Select 集計フェーズで usage_total に対して EWMA を計算
M::cpu:(ewma(usage_total, 0.3)) [1h::1m] BY host
時間句 Rollup に適した単一数値パラメータ化関数には以下も含まれます:
// まず各タイムラインで 5 点移動平均を計算し、その後 host ごとに平均を計算
M::cpu:(avg(usage_total)) [1h::1m:moving_average(5)] BY host
// まず各タイムラインで P95 を取得し、その後 host ごとに平均を計算
M::cpu:(avg(usage_total)) [1h::5m:percentile(95)] BY host
例: 複数の入力フィールドがある場合に明示的集計呼び出しを使用
corr は 2 つの入力フィールドが必要なため、時間句 Rollup に記述できません:
// 正しい: Select 句で 2 つのフィールドを明示的に指定(ユーザー態とカーネル態 CPU の相関係数を計算)
M::cpu:(corr(usage_user, usage_system)) [1h::5m] BY host
例: 同名関数の実行フェーズが異なる
ある関数が Rollup 省略記法と明示的集計呼び出しの両方をサポートする場合、2 つの記法は異なる実行フェーズを表し、完全に等価であるとデフォルトで解釈すべきではありません:
// Rollup 省略記法: まず各元のタイムラインで zscore を計算し、その後グループ集計に進む
M::cpu:(max(usage_total)) [1h::5m:zscore] BY host
// 明示的集計呼び出し: Select 集計フェーズで usage_total に対して zscore を計算
M::cpu:(zscore(usage_total)) [1h::5m] BY host
ユースケース¶
Rollup 関数の典型的なユースケースは Counter メトリクス処理です。
Prometheus またはシステム収集による Counter 型メトリクス(例: net の bytes_recv、HTTP リクエスト累積カウント request_count)では、Counter は単調増加するため、元の値を直接集計することに意味はありません。まずタイムラインごとに増加率を計算し、その後集計する必要があります。
問題例: 2 台のサーバーのリクエストカウンターがあるとします:
{
"host": "web-server-01",
"data": [
{"time": "2024-07-15 08:25:00", "request_count": 150},
{"time": "2024-07-15 08:20:00", "request_count": 140},
{"time": "2024-07-15 08:15:00", "request_count": 130},
{"time": "2024-07-15 08:10:00", "request_count": 120},
{"time": "2024-07-15 08:05:00", "request_count": 110},
{"time": "2024-07-15 08:00:00", "request_count": 100}
]
}
{
"host": "web-server-02",
"data": [
{"time": "2024-07-15 08:25:00", "request_count": 250},
{"time": "2024-07-15 08:20:00", "request_count": 240},
{"time": "2024-07-15 08:15:00", "request_count": 230},
{"time": "2024-07-15 08:10:00", "request_count": 220},
{"time": "2024-07-15 08:05:00", "request_count": 210},
{"time": "2024-07-15 08:00:00", "request_count": 200}
]
}
直接集計の問題:
- web-server-01 の request_count の開始値は 100
- web-server-02 の request_count の開始値は 200
- 2 台のサーバーのリクエストレートは同じ(どちらも 5 分あたり 10 リクエスト)だが、絶対値が異なる
Rollup を使用した解決策:
実行プロセス:
-
Rollup フェーズ(各タイムラインで個別に実行):
- web-server-01: rate([100, 110, 120, 130, 140, 150])
- web-server-02: rate([200, 210, 220, 230, 240, 250])
-
集計フェーズ:
- 各タイムラインのレートを合計し、クラスタ全体の総リクエストレートを得る
関数タイプ¶
一般的な Rollup 関数には以下が含まれます:
| 関数タイプ | 説明 | ユースケース |
|---|---|---|
rate |
増加率を計算 | Counter 型メトリクス |
increase |
増分量を計算 | Counter 型メトリクス |
last |
最後の値を取得 | Gauge 型メトリクス |
avg |
平均値を計算 | データの平滑化 |
max |
最大値を取得 | ピーク分析 |
min |
最小値を取得 | ボトム分析 |
ただし、単一値を返すほぼすべての集計関数を使用できるため、ここではすべての関数リストを列挙しません。
デフォルト Rollup¶
Rollup 関数を明示的に指定しない場合、DQL はデフォルトで Rollup 計算を行いません。PromQL のデフォルト Rollup は last であるため、Prometheus メトリクスを計算している場合はこの違いを必ず理解し、Rollup 関数を手動で指定してください。
使用例¶
// すべてのホストの総ネットワーク受信レート(バイト/秒)を計算
M::net:(sum(bytes_recv)) [1h::5m:rate]
// ホストごとにネットワーク受信と送信のレートを集計
M::net:(
sum(bytes_recv) AS recv_bps,
sum(bytes_sent) AS sent_bps
) [1h::5m:rate] BY host
時間ウィンドウの柔軟な構文¶
DQL はさまざまな時間ウィンドウの省略形式をサポートし、クエリの記述をより便利にします。
省略形式¶
[1h] // 時間範囲のみ指定
[1h::5m] // 時間範囲 + 集計ステップ
[1h:5m] // 開始時間 + 終了時間
[1h:5m:1m] // 開始 + 終了 + ステップ
[1h:5m:1m:avg] // 完全形式
[::5m] // 集計ステップのみ指定(時間範囲は外部リクエストから提供)
[:::sum] // rollup 関数のみ指定
[sum] // rollup 関数のみ指定(最も簡潔な形式)
時間シフト(SHIFT){#shift}¶
クエリレベルの SHIFT は、クエリ全体の時間ウィンドウを duration だけ全体的に過去へシフトし、その期間前のデータを読み取ります。結果の時間列は引き続き現在のウィンドウとして表示されます:
SHIFT は 2 か所に記述でき、効果は同じです:
- 時間ウィンドウの直後、その他の句の前:
BY、HAVING、ORDER BYなどの句の末尾:
ルール:
durationは正の固定期間である必要があります。例:1h、7d。- 各
SELECTではクエリレベルのSHIFTを 1 つだけ宣言できます。 - 句末尾の
SHIFTは句のトップレベル(括弧内ではない)でのみ有効です:BY (service SHIFT 1d)のSHIFTは引き続き式レベルです。 - フィルタリング、グループ化、集計、ソート、ページングはすべてシフト前のデータに基づいて実行されます。結果の構造は
SHIFTを付けないクエリと同じで、時間列のみが引き続き現在のウィンドウに留まります。
ネストされた SELECT はそれぞれクエリレベルの SHIFT を宣言でき、オフセットは階層ごとに加算されます。クエリレベルの SHIFT と式レベルの SHIFT(DQL 関数リファレンスの SHIFT を参照)は組み合わせ可能です: クエリレベルオフセットがまずクエリ全体の基準ウィンドウを決定し、式レベルオフセットがその基準ウィンドウに対してさらに過去の集計値を読み取ります。
フィルター条件(where-clause)¶
フィルター条件はデータ行をフィルタリングし、条件を満たすデータのみを後続処理のために保持します。
基本構文¶
複数の条件はカンマ ,、AND、OR、&&、|| で接続できます(カンマは AND と等価)。
比較演算子¶
| 演算子 | 説明 | 例 |
|---|---|---|
= |
等しい | host = 'web-01' |
!= |
等しくない | status != 'info' |
> |
より大きい | usage_total > 80 |
>= |
以上 | used_percent >= 90 |
< |
より小さい | duration < 1000000 |
<= |
以下 | used_percent <= 80 |
パターンマッチ演算子¶
| 演算子 | 説明 | 例 |
|---|---|---|
=~ |
正規表現マッチ | message =~ 'error.*\\d+' |
!~ |
正規表現非マッチ | message !~ 'debug.*' |
集合演算子¶
| 演算子 | 説明 | 例 |
|---|---|---|
IN |
集合内 | status IN ['error', 'critical'] |
NOT IN |
集合外 | status NOT IN ['debug', 'info'] |
論理演算子¶
| 演算子 | 説明 | 例 |
|---|---|---|
AND または && |
論理積 | usage_total > 80 AND usage_system > 30 |
OR または \|\| |
論理和 | status = 'error' OR status = 'critical' |
NOT |
論理否定 | NOT status = 'info' |
ヒント:
OR演算子は論理和を実行するほか、NULL フォールバックセマンティクスも提供します。左側の式がNULLを返す場合、右側の式の結果を直接返します。これにより優先度フォールバックロジックを実装できます。例:status OR backup_status。
使用例¶
基本フィルタリング¶
// 単一条件
M::cpu:(usage_total) {host = 'web-01'} [1h]
// 複数の AND 条件(カンマ区切り)
M::cpu:(usage_total) {host = 'web-01', usage_total > 80} [1h]
// AND キーワードを使用
M::cpu:(usage_total) {host = 'web-01' AND usage_total > 80} [1h]
// 論理演算子を混在
M::cpu:(usage_total) {(host = 'web-01' OR host = 'web-02') AND usage_total > 80} [1h]
正規表現マッチング¶
// ERROR と 4 桁の数字を含むログにマッチ
L::*:(message) {message =~ 'ERROR.*\\d{4}'} [15m] LIMIT 20
// 特定のレベルプレフィックスを持つログにマッチ
L::*:(message) {message =~ '\\[(ERROR|WARN)\\].*'} [15m] LIMIT 20
// デバッグ情報を除外
L::*:(message) {message !~ 'DEBUG.*'} [15m] LIMIT 20
// ホスト名のパターンマッチ
M::cpu:(avg(usage_total)) {host =~ 'web-.*'} [1h] BY host
集合操作¶
// ログステータスフィルタリング
L::*:(count(*)) {status IN ['error', 'critical']} [1h] BY service
// 通常レベルのログを除外
L::*:(count(*)) {status NOT IN ['debug', 'info', 'ok']} [1h] BY service
// APM トレースの HTTP ステータスコードフィルタリング
T::*:(count(*)) {http_status_code IN ['500', '502', '503', '504']} [1h] BY service
配列フィールドの処理¶
フィールド型が配列(例: ホストオブジェクト O::HOST のタグ配列フィールド df_label または labels)の場合、DQL は配列要素の包含マッチングをサポートします。
ある行のデータの配列フィールド値が df_label = ['web', 'prod', 'api'] であるとします:
推奨構文: IN と NOT IN を使用(いずれかの要素がマッチ)¶
配列フィールドに IN [...] を使用すると、配列が右側のリストのいずれかの要素を含む(積集合が空でない)ことを表します。NOT IN [...] は、配列が右側のリストのどの要素も含まないことを表します。
// 配列が指定値を含むか確認
{df_label IN ['web']} // true、df_label は 'web' を含むため
{df_label IN ['mobile']} // false、df_label は 'mobile' を含まないため
// 複数の値を渡す場合: いずれかを含めば true(論理和)
{df_label IN ['web', 'mobile']} // true、'web' を含むため
// 配列がリスト内のどの値も含まないか確認
{df_label NOT IN ['mobile', 'dev']} // true、'mobile' も 'dev' も含まないため
{df_label NOT IN ['web', 'mobile']} // false、'web' を含むため
配列が複数の指定タグを同時に含む必要がある場合(論理積)は、複数の IN 条件を AND(またはカンマ)で組み合わせられます:
// 'prod' タグを持つホストオブジェクトの一覧をクエリ
O::HOST:(host, cpu_usage, mem_used_percent, df_label) {df_label IN ['prod']} LIMIT 20
// 'web' と 'prod' の両方のタグを持つホストオブジェクトの一覧をクエリ
O::HOST:(host, cpu_usage, mem_used_percent, df_label) {df_label IN ['web'], df_label IN ['prod']} LIMIT 20
互換構文(非推奨)¶
以下の = / != 構文は歴史的な互換性のために保持されており、新しいクエリでの使用は推奨されません(配列フィールドでは = は右側のすべての要素を含むこと、!= は右側のどの要素も含まないことを表し、通常のスカラーフィールドの等価セマンティクスとは異なるため混乱しやすいです):
// 歴史的構文: 単一値包含チェック(等価演算子のオーバーロードセマンティクス)
{df_label = 'web'} // true、df_label は 'web' を含むため
{df_label != 'mobile'} // true、df_label は 'mobile' を含まないため
関数フィルタリング¶
真偽値を返す関数はすべてフィルター条件として使用できます。
// 文字列マッチとワイルドカードマッチ
L::*:(message) { match(message, 'error') } [15m] LIMIT 20
L::*:(message) { wildcard(message, '*timeout*') } [15m] LIMIT 20
// 所要時間が 1 秒を超え、timeout キーワードを含むトレースをクエリ
T::*:(service, resource, duration, message) {
duration > 1000000000 AND
match(message, 'timeout')
} [15m] LIMIT 20
// error_type フィールドが存在するログをクエリ
L::*:(service, status, message) { error_type = exists() } [15m] LIMIT 20
全文検索とトークン化ルール¶
WHERE 句で search(...) または query_string(...) を使用して全文検索を行う場合、システムはまず元のテキストとクエリ条件を独立したトークン(Token)に分割し、その後トークンに基づいて高速マッチングを行います。トークン化ルールを理解すると、1 つのクエリがどのデータにヒットするかを正確に判断でき、記号や部分文字列を正確にマッチングする必要がある場合に適切な関数を選択できます。
1. 中核となる分割ルール¶
トークナイザーはテキスト内の文字を以下の 3 種類のルールで処理します(デフォルトでは大文字小文字を区別しません):
| 文字タイプ | 分割ルール | 例(元のテキスト → 分割されたトークン) |
|---|---|---|
| 英字と数字 | 連続する英字(a-z、A-Z)と数字(0-9)は同じトークンにまとめられ、小文字に統一される |
Error → errorhttp2 → http2v1_2 → v1, 2 |
| 中国語文字 | 一般的な中国語の語句または単字で独立したトークンに分割 | 连接超时 → 连接, 超时数据库异常 → 数据库, 异常 |
| 空白と句読点 | スペース、タブ、改行、およびすべての一般的な句読点は区切り文字として扱われ、トークン化時に両側のトークンを分割し、自身は独立したトークンにならない | user_name → user, nameapi.example.com → api, example, comhost-01:8080 → host, 01, 8080 |
一般的な区切り文字とその分割効果は次のとおりです:
| 記号カテゴリ | 含まれる文字 | 典型的な例(元のテキスト → トークン化結果) |
|---|---|---|
| 空白文字 | スペース、\t、\n |
error timeout → error, timeout |
| 連結子とアンダースコア | _、- |
user_name → user, namekube-system → kube, system |
| ドットとコロン | .、: |
192.168.1.1:8080 → 192, 168, 1, 1, 8080app.service:prod → app, service, prod |
| パスと URL 記号 | /、?、=、&、# |
/api/v1/users?id=42 → api, v1, users, id, 42 |
| メールとその他の句読点 | @、,、;、'、"、(、)、[、]、{、} など |
admin@example.com → admin, example, com |
2. 典型的なテキストのトークン化例¶
- URL アドレス:
https://api.example.com/v1/users?id=123&env=prod_01→ 分割:https,api,example,com,v1,users,id,123,env,prod,01 - メールとホスト名:
user_admin@mail-server.example.com→ 分割:user,admin,mail,server,example,com - 中英語混在ログ:
[ERROR] order_service: 订单支付失败, code=500→ 分割:error,order,service,订单,支付,失败,code,500
3. キーワードマッチ vs フレーズマッチ¶
クエリ条件が複数のトークンに分割される場合、記述方法によってこれらのトークンの組み合わせ方が決まります:
| マッチモード | 構文例 | 実際のマッチングロジック | ヒットするテキスト | ヒットしないテキスト |
|---|---|---|---|---|
| キーワードマッチ(デフォルト) | search("connection timeout")query_string("connection timeout") |
対象テキストがすべてのトークンを同時に含む(AND 関係)、順序と距離は問わない |
"connection timeout""timeout: connection reset" |
"connection" のみを含み "timeout" を含まないテキスト |
| フレーズマッチ(隣接かつ同順) | search("#\"build error\"")query_string("\"build error\"") |
各トークンが順序どおりに隣接して出現する必要がある(トークン間はスペースまたは句読点のみ許可) | "build error""build: error" |
"build succeeded, parse error"(間に他のトークンがある)"error during build"(順序が逆) |
注意:
.、_、-、@、/などの句読点はトークン化時にすべて区切り文字として扱われるため、フレーズマッチはトークンが順序どおり隣接しているかどうかのみを検証し、トークン間の具体的な句読点の種類は区別しません。例えばsearch("#\"user_name\"")またはquery_string("\"user_name\"")はuser_nameにもuser-nameにもuser.nameにもマッチします。
4. テキストマッチ関数の選定提案¶
| クエリ要件 | 推奨記法 | 理由 |
|---|---|---|
| 完全な単語またはフレーズを検索(大文字小文字を無視) | search("error timeout")search("#\"connection reset\"") |
トークンインデックスを直接利用でき、クエリ速度が最も速い |
| ブール組み合わせ検索(A または B を含み、C を含まない) | query_string("(error OR warn) AND NOT timeout") |
AND、OR、NOT、括弧グループをサポート |
句読点を含む部分文字列を厳密にマッチング(例: user_name と user-name を区別、または /api/v1/login を正確に検索) |
match(message, "user_name")match(message, "/api/v1/login") |
match は元の文字の部分文字列を逐字包含マッチングするため、_、/、. のトークン化によって記号の違いが無視されない |
単語内部の断片をマッチング(例: cept で Exception をマッチ) |
match(message, "cept")wildcard(message, "*cept*") |
トークン検索は完全なトークン単位であるため、search("cept") は Exception にヒットしない。部分文字列またはワイルドカードマッチを使用する必要がある |
| 大文字小文字を区別または複雑な形式でマッチング(例: 4 桁の数字エラーコード) | re(message, "ERR-\\d{4}") |
re / regexp は完全な正規表現をサポートし、大文字小文字を区別する |
// 1. 全文トークン検索: error と timeout を同時に含む(大文字小文字と語順を区別しない)
L::*:(service, message) {search("error timeout")} [15m] LIMIT 20
// 2. フレーズ順序検索: build と error が順序どおり隣接して出現する必要がある
L::*:(service, message) {search("#\"build error\"")} [15m] LIMIT 20
// 3. 厳密な部分文字列マッチ: アンダースコアを含む "user_name" を正確にマッチし、"user-name" を誤マッチしない
L::*:(service, message) {match(message, "user_name")} [15m] LIMIT 20
// 4. 組み合わせ論理検索: error または warn を含み、healthcheck を含まない
L::*:(service, message) {query_string("(error OR warn) AND NOT healthcheck")} [15m] LIMIT 20
WHERE サブクエリ¶
WHERE サブクエリは DQL で名前空間をまたぐ動的フィルタリングを実現する強力な機能であり、あるクエリの結果を別のクエリの IN / NOT IN フィルター条件として使用できます。
クエリの特徴¶
- 動的フィルタリング:フィルター条件は固定値ではなく、内側のサブクエリによって動的に計算される
- 名前空間の混在:名前空間をまたぐ関連クエリをサポート(例: まず
O::HOSTオブジェクトから特定のホストを取得し、次にM::cpuでそれらのホストのメトリクスをクエリ。またはまずLログからエラーのtrace_idを取得し、次にTトレースで呼び出し詳細をクエリ) - 単一列プロジェクション:内側のサブクエリは単一のディメンションフィールド(例:
:(host))のみを選択でき、結果は自動的に重複排除されて配列として収集され、外側のINまたはNOT INで使用される
実行フロー¶
名前空間をまたぐ典型的な WHERE サブクエリの例(Linux ホストの平均 CPU 使用率をクエリ):
実行プロセス:
-
サブクエリ実行:
O::HOST:(host) {os = 'linux'}- インフラストラクチャホストオブジェクト
O::HOSTをクエリ - オペレーティングシステム
os = 'linux'のホストを抽出 - 重複排除後のホスト名リストを返す:
['host-01', 'host-02', ...]
- インフラストラクチャホストオブジェクト
-
メインクエリ実行:
M::cpu:(avg(usage_total)) {host IN [...]} [1h] BY hostcpuメジャーメントデータをクエリ- サブクエリが返した Linux ホストのみを集計
- ホストごとにグループ化して平均 CPU 使用率を計算
使用例¶
// オブジェクトとメトリクスを関連付け: クラウドプロバイダーが aliyun のホスト CPU 使用率をクエリ
M::cpu:(avg(usage_total)) { host IN (O::HOST:(host) {cloud_provider = 'aliyun'}) } [1h] BY host
// オブジェクトとメトリクスを関連付け: 特定タグのホストのメモリ使用率をクエリ
M::mem:(avg(used_percent)) { host IN (O::HOST:(host) {df_label IN ['prod']}) } [1h] BY host
// トレースとログを関連付け: 過去 1 時間にトレースエラーが発生したサービスのエラーログ数をクエリ
L::*:(count(*)) { service IN (T::*:(service) {status = 'error'} [1h]) } [1h] BY service, status
// 履歴全期間 Top-N フィルタリング: まず 1 時間内の平均 CPU が最も高い Top 5 ホストを特定し、その後それらの 5 分時系列トレンド線を描画
M::cpu:(avg(usage_total) AS avg_cpu) {
host IN (
M::(M::cpu:(avg(usage_total) AS c) [1h::1h] BY host SORDER BY c DESC SLIMIT 5):(host) [1h::1h]
)
} [1h::5m] BY host
グループ化(group-by-clause)¶
グループ化はデータ分析の中核機能であり、データを指定したディメンションでグループ集計するために使用します。
基本構文¶
グループタイプ¶
フィールドグループ化¶
// 単一フィールドグループ化: ホストごとに CPU 使用率を集計
M::cpu:(avg(usage_total)) [1h] BY host
// 複数フィールドグループ化: ホストとディスクデバイスごとにディスク使用率を集計
M::disk:(max(used_percent)) [1h] BY host, device
// ログ多次元グループ化: サービスとログステータスごとに件数を集計
L::*:(count(*)) [1h] BY service, status
式グループ化¶
// 数学式グループ化: 所要時間の秒数帯ごとにトレース数を集計
T::*:(count(*)) [1h] BY floor(duration / 1000000000) AS duration_sec_bucket
関数グループ化¶
// Drain クラスタリングアルゴリズム: 類似ログを自動的にテンプレートに分類し頻度を集計
L::*:(count(*)) [1h] BY drain(message, 0.7) AS template
// 正規表現抽出グループ化: ログ本文からエラーコードを抽出してグループ集計
L::*:(count(*)) [1h] BY regexp_extract(message, 'error_code: (\\d+)', 1) AS error_code
グループ結果の処理¶
クエリにグループ化と時間ウィンドウの両方が含まれる場合、二次元データ構造が生成されます。Group By は時間ウィンドウと混合使用できます。このようなクエリ結果は二次元配列になります。この二次元配列の第一層はグループキーで区別される複数のグループ自体で、第二層は単一グループ内の複数時間区間データです。
二次元データ構造の例:
クエリ: M::cpu:(max(usage_total)) [1h::10m] BY host
クエリ結果構造:
{
"series": [
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8],
[1721057400000, 88.2]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-02"},
"values": [
[1721059200000, 45.2],
[1721058600000, 52.8],
[1721058000000, 48.5],
[1721057400000, 61.3]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-03"},
"values": [
[1721059200000, 92.1],
[1721058600000, 95.7],
[1721058000000, 89.4],
[1721057400000, 97.6]
]
}
]
}
この二次元配列に対してさらに加工します:
- この二次元配列の結果をフィルタリングする場合は、Having 句を使用
- 二次元配列内の単一グループ内データをソートまたはページングする場合は、order by、limit、offset 系ステートメントを使用
- 二次元配列のグループをソートまたはページングする場合は、sorder by、slimit、soffset 系ステートメントを使用
二次元データ構造の詳細な説明とソート・ページング機能については、ソートとページング を参照してください。
Having 句(having-clause){#having}¶
Having 句はグループ集計後の結果をフィルタリングするために使用され、WHERE 句 に似ていますが、集計後のデータに作用します。
基本構文¶
と WHERE の違い¶
WHERE と HAVING はどちらもデータをフィルタリングする句ですが、クエリ実行の異なる段階で作用し、処理するフィルター条件も異なります。
実行タイミングの違い¶
-
WHERE 句:
- グループ集計の前に実行
- 元のデータ行に作用
- 条件を満たさないデータ行を除外し、後続処理のデータ量を削減
-
HAVING 句:
- グループ集計の後に実行
- 集計後の結果に作用
- 集計関数のエイリアスまたは結果に基づいてフィルタリング
ユースケース¶
HAVING 句は集計結果のフィルタリングに適しています:
// 平均 CPU 使用率が 80% を超える高負荷ホストをフィルタリング
M::cpu:(avg(usage_total) AS avg_usage) [1h] BY host HAVING avg_usage > 80
// エラーログ件数が 100 件を超えるサービスをフィルタリング
L::*:(count(*) AS err_count) {status = 'error'} [1h] BY service HAVING err_count > 100
// エラー率が 1% を超え、総リクエスト数が 1000 を超える APM サービスをフィルタリング
T::*:(
count(*) AS total,
count(CASE WHEN status = 'error' THEN 1 ELSE nil END) AS errors
) [1h] BY service
HAVING errors / total > 0.01 AND total > 1000
// 平均所要時間が高く、変動範囲が大きいインターフェースをフィルタリング
T::*:(
avg(duration) AS avg_time,
max(duration) AS max_time,
min(duration) AS min_time
) [1h] BY resource
HAVING avg_time > 100000000 AND (max_time - min_time) > 500000000
ソートとページング¶
DQL のソートとページングは非常に重要かつ独特な機能であり、時系列データの特性に合わせてグループ内ソートとグループ間ソートの二重ソートメカニズムを設計しています。この設計により、DQL は複雑な多次元時系列データ分析の要件を効率的に処理できます。
DQL のデータ構造を理解する¶
ソートとページングを深く理解する前に、DQL クエリ結果の二次元データ構造を理解しましょう。クエリにグループ化(BY)と時間ウィンドウの両方が含まれる場合、二次元配列が生成されます:
- 第一維(グループディメンション):グループキーで区別される複数のグループ
- 第二維(時間ディメンション):各グループ内で時間ウィンドウごとに集計されたデータ
二次元データ構造の詳細な説明と JSON 形式の例については、グループ結果の処理 を参照してください。この二次元構造は DQL のソートとページング機能の基礎であり、この構造を理解することは DQL のソートメカニズムを習得するために重要です。
グループ内ソートとページング(ORDER BY、LIMIT、OFFSET)¶
グループ内ソートとページングは二次元構造の第二維、つまり各グループ内部のデータ(またはグループ化されていない明細クエリの行データ)に作用します。このソートは各グループ内で独立して実行され、他のグループのデータには影響しません。
基本構文¶
実行メカニズム¶
グループ内ソートの実行プロセス:
- グループ処理: 各グループに対して独立してソート操作を実行
- ソート基準: 時間フィールド、集計関数結果のエイリアス、または元のフィールドを使用可能
- ページング制限: LIMIT は各グループが返すデータ行数を制限します。明示的に指定する値は正の整数である必要があります。
- オフセット処理: OFFSET は各グループの先頭 N 行のデータをスキップ
使用例¶
基本の時間ソート¶
// 時間降順に並べ、各ホストの最新データを表示
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time DESC
// 時間昇順に並べ、履歴トレンドを表示
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time ASC
実行結果(ORDER BY time DESC):
{
"series": [
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8],
[1721057400000, 88.2],
[1721056800000, 72.1],
[1721056200000, 69.4]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-02"},
"values": [
[1721059200000, 45.2],
[1721058600000, 52.8],
[1721058000000, 48.5],
[1721057400000, 61.3],
[1721056800000, 55.7],
[1721056200000, 58.9]
]
}
]
}
数値に基づくソート¶
// CPU 使用率の降順に並べ、各ホストのピーク時間帯を特定
M::cpu:(max(usage_total) AS max_usage_total) [1h::10m] BY host ORDER BY max_usage_total DESC
// 明細クエリ: 所要時間の降順で最も遅い 10 件のトレース Span を表示
T::*:(service, resource, duration, trace_id) [15m] ORDER BY duration DESC LIMIT 10
グループ内ページング¶
// 各ホストで最新の 3 データポイントのみを表示
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time DESC LIMIT 3
// 最新の 2 データポイントをスキップし、次の 3 件を表示
M::cpu:(max(usage_total)) [1h::10m] BY host ORDER BY time DESC LIMIT 3 OFFSET 2
実行結果(LIMIT 3):
{
"series": [
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8]
]
},
{
"columns": ["time", "max(usage_total)"],
"name": "cpu",
"tags": {"host": "web-server-02"},
"values": [
[1721059200000, 45.2],
[1721058600000, 52.8],
[1721058000000, 48.5]
]
}
]
}
グループ間ソートとページング(SORDER BY、SLIMIT、SOFFSET)¶
グループ間ソートとページングは DQL の特色ある機能であり、二次元構造の第一維、つまりグループ(Series)自体をソートし Top-N を取得します。
BY を使用しないクエリでは、結果は通常 1 つのグループのみです。この場合、SORDER BY はソート上通常目に見える効果はありませんが、SLIMIT / SOFFSET は「グループ数」のセマンティクスで引き続き有効です(つまりその単一グループに対して作用)。
基本構文¶
実行メカニズムと中核セマンティクス¶
グループ間ソートの実行プロセス:
- 各グループのソート代表値を決定:
- 単一ウィンドウ集計クエリ(ステップなし、例:
[1h]): 各グループには集計結果が 1 行だけあり、SORDER BY <プロジェクションエイリアス>はその集計値でグループを直接ソートします。 - 複数時点の時系列クエリ(ステップ付き、例:
[1h::5m]): 各グループには複数の時間バケットがあります。SORDER BY <プロジェクションエイリアス>はそのグループの最後の時間バケットの値(last)でソートします。SORDER BY sum(<プロジェクションエイリアス>)/avg(<プロジェクションエイリアス>)/max(<プロジェクションエイリアス>)は、そのプロジェクション列をクエリ期間全体のすべての時間バケットで二次集計してからソートします。
- 単一ウィンドウ集計クエリ(ステップなし、例:
- グループソート: 各グループの代表値に基づいてすべてのグループを昇順または降順に並べる。
- グループページング:
SLIMITは返すグループ数を制限します(明示的に指定する値は正の整数である必要があります)。SOFFSETは先頭 N 個のグループをスキップします。
重要なお知らせ(
SORDER BYを記述する際の推奨規範): 1. Select 集計式には必ずエイリアスを付け、SORDER BYでそのエイリアスを参照してください(例:M::cpu:(avg(usage_total) AS avg_usage) [1h] BY host SORDER BY avg_usage DESC SLIMIT 5)。SORDER BYにエイリアスなしの集計や元のフィールドを直接記述しないでください(例:SORDER BY count(*)、SORDER BY avg(usage_total))。SORDER BYはプロジェクションの後に実行されるため、この時点では元の列は存在せず、プッシュダウンもできません。 2. ステップ付きの時系列クエリではどのソート方法を選択すべきか? - 最新時間バケットでソート:SORDER BY avg_usage DESCを直接記述。 - 期間全体の合計/平均/ピークでソート: プロジェクションエイリアスに集計関数を適用します。例:M::cpu:(avg(usage_total) AS avg_usage) [1h::5m] BY host SORDER BY avg(avg_usage) DESC SLIMIT 5(またはWHERE ... IN (サブクエリ)を使用して単一バケットウィンドウ[1h::1h]で Top-N ディメンションを先に選択)。
使用例¶
単一ウィンドウランキング(期間全体の集計値でソート)¶
// 過去 1 時間の平均 CPU 使用率が最も高い 5 台のホストを集計
M::cpu:(avg(usage_total) AS avg_usage) [1h] BY host SORDER BY avg_usage DESC SLIMIT 5
// 過去 1 時間の平均レスポンス所要時間が最も短い 10 個の APM サービスを集計
T::*:(avg(duration) AS avg_duration) [1h] BY service SORDER BY avg_duration ASC SLIMIT 10
// 過去 1 時間のエラーログが最も多い 5 個のサービスを集計
L::*:(count(*) AS error_count) {status = 'error'} [1h] BY service SORDER BY error_count DESC SLIMIT 5
複数時点の時系列クエリ(最新時間バケットでソート)¶
// 過去 1 時間(10 分ごと)の各ホストのピーク CPU をクエリし、最新時間バケットのピークで降順に上位 10 台のホストを取得
M::cpu:(max(usage_total) AS max_usage) [1h::10m] BY host SORDER BY max_usage DESC SLIMIT 10
// 過去 24 時間(1 時間ごと)の各ホストの最低メモリ使用率をクエリし、最新時間バケットで最も低い 5 台のホストを取得
M::mem:(min(used_percent) AS min_mem) [24h::1h] BY host SORDER BY min_mem ASC SLIMIT 5
実行結果例(SLIMIT 2):
{
"series": [
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-03"},
"values": [
[1721059200000, 92.1],
[1721058600000, 95.7],
[1721058000000, 89.4]
]
},
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8]
]
}
]
}
二重ソートとページングの組み合わせ使用¶
実際のアプリケーションでは、グループ内ソートとグループ間ソートが組み合わせて使用され、複雑なデータ表示要件を実現します。この組み合わせにより、グループの順序とグループ内データの順序を同時に制御できます。
実行順序¶
二重ソートの実行順序:
- グループ間ソート: まずすべてのグループをソートおよびページング(
SORDER BY+SLIMIT) - グループ内ソート: 選択されたグループに対して内部ソートおよびページング(
ORDER BY+LIMIT)
使用例¶
モニタリングダッシュボードのシナリオ¶
// CPU 使用率が最も高い 10 台のホストを特定し、各ホストの最新 5 時点のみを返す
M::cpu:(avg(usage_total) AS avg_usage) [1h::10m] BY host
ORDER BY time DESC LIMIT 5
SORDER BY avg_usage DESC SLIMIT 10
実行結果:
{
"series": [
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-03"},
"values": [
[1721059200000, 92.1],
[1721058600000, 95.7],
[1721058000000, 89.4],
[1721057400000, 97.6],
[1721056800000, 87.3]
]
},
{
"columns": ["time", "avg_usage"],
"name": "cpu",
"tags": {"host": "web-server-01"},
"values": [
[1721059200000, 78.5],
[1721058600000, 82.3],
[1721058000000, 75.8],
[1721057400000, 88.2],
[1721056800000, 72.1]
]
}
]
}
よくあるクエリシナリオ実践(そのままコピーして実行可能){#cookbook}¶
このセクションでは、日常の運用監視、ログトラブルシューティング、APM トレース分析、RUM ユーザーアクセス、アラートイベント集計の高頻度クエリテンプレートをまとめます。すべての例はプラットフォームのデフォルト収集によるメジャーメントと標準フィールドに基づいて作成されており、ワークスペースの「クイッククエリ / DQL クエリ」にコピーするとそのまま実行できます。
シナリオ 1: インフラストラクチャ監視(ホスト CPU / メモリ / ディスク / ネットワーク)¶
- データ前提: DataKit がインストールされ、デフォルトのホストコレクター(
cpu、mem、disk、net、systemおよびオブジェクトO::HOST)が有効。 - 期待結果: ホストまたはデバイスでグループ化されたリソース使用率ランキング、時系列トレンド、またはオンラインホスト一覧を返す。
// 1.1 過去 1 時間の平均 CPU 使用率が最も高い Top 10 ホストをクエリ(単一値ランキング)
M::cpu:(avg(usage_total) AS avg_cpu, max(usage_total) AS max_cpu) [1h] BY host SORDER BY avg_cpu DESC SLIMIT 10
// 1.2 メモリ使用率が 80% を超えるホストの時系列トレンドを表示(5 分ごと)
M::mem:(avg(used_percent) AS mem_pct) [1h::5m] BY host HAVING mem_pct > 80 SORDER BY mem_pct DESC SLIMIT 20
// 1.3 各ホストのディスクパーティション使用率と空き容量をクエリ(単位を GB に変換)
M::disk:(last(used_percent) AS disk_pct, last(free) / 1024 / 1024 / 1024 AS free_gb) [15m] BY host, device HAVING disk_pct > 75 SORDER BY disk_pct DESC SLIMIT 20
// 1.4 各ホストのネットワークインターフェースの受信・送信スループットレートを計算(Counter メトリクスは rate を使用してバイト/秒に変換)
M::net:(sum(bytes_recv) AS recv_bps, sum(bytes_sent) AS sent_bps) [1h::1m:rate] BY host SORDER BY recv_bps DESC SLIMIT 10
// 1.5 最近 10 分間にオンラインの Linux ホスト資産一覧と主要な負荷メトリクスを表示
O::HOST:(host, os, arch, cpu_usage, mem_used_percent, disk_used_percent, load) {os = 'linux', last_update_time > now() - 10m} ORDER BY cpu_usage DESC LIMIT 20
シナリオ 2: ログ検索とトラブルシューティング(Logging)¶
- データ前提: ログ収集が有効(
L名前空間、汎用フィールドmessage、status、service、source、hostを含む)。 - 期待結果: エラーログトレンド、高頻度エラーサービス、ログクラスタリングテンプレート、またはコンテキストのマスキング抽出結果を返す。
// 2.1 最近 15 分間で "timeout" または "connection refused" を含むエラーログ明細を検索
L::*:(source, service, host, status, message) {status IN ['error', 'critical'], query_string(message, "timeout OR \"connection refused\"")} [15m] ORDER BY time DESC LIMIT 50
// 2.2 サービスごとに過去 1 時間のログ書き込み QPS(毎秒ログ件数)を集計
L::*:(count(*) / 1i AS log_qps) [1h::1m] BY service SORDER BY log_qps DESC SLIMIT 10
// 2.3 各サービスのエラーログ数、総ログ数を集計し、エラーログが 10 件を超えるサービスをフィルタリング
L::*:(
count(*) AS total_logs,
count(CASE WHEN status = 'error' OR status = 'critical' THEN 1 ELSE nil END) AS error_logs
) [1h] BY service HAVING error_logs > 10 SORDER BY error_logs DESC SLIMIT 20
// 2.4 Drain アルゴリズムを使用して過去 1 時間のエラーログを自動クラスタリングし、高頻度エラーパターンをすばやく特定
L::*:(count(*) AS cnt, any(service) AS sample_service) {status = 'error'} [1h] BY drain(message, 0.7) AS log_template SORDER BY cnt DESC SLIMIT 20
シナリオ 3: APM アプリケーションパフォーマンスとトレース分析(Tracing)¶
- データ前提: APM トレースが接続済み(
T名前空間、標準フィールドservice、resource、duration、status、span_type、trace_idを含む)。 - 期待結果: サービスのスループット、エラー率、P50/P95/P99 レスポンスレイテンシ、および遅い呼び出しの明細を返す。
// 3.1 各サービスのエントリリクエスト(span_type = 'entry')の P50 / P95 / P99 レスポンスレイテンシ(単位ナノ秒)を集計
T::*:(
p50(duration) AS p50_ns,
p95(duration) AS p95_ns,
p99(duration) AS p99_ns
) {span_type = 'entry'} [1h] BY service SORDER BY p99_ns DESC SLIMIT 15
// 3.2 各サービスのリクエスト総数、エラー数、エラー率パーセントを集計
T::*:(
count(*) AS total_req,
count(CASE WHEN status = 'error' THEN 1 ELSE nil END) AS err_req,
(count(CASE WHEN status = 'error' THEN 1 ELSE nil END) / count(*)) * 100 AS err_rate_pct
) {span_type = 'entry'} [1h] BY service SORDER BY err_req DESC SLIMIT 15
// 3.3 単一インターフェースの所要時間分布ヒストグラムと分位数を分析(histogram_auto)
T::*:(histogram_auto(duration)) {span_type = 'entry'} [1h] BY service SLIMIT 10
// 3.4 最近 15 分間で最も所要時間が長い Top 20 異常呼び出しチェーン明細を検索
T::*:(service, resource, duration, http_status_code, trace_id, span_id) {status = 'error'} [15m] ORDER BY duration DESC LIMIT 20
シナリオ 4: RUM ユーザーアクセス体験分析(Real User Monitoring)¶
- データ前提: フロントエンドまたはモバイルの RUM 収集が接続済み(
R名前空間、データソースview、error、resourceを含む)。 - 期待結果: ページ PV/UV、初回画面読み込み所要時間、およびフロントエンド JS エラーランキングを返す。
// 4.1 過去 24 時間の各ページの閲覧数(PV)、独立訪問者数(UV)、平均読み込み時間を集計
R::view:(
count(*) AS pv,
count_distinct(userid) AS uv,
avg(loading_time) AS avg_load_time
) [24h] BY view_path SORDER BY pv DESC SLIMIT 20
// 4.2 過去 1 時間のフロントエンドエラーが最も多いエラータイプとサンプルメッセージを集計
R::error:(count(*) AS err_cnt, any(error_message) AS sample_msg) [1h] BY app_id, error_type SORDER BY err_cnt DESC SLIMIT 15
シナリオ 5: 前年同期比 / 前期比分析と未復旧アラートのクエリ¶
- データ前提: ワークスペースに履歴同期間データが存在(
SHIFT比較用)、またはモニターアラートが有効(E/UE名前空間)。 - 期待結果: 現在のウィンドウと昨日/先週同期間の比較結果、または現在の未復旧アラート統計を返す。
// 5.1 ログトラフィックの週次前年同期比分析: 過去 1 時間と 7 日前の同期間の各サービスログ量および増加倍率を比較
L::*:(
service,
count(*) AS current_logs,
count(*) SHIFT 7d AS last_week_logs,
CASE
WHEN (count(*) SHIFT 7d) = nil OR (count(*) SHIFT 7d) = 0 THEN nil
ELSE count(*) / (count(*) SHIFT 7d)
END AS wow_ratio
) [1h] BY service SLIMIT 15
// 5.2 現在の未復旧アラートイベント(UE 名前空間)をアラートレベルとモニターでグループ化して集計
UE::monitor:(count(*) AS active_events, any(df_title) AS sample_title) [24h] BY df_status, df_monitor_checker_name SORDER BY active_events DESC SLIMIT 20
DQL のソート、ページング、組み合わせ分析機能を習得することで、強力なモニタリングダッシュボード、パフォーマンス分析ツール、ビジネスインサイトシステムを構築できます。
注意
グループ内ソートとグループ間ソートの組み合わせを適切に使用すると、データ分析の効率と効果を大幅に向上できます。