signoz-writing-clickhouse-queries

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 がない。
• 分散テーブルを読み取るサブクエリに対する単純な IN / JOIN：distributed_product_mode='deny' では失敗します。時間範囲で絞り込むフィンガープリントの GLOBAL IN パターン、またはローカルのサブクエリテーブルを優先してください。GLOBAL JOIN は、右辺（RHS）が明らかに小さく、範囲が限定されている場合にのみ使用します。この方法では、データセットが各シャードにブロードキャストされます。
• リソース属性のフィルターがないのに、リソース CTE を追加する。
• JSONExtractString(body, ...) などの計算済み射影を含め、集約されていない射影を GROUP BY に含めない。
• $start_datetime または $end_datetime を使うログクエリ。
• $start_timestamp_nano または $end_timestamp_nano を使うトレースクエリ。
• signoz_logs.logs、裸の logs、または distributed_logs に対するログクエリ。必ず signoz_logs.distributed_logs_v2 を使用してください。
• resource_string_service$$name ではなく resources_string['service.name'] を使うトレースクエリ。

クエリの帰属情報

監視のため、生成するすべてのクエリの末尾に SETTINGS 句を必ず付けてください。

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

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

ワークフロー

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