Nightingale 创建 VictoriaLogs 日志告警规则LogsQL stats 管道语法与 rule_config 实战指南【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale本文是 NightingaleN9E监控告警平台中VictoriaLogs 日志数据源告警规则创建的专项实战指南。全文围绕 create-alert-rule 技能技能入口中datasources/victorialogs.md的规范展开讲解 LogsQL 聚合查询必须遵循的| stats管道语法、rule_config的 JSON 结构、trigger 表达式exp的变量引用规则并结合 dskit/victorialogs/victorialogs.go 源码揭示底层/select/logsql/stats_query端点的实现原理。读完本文你将能够手写并正确提交一条可稳定运行的 VictoriaLogs 日志告警规则并学会排查规则保存成功但永远无数据这一类高频问题。1. 定位VictoriaLogs 告警规则的三个关键标识在 Nightingale 中VictoriaLogs 属于日志型log type数据源创建告警规则时必须显式携带以下标识字段取值含义prodlogging产品类型标记为日志场景catevictorialogs数据源类别驱动告警引擎走 VictoriaLogs 查询路径recover_config.judge_type0恢复判定类型0表示日志型以查询结果有无/计数来判定而指标型数据源prometheus/mysql/pgsql/ck/tdengine使用1cate取值在 aiagent/tools/alert_rule.go 中被白名单校验可选值包括prometheus/loki/elasticsearch/opensearch/tdengine/ck/mysql/pgsql/doris/victorialogs/hostvictorialogs是其中明确支持的一类。用户在对话中表达应用错误日志VictoriaLogs 日志等诉求时Agent 应选择catevictorialogs并走 create-alert-rule 的通用路径SKILL.md 中 B-1 步骤。2. 核心约束VictoriaLogs 告警查询必须使用| stats管道语法VictoriaLogs 告警查询最终通过/select/logsql/stats_query端点执行。在 dskit/victorialogs/victorialogs.go 中StatsQuery函数将query参数原样 POST 到该端点并将响应解析为 Prometheus 风格的PrometheusResponsestatus/data.resultType/data.result。该端点只接受带| stats管道的聚合查询不接受纯过滤查询——这是整篇文档最重要的约束。错误写法只会报错或返回空结果_msg:error service:payment AND level:error正确写法filter condition | stats aggregation function2.1 常用聚合场景与 LogsQL 写法需求LogsQL最近 5 分钟错误日志条数_msg:error \| stats count() as value某服务错误日志条数service:payment AND level:error \| stats count() as value按服务分组统计条数level:error \| stats by (service) count() as value平均响应时间* \| stats avg(duration) as value多个聚合同时输出_msg:error \| stats count() as error_count, avg(duration) as avg_dur注意上表中 LogsQL 里的\|是 Markdown 表格转义写法实际写入 JSON 时应还原为单个|。2.2 四条关键规则| stats之后的每个聚合函数都必须起别名as value/as count等别名即返回结果的字段名告警引擎按别名匹配取值分组使用stats by (field1, field2) ...过滤部分可以是任意 LogsQL 过滤条件_msg:keyword、field:value、field:value with space、_time:5m等。源码层面的佐证来自 dskit/victorialogs/victorialogs_test.go测试用例TestVictoriaLogs_StatsQuery使用* | stats count() as total验证单点统计TestVictoriaLogs_StatsQueryByField使用* | stats by (level) count() as cnt验证分组统计TestVictoriaLogs_StatsQueryRange使用* | stats count() as total加step5m验证时间范围统计——这些正是文档中推荐写法的直接回归证据。此外若需要获取命中的日志总数如用于大盘展示HitsLogs走/select/logsql/hits端点与告警用的stats_query是两条不同的路径不要把二者混淆。3. triggers 硬性规则必读VictoriaLogs 告警的触发条件triggers有三条硬性规则违反任何一条都会导致规则静默失效exp必填且是告警引擎唯一求值的字段——一条没有exp的规则创建后永远不会触发并且不会报任何错误变量语法为$ref.stats输出别名例如$A.value 20对应stats count() as value当只有一个 stats 输出时可以省略别名直接写$Amode固定为1表达式模式前端按原样展示 exp多个条件用/||连接例如$A.value 10 $B.value 5。这一exp 是唯一求值入口、缺失即静默的设计要求使用者必须在提交前自检 exp 是否填写完整。4. rule_config 结构详解VictoriaLogs 告警规则的完整rule_config骨架如下{ rule_config: { queries: [ { ref: A, query: _msg:error | stats count() as value, interval: 60 } ], triggers: [ { mode: 1, exp: $A.value 20, severity: 2, recover_config: {judge_type: 0} } ] } }通过create_alert_rule工具的通用路径创建时需要把上述rule_config对象序列化为 JSON字符串传给rule_config_json参数在 aiagent/tools/alert_rule.go 中该参数必须是可解析的合法 JSON 对象否则会返回带datasources/cate.md提示的解析错误。调用格式可参考 SKILL.md 中 MySQL 示例的形态将cate换成victorialogs、rule_config_json换成上文结构即可。5. query 字段参考字段必填说明ref✅查询引用名如A供 exp 引用query✅LogsQL 查询必须为filter \| stats function格式interval❌查询时间窗口单位为总秒数601 分钟3005 分钟。不要写interval_unit关于interval的单位SKILL.md 通用规则有补充说明前端保存时会把值 × 单位换算成秒读取时再反推显示单位因此写interval: 5, interval_unit: min会被前端显示为 5 秒。工具侧有防御性兜底误写interval_unit或小于 60 的裸值会自动换算成秒但最佳实践仍是直接写对总秒数。6. 完整示例应用错误日志告警以下是一条完整可提交的规则 JSON可直接用于import_alert_rule批量导入接口或作为create_alert_rule构造参考[{ name: Application error log alert, note: More than 20 error logs for the payment service in the last 1 minute, prod: logging, cate: victorialogs, datasource_ids: [11], datasource_queries: [{match_type: 0, op: in, values: [11]}], disabled: 0, prom_eval_interval: 30, prom_for_duration: 60, rule_config: { queries: [ { ref: A, query: service:payment AND _msg:error | stats count() as value, interval: 60 } ], triggers: [ { mode: 1, exp: $A.value 20, severity: 2, recover_config: {judge_type: 0} } ] }, notify_version: 1 }]字段拆解name/note规则名与告警说明note 同时作为告警通知正文datasource_ids: [11]与datasource_queries将规则绑定到具体的 VictoriaLogs 数据源ID 11 为示例实际以list_datasources返回为准prom_eval_interval: 30每 30 秒评估一次prom_for_duration: 60持续 60 秒满足条件才触发注意应大于eval_intervalquery过滤servicepayment且_msg含error的日志统计 1 分钟interval: 60内的条数exp: $A.value 20引用查询 A 的value别名超过 20 即触发severity: 2Warning 级别1Critical2Warning3Info默认 2。7. 故障排查症状原因修复规则保存成功但一直无数据查询只有过滤条件缺少\| stats追加\| stats count() as value或其他聚合no stats clause错误同上同上拿不到聚合值聚合没有起别名给聚合加as value并让value与阈值一致这三个症状本质上是同一类问题stats_query端点只接受聚合查询对应 StatsQuery 的实现约束以及别名是引擎取值的唯一入口。排查顺序建议为先确认 query 带| stats且聚合有别名 → 再确认 exp 的$A.别名与as 别名完全一致 → 最后确认interval是总秒数、recover_config.judge_type为0。8. 小结VictoriaLogs 告警规则四步自检标识prodlogging、catevictorialogs、recover_config.judge_type0查询filter | stats 聚合 as 别名过滤部分任意聚合必须起别名必要时用stats by (...)分组触发器mode1exp必填且格式为$ref.别名 比较符 阈值多条件用/||连接参数interval写总秒数不写interval_unit。按照这四步配合 create-alert-rule 技能与 VictoriaLogs 驱动源码即可在 Nightingale 中稳定落地日志驱动的告警规则。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nightingale 创建 VictoriaLogs 日志告警规则：LogsQL stats 管道语法与 rule_config 实战指南
Nightingale 创建 VictoriaLogs 日志告警规则LogsQL stats 管道语法与 rule_config 实战指南【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale本文是 NightingaleN9E监控告警平台中VictoriaLogs 日志数据源告警规则创建的专项实战指南。全文围绕 create-alert-rule 技能技能入口中datasources/victorialogs.md的规范展开讲解 LogsQL 聚合查询必须遵循的| stats管道语法、rule_config的 JSON 结构、trigger 表达式exp的变量引用规则并结合 dskit/victorialogs/victorialogs.go 源码揭示底层/select/logsql/stats_query端点的实现原理。读完本文你将能够手写并正确提交一条可稳定运行的 VictoriaLogs 日志告警规则并学会排查规则保存成功但永远无数据这一类高频问题。1. 定位VictoriaLogs 告警规则的三个关键标识在 Nightingale 中VictoriaLogs 属于日志型log type数据源创建告警规则时必须显式携带以下标识字段取值含义prodlogging产品类型标记为日志场景catevictorialogs数据源类别驱动告警引擎走 VictoriaLogs 查询路径recover_config.judge_type0恢复判定类型0表示日志型以查询结果有无/计数来判定而指标型数据源prometheus/mysql/pgsql/ck/tdengine使用1cate取值在 aiagent/tools/alert_rule.go 中被白名单校验可选值包括prometheus/loki/elasticsearch/opensearch/tdengine/ck/mysql/pgsql/doris/victorialogs/hostvictorialogs是其中明确支持的一类。用户在对话中表达应用错误日志VictoriaLogs 日志等诉求时Agent 应选择catevictorialogs并走 create-alert-rule 的通用路径SKILL.md 中 B-1 步骤。2. 核心约束VictoriaLogs 告警查询必须使用| stats管道语法VictoriaLogs 告警查询最终通过/select/logsql/stats_query端点执行。在 dskit/victorialogs/victorialogs.go 中StatsQuery函数将query参数原样 POST 到该端点并将响应解析为 Prometheus 风格的PrometheusResponsestatus/data.resultType/data.result。该端点只接受带| stats管道的聚合查询不接受纯过滤查询——这是整篇文档最重要的约束。错误写法只会报错或返回空结果_msg:error service:payment AND level:error正确写法filter condition | stats aggregation function2.1 常用聚合场景与 LogsQL 写法需求LogsQL最近 5 分钟错误日志条数_msg:error \| stats count() as value某服务错误日志条数service:payment AND level:error \| stats count() as value按服务分组统计条数level:error \| stats by (service) count() as value平均响应时间* \| stats avg(duration) as value多个聚合同时输出_msg:error \| stats count() as error_count, avg(duration) as avg_dur注意上表中 LogsQL 里的\|是 Markdown 表格转义写法实际写入 JSON 时应还原为单个|。2.2 四条关键规则| stats之后的每个聚合函数都必须起别名as value/as count等别名即返回结果的字段名告警引擎按别名匹配取值分组使用stats by (field1, field2) ...过滤部分可以是任意 LogsQL 过滤条件_msg:keyword、field:value、field:value with space、_time:5m等。源码层面的佐证来自 dskit/victorialogs/victorialogs_test.go测试用例TestVictoriaLogs_StatsQuery使用* | stats count() as total验证单点统计TestVictoriaLogs_StatsQueryByField使用* | stats by (level) count() as cnt验证分组统计TestVictoriaLogs_StatsQueryRange使用* | stats count() as total加step5m验证时间范围统计——这些正是文档中推荐写法的直接回归证据。此外若需要获取命中的日志总数如用于大盘展示HitsLogs走/select/logsql/hits端点与告警用的stats_query是两条不同的路径不要把二者混淆。3. triggers 硬性规则必读VictoriaLogs 告警的触发条件triggers有三条硬性规则违反任何一条都会导致规则静默失效exp必填且是告警引擎唯一求值的字段——一条没有exp的规则创建后永远不会触发并且不会报任何错误变量语法为$ref.stats输出别名例如$A.value 20对应stats count() as value当只有一个 stats 输出时可以省略别名直接写$Amode固定为1表达式模式前端按原样展示 exp多个条件用/||连接例如$A.value 10 $B.value 5。这一exp 是唯一求值入口、缺失即静默的设计要求使用者必须在提交前自检 exp 是否填写完整。4. rule_config 结构详解VictoriaLogs 告警规则的完整rule_config骨架如下{ rule_config: { queries: [ { ref: A, query: _msg:error | stats count() as value, interval: 60 } ], triggers: [ { mode: 1, exp: $A.value 20, severity: 2, recover_config: {judge_type: 0} } ] } }通过create_alert_rule工具的通用路径创建时需要把上述rule_config对象序列化为 JSON字符串传给rule_config_json参数在 aiagent/tools/alert_rule.go 中该参数必须是可解析的合法 JSON 对象否则会返回带datasources/cate.md提示的解析错误。调用格式可参考 SKILL.md 中 MySQL 示例的形态将cate换成victorialogs、rule_config_json换成上文结构即可。5. query 字段参考字段必填说明ref✅查询引用名如A供 exp 引用query✅LogsQL 查询必须为filter \| stats function格式interval❌查询时间窗口单位为总秒数601 分钟3005 分钟。不要写interval_unit关于interval的单位SKILL.md 通用规则有补充说明前端保存时会把值 × 单位换算成秒读取时再反推显示单位因此写interval: 5, interval_unit: min会被前端显示为 5 秒。工具侧有防御性兜底误写interval_unit或小于 60 的裸值会自动换算成秒但最佳实践仍是直接写对总秒数。6. 完整示例应用错误日志告警以下是一条完整可提交的规则 JSON可直接用于import_alert_rule批量导入接口或作为create_alert_rule构造参考[{ name: Application error log alert, note: More than 20 error logs for the payment service in the last 1 minute, prod: logging, cate: victorialogs, datasource_ids: [11], datasource_queries: [{match_type: 0, op: in, values: [11]}], disabled: 0, prom_eval_interval: 30, prom_for_duration: 60, rule_config: { queries: [ { ref: A, query: service:payment AND _msg:error | stats count() as value, interval: 60 } ], triggers: [ { mode: 1, exp: $A.value 20, severity: 2, recover_config: {judge_type: 0} } ] }, notify_version: 1 }]字段拆解name/note规则名与告警说明note 同时作为告警通知正文datasource_ids: [11]与datasource_queries将规则绑定到具体的 VictoriaLogs 数据源ID 11 为示例实际以list_datasources返回为准prom_eval_interval: 30每 30 秒评估一次prom_for_duration: 60持续 60 秒满足条件才触发注意应大于eval_intervalquery过滤servicepayment且_msg含error的日志统计 1 分钟interval: 60内的条数exp: $A.value 20引用查询 A 的value别名超过 20 即触发severity: 2Warning 级别1Critical2Warning3Info默认 2。7. 故障排查症状原因修复规则保存成功但一直无数据查询只有过滤条件缺少\| stats追加\| stats count() as value或其他聚合no stats clause错误同上同上拿不到聚合值聚合没有起别名给聚合加as value并让value与阈值一致这三个症状本质上是同一类问题stats_query端点只接受聚合查询对应 StatsQuery 的实现约束以及别名是引擎取值的唯一入口。排查顺序建议为先确认 query 带| stats且聚合有别名 → 再确认 exp 的$A.别名与as 别名完全一致 → 最后确认interval是总秒数、recover_config.judge_type为0。8. 小结VictoriaLogs 告警规则四步自检标识prodlogging、catevictorialogs、recover_config.judge_type0查询filter | stats 聚合 as 别名过滤部分任意聚合必须起别名必要时用stats by (...)分组触发器mode1exp必填且格式为$ref.别名 比较符 阈值多条件用/||连接参数interval写总秒数不写interval_unit。按照这四步配合 create-alert-rule 技能与 VictoriaLogs 驱动源码即可在 Nightingale 中稳定落地日志驱动的告警规则。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考