signoz-clickhouse-query

为 SigNoz 仪表板编写 ClickHouse 查询

何时使用

当用户提出有关 SigNoz 查询的需求，涉及以下内容时，请使用此技能：

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

如果用户要求创建仪表板面板，但没有提到 ClickHouse，也请使用此技能。

信号检测

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

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

如果请求含糊不清，请让用户进一步说明。

参考资料路由

• 日志：编写任何查询前，先阅读 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，而不是 GLOBAL IN。
• 没有资源属性筛选器时仍添加资源 CTE。
• 日志查询使用 $start_datetime 或 $end_datetime。
• 追踪查询使用 $start_timestamp_nano 或 $end_timestamp_nano。
• 追踪查询使用 resources_string['service.name']，而不是 resource_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. 根据参考资料中的清单验证结果。