signoz-clickhouse-query

SigNoz ダッシュボード用 ClickHouse クエリの作成

使用するタイミング

次のような SigNoz クエリをユーザーから依頼された場合に、このスキルを使用します。

• ログ：重大度、本文テキスト、ログ量、構造化フィールド、コンテナー、 サービス、環境。
• トレース：スパン、レイテンシ、所要時間、p95 または p99、HTTP 操作、DB 操作、エラースパン。
• ダッシュボードパネル：時系列グラフ、値ウィジェット、テーブルの内訳。

ユーザーがダッシュボードパネルを依頼し、ClickHouse に言及していない場合も、 このスキルを使用してください。

シグナルの判定

リクエストがログとトレースのどちらに関するものかを判定します。

• ログ：ログ行、重大度、本文テキスト、ログ量、コンテナーログ、または 構造化ログフィールド。
• トレース：スパン、レイテンシ、所要時間、p99、トレース分析、HTTP 操作、DB 操作、またはエラースパン。

リクエストが曖昧な場合は、ユーザーに確認してください。

参照先の案内

• ログ：クエリを作成する前に references/clickhouse-logs-reference.md を読んでください。
• トレース：クエリを作成する前に references/clickhouse-traces-reference.md を読んでください。

各リファレンスでは、テーブルスキーマ、最適化パターン、属性アクセス構文、 ダッシュボードテンプレート、クエリ例、検証チェックリストを説明しています。

クイックリファレンス

• 時系列パネル：時間の経過に伴うグラフ用に、(ts, value) の行を返します。
• 値パネル：統計またはカウンターウィジェット用に、単一の value を返します。
• テーブルパネル：グループ化した内訳用に、ラベル付きの列を返します。

シグナル別の主な変数

ログ

• タイムスタンプ型：ナノ秒単位の UInt64。
• 時間フィルター：$start_timestamp_nano と $end_timestamp_nano。
• バケットフィルター：$start_timestamp と $end_timestamp。
• 表示変換：fromUnixTimestamp64Nano(timestamp)。
• メインテーブル：signoz_logs.distributed_logs_v2。
• リソーステーブル：signoz_logs.distributed_logs_v2_resource。

トレース

• タイムスタンプ型：DateTime64(9)。
• 時間フィルター：$start_datetime と $end_datetime。
• バケットフィルター：$start_timestamp と $end_timestamp。
• 表示変換：タイムスタンプをそのまま使用します。
• メインテーブル：signoz_traces.distributed_signoz_index_v3。
• リソーステーブル：signoz_traces.distributed_traces_v3_resource。

主なアンチパターン

• ts_bucket_start BETWEEN $start_timestamp - 1800 AND $end_timestamp がない。
• リソースのフィンガープリントサブクエリで GLOBAL IN ではなく通常の IN を使用する。
• リソース属性フィルターがないのに、リソース CTE を追加する。
• $start_datetime または $end_datetime を使ったログクエリ。
• $start_timestamp_nano または $end_timestamp_nano を使ったトレースクエリ。
• resource_string_service$$name ではなく resources_string['service.name'] を使ったトレースクエリ。

クエリの帰属情報

生成するすべてのクエリは、監視用の SETTINGS 句で終わらなければなりません。

SELECT ...
FROM ...
WHERE ...
SETTINGS log_comment = 'signoz-clickhouse-query skill | YYYY-MM-DD'

YYYY-MM-DD を今日の日付（例：2026-04-03）に置き換えます。クエリにすでに SETTINGS 句がある場合は、カンマを付けて log_comment を追加します。

ワークフロー

1. シグナルを判定します：ログまたはトレース。
2. クエリを作成する前に、対応するリファレンスファイルを読みます。
3. パネルの種類を選びます：時系列、値、またはテーブル。
4. リファレンスにある必須パターンを使ってクエリを作成します。
5. SETTINGS log_comment の帰属情報句を追加します。
6. リファレンスのチェックリストを使って結果を検証します。