Nightingale 基于 Elasticsearch / OpenSearch 的日志告警规则配置实战指南

Nightingale 基于 Elasticsearch / OpenSearch 的日志告警规则配置实战指南

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale

本篇技术指南聚焦于夜莺（Nightingale/N9E）监控告警系统中Elasticsearch / OpenSearch 类日志数据源告警规则的完整配置方法。文中内容是 AI 侧create-alert-rule技能创建 ES 日志告警时的权威字段参考（见 elasticsearch.md，由 SKILL.md 的 Approach B 通用路径在写规则前read_file读取），同样适用于人工通过前端/API 配置告警。读完本文，你将掌握rule_config中 queries/triggers 的完整字段语义、触发条件（exp）的变量语法，以及recover_config.judge_type等恢复判定机制的底层原理，并能直接照抄文中的完整 JSON 创建一条可用的 ES 日志告警规则。

一、定位与适用场景

在 Nightingale 的告警规则体系中，每条规则都有一个cate（数据源类别）标识其查询与判定方式。Elasticsearch / OpenSearch 属于日志聚合类数据源：查询结果是某个时间窗口内对日志的聚合统计值（如计数、均值、分位数），而不是 Prometheus 那样的指标序列。

从 SKILL.md 的 cate 选择表可以看到：

在 AI 助手的实际调用链路中，Agent 会在 SKILL.md 的 B-2 步骤里执行read_file(base="create-alert-rule", path="datasources/<cate>.md")读取本文档，然后把rule_config对象序列化为 JSON 字符串传入create_alert_rule工具的rule_config_json参数。这也是理解本文所有示例的背景：文档给出的rule_config就是规则rule_config字段的原始结构。

二、Elasticsearch 与 OpenSearch 的最小差异化配置

两条核心标识字段决定了规则归属于哪类数据源：

Elasticsearch

• prod:"logging"（产品线，日志类）
• cate:"elasticsearch"
• recover_config.judge_type:0（日志类恢复判定方式）

OpenSearch

• prod:"logging"
• cate:"opensearch"
• 结构与 Elasticsearch完全一致，仅cate不同，且不支持index_pattern（即index_type只能取"index"）

关于judge_type取0的含义，见 alert_rule.go 中RecoverJudge枚举：Origin = 0表示恢复判定沿用告警本身的表达式逻辑（即触发条件不再满足即恢复）；NotRecoverWhenNoData = 1表示无数据时不恢复；RecoverOnCondition = 2表示需显式满足恢复表达式才恢复。日志类数据源使用0，即"告警条件消失即恢复"；而指标类（prometheus/mysql/pgsql/ck/tdengine）在 SKILL.md 中约定使用1。二者不可混用。

三、triggers 硬性规则（必读）

triggers是规则真正被告警引擎评估的部分，有三条硬性规则：

1. exp为必填项，且是告警引擎唯一评估的字段。一条没有exp的规则创建成功后永远不会触发告警——并且不会报任何错误。这是最容易踩的"静默失败"坑，务必自查。
2. 变量语法：本数据源使用$<ref>引用单值查询结果，例如$A > 100。ref是queries数组中某条查询的引用名（如"A"）。
3. mode固定为1（表达式模式），前端原样展示exp内容；多个条件用&&/||连接，例如"$A > 10 && $B < 5"。

从 alert_rule.go 的Trigger结构可以看到Mode、Exp、Severity、RecoverConfig正是触发器的核心字段，与文档描述一一对应。

四、rule_config 结构逐字段拆解

ES/OpenSearch 规则的rule_config由queries（查询数组）与triggers（触发数组）两部分组成，完整骨架如下：

{ "rule_config": { "queries": [ { "ref": "A", "index_type": "index", "index": "logs-*", "filter": "level:ERROR", "date_field": "@timestamp", "interval": 300, "value": { "func": "count" }, "group_by": [ {"cate": "terms", "field": "service", "size": 10} ], "keys": { "labelKey": [], "valueKey": [] } } ], "triggers": [ { "mode": 1, "exp": "$A > 100", "severity": 2, "recover_config": {"judge_type": 0} } ] } }

queries 字段参考

几点值得展开的细节：

• index_pattern的深层含义：index_type: "index_pattern"时，index不再是索引名，而是引用 Nightingale 中配置的 ES 索引模式（对应 es_index_pattern.go 中的EsIndexPattern实体，按datasource_id + name唯一约束存储，含time_field）。在 es_index_pattern.go 中可以找到反向检索逻辑：删除索引模式前会扫描rule_configJSON 中"index_type":"index_pattern","index_pattern":<id>的引用并阻止删除。OpenSearch 不支持该模式，原因在于其底层查询构造路径不同。
• date_field默认值：在公共 ES 查询组件 eslike.go 中，date_field缺省时自动回退为@timestamp；而当index_type=index_pattern时，时间字段取自索引模式配置的TimeField。
• group_by三种分组cate：terms（按字段词项聚合，配合size限制返回桶数）、filters（按过滤条件分桶）、histogram（按数值区间直方图分桶）。分组后的结果在判定时会按桶分别评估，这使一条规则可以同时覆盖多个维度（如按service分组后对每个服务分别判断错误日志数）。
• keys结构：labelKey/valueKey用于标注结果中的标签与数值字段映射，日志聚合场景通常各传空数组即可。

triggers 字段要点

五、完整示例（Elasticsearch）

以下是从文档继承的完整创建入参，可直接作为create_alert_rule的rule_config_json之外的规则主体参考。语义为：5 分钟内logs-*索引中level:ERROR的错误日志超过 100 条时触发 Warning 告警：

[{ "name": "Too many ES error logs", "note": "More than 100 error logs within 5 minutes", "prod": "logging", "cate": "elasticsearch", "datasource_ids": [2], "datasource_queries": [{"match_type": 0, "op": "in", "values": [2]}], "disabled": 0, "prom_eval_interval": 60, "prom_for_duration": 0, "rule_config": { "queries": [ { "ref": "A", "index_type": "index", "index": "logs-*", "filter": "level:ERROR", "date_field": "@timestamp", "interval": 300, "value": {"func": "count"} } ], "triggers": [ { "mode": 1, "exp": "$A > 100", "severity": 2, "recover_config": {"judge_type": 0} } ] }, "enable_in_bg": 0, "enable_days_of_weeks": [["0","1","2","3","4","5","6"]], "enable_stimes": ["00:00"], "enable_etimes": ["00:00"], "notify_recovered": 1, "notify_repeat_step": 60, "notify_max_number": 0, "callbacks": [], "append_tags": [], "annotations": {}, "extra_config": {}, "notify_version": 1, "notify_rule_ids": [] }]

逐项说明：

• datasource_ids/datasource_queries共同限定规则只作用于 datasource id 为2的数据源（match_type: 0为精确匹配，op: "in"为包含语义，结构定义见 alert_rule.go）；
• prom_eval_interval为评估间隔（秒），prom_for_duration为持续时长，设0表示条件满足即触发；
• enable_days_of_weeks/enable_stimes/enable_etimes控制生效时间窗口（此处为全天生效）；
• notify_recovered: 1表示恢复时也发送通知；notify_repeat_step: 60为重复告警间隔（秒）；notify_max_number: 0表示不限制重复次数；
• notify_rule_ids为空数组，即默认不绑定任何通知规则——这与 SKILL.md 中"导入/创建的规则默认不关联通知渠道以避免误报"的约定一致，需要告警触达时需另行关联。

若需创建 OpenSearch 规则，仅需将"cate": "elasticsearch"改为"cate": "opensearch"，其余字段保持一致，并确保index_type不使用"index_pattern"。

六、源码视角：interval为什么必须是总秒数

文档反复强调interval的单位是总秒数，且不要写interval_unit，这背后是前后端与 AI 工具三方的约定（SKILL.md）：

• 前端保存规则时，把值 × 单位换算成秒后写入interval；
• 读取展示时再根据秒数反推出显示单位；
• 因此若写成"interval": 5, "interval_unit": "min"，前端只会把它显示为5 秒，语义完全错误；
• create_alert_rule工具有防御性兜底：若误写了interval_unit或写了小于 60 的裸数值，会自动换算为秒，但正确写法应一步到位。

常用取值速查：最近 1 分钟 →60；最近 5 分钟 →300；最近 1 小时 →3600。

七、常见问题排查清单

结合本文与 SKILL.md 的通用约束，ES/OpenSearch 告警规则创建后不触发时按以下顺序排查：

1. exp是否缺失或引用名错误：规则创建成功但永不触发、且无任何报错，几乎都是exp缺失或$A与 queries 中的ref不一致导致；
2. mode是否等于1：非表达式模式不会按预期评估exp；
3. interval单位：是否误写成分钟数并带上了interval_unit；
4. recover_config.judge_type：日志类必须是0，误用指标类的1会导致恢复语义异常；
5. OpenSearch 使用index_pattern：该类型不受支持，应改用index_type: "index"；
6. filter语法与索引通配：确认logs-*能命中真实索引、level:ERROR符合该索引的字段映射（可通过数据源查询接口先行验证）。

掌握以上要点后，无论是通过 AI 助手自然语言创建（create_alert_rule+cate=elasticsearch/opensearch），还是手工构造规则 JSON，都能准确产出可稳定触发、可正确恢复的 ES/OpenSearch 日志告警规则。同类日志数据源（如 Loki、VictoriaLogs）的规则结构与本文一脉相承，可对照 datasources 目录下的对应参考文档继续查阅。

【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale