signoz-writing-clickhouse-queries

为 SigNoz 仪表板编写 ClickHouse 查询

适用场景

当用户请求编写涉及以下内容的 SigNoz 查询时，使用此技能：

• 日志：严重性、正文文本、日志量、结构化字段、容器、 服务或环境。
• 追踪：Span、延迟、持续时间、p95 或 p99、HTTP 操作、数据库 操作或错误 Span。
• 仪表板面板：时序图、数值组件和表格细分。

如果用户请求创建仪表板面板，但未提及 ClickHouse，仍要使用此技能。

信号识别

判断请求涉及日志还是追踪。

• 日志：日志行、严重性、正文文本、日志量、容器日志或 结构化日志字段。
• 追踪：Span、延迟、持续时间、p99、追踪分析、HTTP 操作、数据库 操作或错误 Span。

如果请求不明确，请向用户确认。

参考资料路由

• 日志：编写任何查询前，阅读 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 模式或本地子查询表。只有在 RHS 明确规模较小且范围有限时才使用 GLOBAL JOIN；它会将该数据集广播到每个分片。
• 没有资源属性筛选器时仍添加资源 CTE。
• 未将非聚合投影添加到 GROUP BY，包括诸如 JSONExtractString(body, ...) 这样的计算投影。
• 日志查询使用 $start_datetime 或 $end_datetime。
• 追踪查询使用 $start_timestamp_nano 或 $end_timestamp_nano。
• 日志查询使用 signoz_logs.logs、裸表名 logs 或 distributed_logs； 始终使用 signoz_logs.distributed_logs_v2。
• 追踪查询使用 resources_string['service.name']，而不是 resource_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. 使用参考资料中的清单验证结果。