尧图网页设计 
Nightingale Host 机器失联告警规则完全指南queries / triggers 结构与源码级原理解析【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale导读本篇指南围绕 NightingaleN9E中一类特殊的告警规则——Host 机器监控告警规则展开完整讲解rule_config中queries机器筛选条件与triggers失联触发条件的字段语义、取值选项与完整可运行示例并结合仓库源码models/alert_rule.go、alert/eval/eval.go剖析机器失联失联比例时间偏移过大三类触发器的底层判定逻辑。读完本文你将能够独立编写、校验并理解 Host 类型告警规则也能通过 AI Agent 的create-alert-ruleSkill见 SKILL.md快速生成此类规则。一、Host 类型告警规则的定位它与其他数据源类型有何不同在 Nightingale 的告警规则体系中绝大多数规则Prometheus / Loki / ES / MySQL / TDengine 等都是查询某数据源中的指标或日志再对数值做阈值判断。而 Host 类型是相当特殊的一类prod固定为hostcate固定为host不需要指定datasource_ids数据源机器失联判断依据的不是某条时序数据而是机器向服务端上报心跳heartbeat的时间戳正如 SKILL.md 中强调的catehosthost-unreachable classdoes not need a data source。因此在用create_alert_rule工具创建 Host 规则时datasource_id可以省略见 SKILL.md 的参数表。该类型的 queries查询/筛选结构与 triggers触发结构与其他类型完全不同这是它在设计上最显著的特征。二、rule_config 结构queries triggers 双段式Host 规则的rule_config是一个由queries与triggers两个数组组成的 JSON 对象{ rule_config: { queries: [ { key: all_hosts, op: , values: [] } ], triggers: [ { type: target_miss, severity: 2, duration: 30 } ] } }从源码结构看该 JSON 与模型层定义一一对应。在 models/alert_rule.go 中定义了HostRuleConfigtype HostRuleConfig struct { Queries []HostQuery json:queries Triggers []HostTrigger json:triggers Inhibit bool json:inhibit }其中HostQuerymodels/alert_rule.go由key/op/values三个字段构成queries用于圈定被监控的机器范围HostTriggermodels/alert_rule.go由type/duration/percent/severity四个字段构成triggers用于定义失联的判定条件与告警级别。另外HostRuleConfig还含一个inhibit字段用于规则级抑制inhibit开关。2.1 queries 段如何圈定被监控的机器queries中的每个元素都是形如{key, op, values}的过滤条件对应模型层定义type HostQuery struct { Key string json:key Op string json:op Values []interface{} json:values }多条 query 之间是逻辑与AND关系即所有条件同时满足的机器才会进入告警判定范围。key 选项key含义values 示例all_hosts全部机器[]group_ids按业务组business group筛选[1, 2, 3]tags按标签筛选[envprod, regioncn]hosts按主机名ident筛选[web-01, web-02]这些 key 在底层会被转换为针对target表的过滤 SQL。以 models/alert_rule.go 的GetHostsQuery函数为证group_ids转换为target_busi_group.group_id in (?)之类的关联查询特殊地当 values 包含0时表示未归组的机器对应target_ident IS NULL分支代码中有详细注释说明依赖 LEFT JOIN 才能表达未归组语义tags时对tags与host_tags两列做like %tag%匹配!时生成tags not like ? and (host_tags not like ? or host_tags is null)hosts生成ident in (?)!生成ident not in (?)~/!~则把*通配符替换为 SQL 的%后执行ident like模糊匹配。op 选项op含义适用范围等于所有 key!不等于所有 key~正则匹配仅hostskey 支持底层实现为将*转成%的 like 匹配!~正则不匹配仅hostskey 支持2.2 triggers 段如何定义失联触发条件triggers中的每个元素都是形如{type, severity, duration}的触发条件HostTrigger结构体还额外包含百分比字段percenttype HostTrigger struct { Type string json:type Duration int json:duration Percent int json:percent Severity int json:severity }type 选项type含义额外字段target_miss机器失联未上报duration秒pct_target_miss失联机器占比超阈值duration秒percent百分比offset机器时间偏移过大duration秒2.3 三类触发器的源码级判定逻辑Host 规则的实际求值发生在 alert/eval/eval.go 的GetHostAnomalyPoint函数中。该函数把rule_config反序列化为models.HostRuleConfig随后遍历rule.Triggers按trigger.Type分派target_miss机器失联计算时间阈值t now - trigger.Duration从TargetsOfAlertRuleCache取出该规则覆盖的机器集合idents中心节点还会把 engineName 为空的不再上报机器并入集合通过TargetCache.GetHostUpdateTime(idents)拿到每台机器的最近上报时间凡是updateTime t的机器即被判为失联missTargets为每台失联机器生成异常点标签中注入identvalue 取now - target.BeatTime已失联秒数并携带trigger.Severity。pct_target_miss失联占比同样先取时间阈值与机器集合统计missTargets计算pct len(missTargets) / len(idents) * 100当pct trigger.Percent时整条规则才触发一个异常点value 即百分比。offset时间偏移过大通过TargetCache.GetHostMetas获取机器上报的元数据跳过CpuNum 0非 categraf 采集以及now-BeatTime 120非活跃机器的目标当|meta.Offset| trigger.Duration时判定该机器时间偏移异常value 取偏移量毫秒。由上述逻辑可以推断target_miss的duration语义是最后一次上报距今超过 N 秒pct_target_miss的percent语义是失联机器数占全部目标数的百分比阈值offset的duration则是允许的最大时间偏移毫秒级数值。三、完整示例机器失联告警可直接创建下面是创建一条机器失联告警规则的完整 JSON来自 host.md可直接用于create_alert_rule的rule_config_json或前端创建[{ name: Machine unreachable alert, note: Machine has not reported data for more than 60 seconds, prod: host, cate: host, datasource_ids: [], datasource_queries: [{match_type: 0, op: in, values: []}], disabled: 0, prom_eval_interval: 30, prom_for_duration: 0, rule_config: { queries: [{key: all_hosts, op: , values: []}], triggers: [{type: target_miss, severity: 1, duration: 60}] }, 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: [] }]关键字段说明name/note规则名称与告警内容描述prod: host、cate: host标识这是 Host 类型规则。模型层中HOST hostmodels/alert_rule.go且IsHostRule()按prod host判定见 models/alert_rule.go校验时 Host 规则使用type/duration/percent描述的 triggers 而不是 Prom 的prom_ql表达式见 models/alert_rule.go 的注释与校验分支datasource_ids: []留空即可Host 规则不依赖数据源rule_config.queriesall_hosts []表示监控全部机器如需限定范围可改为group_ids、tags或hostsrule_config.triggerstarget_missseverity: 1duration: 60表示机器超过 60 秒未上报数据即以 Critical1 级告警prom_eval_interval: 30规则评估周期 30 秒notify_recovered: 1恢复后发送恢复通知notify_repeat_step: 60重复告警间隔 60 秒。在 AI Agent 场景下这条规则对应create_alert_rule的通用路径Approach B Mode 2先read_file(basecreate-alert-rule, pathdatasources/host.md)获取结构模板再把rule_config对象序列化为 JSON 字符串传入rule_config_json详见 SKILL.md。四、常用场景速查queries 与 triggers 组合4.1 只监控指定业务组{ rule_config: { queries: [{key: group_ids, op: , values: [1, 2, 3]}], triggers: [{type: target_miss, severity: 2, duration: 120}] } }4.2 按标签圈定机器{ rule_config: { queries: [{key: tags, op: , values: [envprod, regioncn]}], triggers: [{type: target_miss, severity: 2, duration: 60}] } }4.3 按主机名 正则排除{ rule_config: { queries: [ {key: hosts, op: ~, values: [web-*]}, {key: hosts, op: !~, values: [web-99]} ], triggers: [{type: target_miss, severity: 2, duration: 90}] } }4.4 失联机器占比告警{ rule_config: { queries: [{key: all_hosts, op: , values: []}], triggers: [{type: pct_target_miss, severity: 2, duration: 300, percent: 50}] } }含义全部机器中失联超过 300 秒的数量占比达到 50% 时触发 Warning 告警判定逻辑见上文pct trigger.Percent的源码实现。4.5 机器时间偏移告警{ rule_config: { queries: [{key: all_hosts, op: , values: []}], triggers: [{type: offset, severity: 3, duration: 5000}] } }含义机器上报的时间偏移超过 5000毫秒量级时触发 Info 级告警。注意源码中会跳过CpuNum 0非 categraf 采集与不活跃机器因此该触发器面向由 categraf 采集上报的活跃目标。五、使用注意与边界无需数据源但需要机器接入上报Host 规则的判定完全依赖机器上报心跳后写入的target表数据上报时间戳、tags、host_tags、offset 等因此被监控机器必须已通过 categraf或等价 Agent接入 Nightingale 并持续上报。queries 多条为 AND 关系hosts ~ web-*与hosts !~ web-99同时使用时只有同时满足两条的机器才进入判定范围。~/!~仅支持hostskey对group_ids、tags使用正则运算符不会被支持请改用/!。group_ids传0表示未归组机器源码中专门处理了group_id0与业务组 ID 混合的场景见 models/alert_rule.go。校验差异Host 规则在模型层校验时走独立分支——isHost : ar.Prod HOST || ar.Cate HOST它要求的是type/duration/percent结构的 triggers而非 Prom 规则的prom_ql表达式见 models/alert_rule.go。与其他数据源类型的区别与 Prometheus 规则v1 格式把阈值写进prom_ql见 prometheus.md不同Host 规则的查询段不含任何 SQL/PromQL只做机器范围圈定这也是它被称为rather special的原因。六、结语Host 类型告警规则是 Nightingale 中监控机器在线状态的核心手段它通过queries按业务组 / 标签 / 主机名圈定范围triggerstarget_miss失联、pct_target_miss失联占比、offset时间偏移的简洁双段结构绕开数据源直接基于心跳上报数据进行判定。从源码models/alert_rule.go 的HostRuleConfig/GetHostsQuery、alert/eval/eval.go 的GetHostAnomalyPoint可以完整还原其判定链路这为手工编写规则、排查告警未触发原因以及让 AI Agent 按 datasources/host.md 模板生成规则提供了坚实依据。配套的 Linux 等组件规则包如 integrations/Linux/alerts/linux_by_categraf.json中也内置了 host 心跳类规则可作为现成参考。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nightingale Host 机器失联告警规则完全指南：queries / triggers 结构与源码级原理解析
Nightingale Host 机器失联告警规则完全指南queries / triggers 结构与源码级原理解析【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale导读本篇指南围绕 NightingaleN9E中一类特殊的告警规则——Host 机器监控告警规则展开完整讲解rule_config中queries机器筛选条件与triggers失联触发条件的字段语义、取值选项与完整可运行示例并结合仓库源码models/alert_rule.go、alert/eval/eval.go剖析机器失联失联比例时间偏移过大三类触发器的底层判定逻辑。读完本文你将能够独立编写、校验并理解 Host 类型告警规则也能通过 AI Agent 的create-alert-ruleSkill见 SKILL.md快速生成此类规则。一、Host 类型告警规则的定位它与其他数据源类型有何不同在 Nightingale 的告警规则体系中绝大多数规则Prometheus / Loki / ES / MySQL / TDengine 等都是查询某数据源中的指标或日志再对数值做阈值判断。而 Host 类型是相当特殊的一类prod固定为hostcate固定为host不需要指定datasource_ids数据源机器失联判断依据的不是某条时序数据而是机器向服务端上报心跳heartbeat的时间戳正如 SKILL.md 中强调的catehosthost-unreachable classdoes not need a data source。因此在用create_alert_rule工具创建 Host 规则时datasource_id可以省略见 SKILL.md 的参数表。该类型的 queries查询/筛选结构与 triggers触发结构与其他类型完全不同这是它在设计上最显著的特征。二、rule_config 结构queries triggers 双段式Host 规则的rule_config是一个由queries与triggers两个数组组成的 JSON 对象{ rule_config: { queries: [ { key: all_hosts, op: , values: [] } ], triggers: [ { type: target_miss, severity: 2, duration: 30 } ] } }从源码结构看该 JSON 与模型层定义一一对应。在 models/alert_rule.go 中定义了HostRuleConfigtype HostRuleConfig struct { Queries []HostQuery json:queries Triggers []HostTrigger json:triggers Inhibit bool json:inhibit }其中HostQuerymodels/alert_rule.go由key/op/values三个字段构成queries用于圈定被监控的机器范围HostTriggermodels/alert_rule.go由type/duration/percent/severity四个字段构成triggers用于定义失联的判定条件与告警级别。另外HostRuleConfig还含一个inhibit字段用于规则级抑制inhibit开关。2.1 queries 段如何圈定被监控的机器queries中的每个元素都是形如{key, op, values}的过滤条件对应模型层定义type HostQuery struct { Key string json:key Op string json:op Values []interface{} json:values }多条 query 之间是逻辑与AND关系即所有条件同时满足的机器才会进入告警判定范围。key 选项key含义values 示例all_hosts全部机器[]group_ids按业务组business group筛选[1, 2, 3]tags按标签筛选[envprod, regioncn]hosts按主机名ident筛选[web-01, web-02]这些 key 在底层会被转换为针对target表的过滤 SQL。以 models/alert_rule.go 的GetHostsQuery函数为证group_ids转换为target_busi_group.group_id in (?)之类的关联查询特殊地当 values 包含0时表示未归组的机器对应target_ident IS NULL分支代码中有详细注释说明依赖 LEFT JOIN 才能表达未归组语义tags时对tags与host_tags两列做like %tag%匹配!时生成tags not like ? and (host_tags not like ? or host_tags is null)hosts生成ident in (?)!生成ident not in (?)~/!~则把*通配符替换为 SQL 的%后执行ident like模糊匹配。op 选项op含义适用范围等于所有 key!不等于所有 key~正则匹配仅hostskey 支持底层实现为将*转成%的 like 匹配!~正则不匹配仅hostskey 支持2.2 triggers 段如何定义失联触发条件triggers中的每个元素都是形如{type, severity, duration}的触发条件HostTrigger结构体还额外包含百分比字段percenttype HostTrigger struct { Type string json:type Duration int json:duration Percent int json:percent Severity int json:severity }type 选项type含义额外字段target_miss机器失联未上报duration秒pct_target_miss失联机器占比超阈值duration秒percent百分比offset机器时间偏移过大duration秒2.3 三类触发器的源码级判定逻辑Host 规则的实际求值发生在 alert/eval/eval.go 的GetHostAnomalyPoint函数中。该函数把rule_config反序列化为models.HostRuleConfig随后遍历rule.Triggers按trigger.Type分派target_miss机器失联计算时间阈值t now - trigger.Duration从TargetsOfAlertRuleCache取出该规则覆盖的机器集合idents中心节点还会把 engineName 为空的不再上报机器并入集合通过TargetCache.GetHostUpdateTime(idents)拿到每台机器的最近上报时间凡是updateTime t的机器即被判为失联missTargets为每台失联机器生成异常点标签中注入identvalue 取now - target.BeatTime已失联秒数并携带trigger.Severity。pct_target_miss失联占比同样先取时间阈值与机器集合统计missTargets计算pct len(missTargets) / len(idents) * 100当pct trigger.Percent时整条规则才触发一个异常点value 即百分比。offset时间偏移过大通过TargetCache.GetHostMetas获取机器上报的元数据跳过CpuNum 0非 categraf 采集以及now-BeatTime 120非活跃机器的目标当|meta.Offset| trigger.Duration时判定该机器时间偏移异常value 取偏移量毫秒。由上述逻辑可以推断target_miss的duration语义是最后一次上报距今超过 N 秒pct_target_miss的percent语义是失联机器数占全部目标数的百分比阈值offset的duration则是允许的最大时间偏移毫秒级数值。三、完整示例机器失联告警可直接创建下面是创建一条机器失联告警规则的完整 JSON来自 host.md可直接用于create_alert_rule的rule_config_json或前端创建[{ name: Machine unreachable alert, note: Machine has not reported data for more than 60 seconds, prod: host, cate: host, datasource_ids: [], datasource_queries: [{match_type: 0, op: in, values: []}], disabled: 0, prom_eval_interval: 30, prom_for_duration: 0, rule_config: { queries: [{key: all_hosts, op: , values: []}], triggers: [{type: target_miss, severity: 1, duration: 60}] }, 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: [] }]关键字段说明name/note规则名称与告警内容描述prod: host、cate: host标识这是 Host 类型规则。模型层中HOST hostmodels/alert_rule.go且IsHostRule()按prod host判定见 models/alert_rule.go校验时 Host 规则使用type/duration/percent描述的 triggers 而不是 Prom 的prom_ql表达式见 models/alert_rule.go 的注释与校验分支datasource_ids: []留空即可Host 规则不依赖数据源rule_config.queriesall_hosts []表示监控全部机器如需限定范围可改为group_ids、tags或hostsrule_config.triggerstarget_missseverity: 1duration: 60表示机器超过 60 秒未上报数据即以 Critical1 级告警prom_eval_interval: 30规则评估周期 30 秒notify_recovered: 1恢复后发送恢复通知notify_repeat_step: 60重复告警间隔 60 秒。在 AI Agent 场景下这条规则对应create_alert_rule的通用路径Approach B Mode 2先read_file(basecreate-alert-rule, pathdatasources/host.md)获取结构模板再把rule_config对象序列化为 JSON 字符串传入rule_config_json详见 SKILL.md。四、常用场景速查queries 与 triggers 组合4.1 只监控指定业务组{ rule_config: { queries: [{key: group_ids, op: , values: [1, 2, 3]}], triggers: [{type: target_miss, severity: 2, duration: 120}] } }4.2 按标签圈定机器{ rule_config: { queries: [{key: tags, op: , values: [envprod, regioncn]}], triggers: [{type: target_miss, severity: 2, duration: 60}] } }4.3 按主机名 正则排除{ rule_config: { queries: [ {key: hosts, op: ~, values: [web-*]}, {key: hosts, op: !~, values: [web-99]} ], triggers: [{type: target_miss, severity: 2, duration: 90}] } }4.4 失联机器占比告警{ rule_config: { queries: [{key: all_hosts, op: , values: []}], triggers: [{type: pct_target_miss, severity: 2, duration: 300, percent: 50}] } }含义全部机器中失联超过 300 秒的数量占比达到 50% 时触发 Warning 告警判定逻辑见上文pct trigger.Percent的源码实现。4.5 机器时间偏移告警{ rule_config: { queries: [{key: all_hosts, op: , values: []}], triggers: [{type: offset, severity: 3, duration: 5000}] } }含义机器上报的时间偏移超过 5000毫秒量级时触发 Info 级告警。注意源码中会跳过CpuNum 0非 categraf 采集与不活跃机器因此该触发器面向由 categraf 采集上报的活跃目标。五、使用注意与边界无需数据源但需要机器接入上报Host 规则的判定完全依赖机器上报心跳后写入的target表数据上报时间戳、tags、host_tags、offset 等因此被监控机器必须已通过 categraf或等价 Agent接入 Nightingale 并持续上报。queries 多条为 AND 关系hosts ~ web-*与hosts !~ web-99同时使用时只有同时满足两条的机器才进入判定范围。~/!~仅支持hostskey对group_ids、tags使用正则运算符不会被支持请改用/!。group_ids传0表示未归组机器源码中专门处理了group_id0与业务组 ID 混合的场景见 models/alert_rule.go。校验差异Host 规则在模型层校验时走独立分支——isHost : ar.Prod HOST || ar.Cate HOST它要求的是type/duration/percent结构的 triggers而非 Prom 规则的prom_ql表达式见 models/alert_rule.go。与其他数据源类型的区别与 Prometheus 规则v1 格式把阈值写进prom_ql见 prometheus.md不同Host 规则的查询段不含任何 SQL/PromQL只做机器范围圈定这也是它被称为rather special的原因。六、结语Host 类型告警规则是 Nightingale 中监控机器在线状态的核心手段它通过queries按业务组 / 标签 / 主机名圈定范围triggerstarget_miss失联、pct_target_miss失联占比、offset时间偏移的简洁双段结构绕开数据源直接基于心跳上报数据进行判定。从源码models/alert_rule.go 的HostRuleConfig/GetHostsQuery、alert/eval/eval.go 的GetHostAnomalyPoint可以完整还原其判定链路这为手工编写规则、排查告警未触发原因以及让 AI Agent 按 datasources/host.md 模板生成规则提供了坚实依据。配套的 Linux 等组件规则包如 integrations/Linux/alerts/linux_by_categraf.json中也内置了 host 心跳类规则可作为现成参考。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考