ClickHouse 告警规则配置说明

本文档详细介绍如何在 Monitors 告警引擎中配置 ClickHouse 数据源的告警规则。Monitors 支持使用标准 SQL 语法对 ClickHouse 进行查询，并根据查询结果触发告警。

前置说明

查询语言：使用 ClickHouse SQL 语法。

字段处理：告警引擎会自动将查询结果的所有字段名转换为小写。在配置"值字段"和"标签字段"时，请务必使用小写字母。

类型转换：ClickHouse 的数据类型较为丰富（如 DateTime、Nullable、Array 等），告警引擎可能无法直接解析复杂类型。建议在 SQL 中使用 toString()、toFloat64() 等函数将结果转换为基础类型。

1. 阈值判定模式

此模式适用于需要对聚合后的数值进行阈值比对的场景。

配置方式

查询语句：编写 SQL 聚合查询，返回数值列和（可选的）标签列。

示例：统计最近 5 分钟内，各服务的错误日志数量。

字段映射：

标签字段：用于区分不同告警对象的字段。上例中为 service_name。该字段可留空，Monitors 会自动把除了值字段外的所有字段都作为标签字段。

值字段：用于阈值判定的数值字段。上例中为 error_cnt。

阈值条件：

使用 $A.field_name 引用数值。

示例：Critical: $A.error_cnt > 50，Warning: $A.error_cnt > 10。

工作原理

引擎执行 SQL 查询，获取结果集。根据"标签字段"将数据分组，然后提取"值字段"的数值与阈值表达式进行比对。

恢复逻辑

自动恢复：当最新的 SQL 查询结果中，某组数据的数值不再满足任何告警阈值时，自动生成恢复事件。

特定恢复条件：配置额外的恢复表达式（如 $A.error_cnt < 5）。

恢复查询：

支持配置独立的 SQL 语句用于恢复判定。

支持 ${label_name} 变量替换。

示例：告警 SQL 查出了 network_host="a", interface="b" 的网卡挂了。恢复 SQL 可以写：

引擎会将 ${network_host} 和 ${interface} 替换为实际值后执行查询，如果查到数据，则判定恢复。

2. 数据存在模式

此模式适用于将过滤逻辑直接写在 SQL 中的场景。

配置方式

查询语句：在 SQL 中使用 HAVING 子句直接过滤出异常数据。

示例：直接查询错误数超过 50 的服务。

判定规则：只要 SQL 查询返回了数据，即触发告警。

优缺点分析

优点：利用 ClickHouse 强大的 OLAP 能力进行计算和过滤，性能极佳。

缺点：无法区分多级告警。

恢复逻辑

数据消失即恢复：当 SQL 查询结果为空时，判定恢复。

恢复查询：支持配置额外的查询语句用于辅助判断恢复状态。

3. 数据缺失模式

此模式用于监控"预期应该有数据，但实际没有数据"的场景。

配置方式

查询语句：编写一个预期应该持续返回数据的 SQL 查询。

示例：查询所有探针的心跳上报。

判定规则：如果某个 probe_id 在之前的周期中出现过，但在当前及连续 N 个周期中查不到数据，则触发"数据缺失"告警。

4. 最佳实践与注意事项

类型转换

ClickHouse 的驱动在处理某些复杂类型时可能会返回引擎无法识别的格式。

建议：在 SELECT 子句中显式转换类型。

toString(uuid)

toFloat64(avg_duration)

时间过滤

ClickHouse 对时间分区非常敏感。务必在 WHERE 子句中包含时间范围过滤，以便利用索引加速查询。

推荐写法：timestamp > now() - INTERVAL 5 MINUTE 或 timestamp > toDateTime(now()) - 300。

字段大小写

Monitors 引擎会将 ClickHouse 返回的列名统一转为小写。

配置：在填写"标签字段"和"值字段"时，请始终使用小写字母。

ClickHouse

前置说明#

1. 阈值判定模式#

配置方式#

工作原理#

恢复逻辑#

2. 数据存在模式#

配置方式#

优缺点分析#

恢复逻辑#

3. 数据缺失模式#

配置方式#

4. 最佳实践与注意事项#

类型转换#

时间过滤#

字段大小写#

前置说明

1. 阈值判定模式

配置方式

工作原理

恢复逻辑

2. 数据存在模式

配置方式

优缺点分析

恢复逻辑

3. 数据缺失模式

配置方式

4. 最佳实践与注意事项

类型转换

时间过滤

字段大小写