用 Categraf 全面采集 Consul 健康检查与集群状态Nightingale 监控体系中的 Consul Input Plugin 实战指南【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale导读本文围绕 Nightingale 开源可观测性平台配套采集器 Categraf 的 Consul 输入插件展开讲解如何采集 Consul 集群中注册的全部健康检查状态、Raft/Serf 集群视图、Catalog 服务目录与 KV 键值数据并上报至 Nightingale 服务端。读完本文你将掌握 Consul 插件的完整配置参数、全部输出指标语义、基于真实告警模板的接入方式以及数据落库后需要避开的同名样本覆盖等实战陷阱。Consul 插件在 Categraf 采集体系中的定位Consul 是业界广泛使用的服务发现与 KV 存储组件其健康检查Health Checks机制直接反映了注册服务的可用性。Categraf 的 Consul 输入插件Input Plugin专门负责收集 Consul 中注册的所有健康检查统计信息通过 Consul HTTP API 查询数据。需要特别说明的是该插件不采集 Consul 的 telemetry 指标如内存、GC、Raft 提交耗时等运行时指标。正如 integrations/Consul/markdown/README.md 所强调的如果确实需要这些数据Consul 本身已经支持通过 StatsD 协议输出 telemetry无需本插件重复采集。插件聚焦于服务健康状态 集群成员视图 目录服务数量 选中的 KV 键值这一组对监控告警最有价值的数据面。从仓库结构看integrations/目录下每个组件目录都是Categraf 配置语法和指标命名的权威 ground truth。在 aiagent/tools/integrations_loader.go 的注释中明确写道该目录下每个组件的markdown/README.md和collect/*/*.toml会被加载进文档索引供 AI Agent 的search_n9e_docs检索——这也意味着本插件文档与配置本身就是 Categraf 用户和 Agent 的双重参考基准。Consul 组件目录与同类插件保持一致的四件套布局integrations/Consul/ ├── alerts/consul_by_categraf.json # 随插件附赠的 7 条告警规则模板 ├── collect/consul/consul.toml # 插件采集配置 ├── i18n/en_US.json # 告警文案国际化 ├── icon/consul.png # 组件图标 └── markdown/README.md # 插件说明文档启用与基础配置Consul 插件作为 Categraf 的一个实例型插件[[instances]]启用方式与 Categraf 其他插件完全一致将 integrations/Consul/collect/consul/consul.toml 放入 Categraf 的采集配置目录调整address指向你的 Consul 服务端即可。完整配置模板以下为仓库内附带的完整配置相比插件文档collect目录下的配置还额外暴露了allow_stale、require_consistent、kv_prefix、kv_filter四个高阶参数# # collect interval # interval 15 [[instances]] ## Consul server address # address localhost:8500 ## URI scheme for the Consul server, one of http, https # scheme http ## ACL token used in every request # token ## HTTP Basic Authentication username and password. # username # password ## Data center to query the health checks from # datacenter ## Allows any Consul server (non-leader) to service a read. ## Default is true # allow_stale true ## Forces the read to be fully consistent. ## Default is false # require_consistent false ## Prefix from which to expose key/value pairs. # kv_prefix ## Regex that determines which keys to expose. ## Default is .* # kv_filter .* ## Optional TLS Config # tls_ca /etc/telegraf/ca.pem # tls_cert /etc/telegraf/cert.pem # tls_key /etc/telegraf/key.pem ## Use TLS but skip chain host verification # insecure_skip_verify true关键参数逐项说明参数默认值说明addresslocalhost:8500Consul 服务端地址支持 IP 或域名加端口schemehttp访问 Consul 的 URI scheme仅支持http、https两种取值启用 HTTPS 时配合下方 TLS 配置使用token空每次请求携带的 ACL Token用于访问被 ACL 保护的 Consul 集群权限不足时 API 会返回 403这在排查实例不可达告警时是首要怀疑点username/password空HTTP Basic Auth 认证凭据适用于 Consul 前置了认证代理的场景datacenter空要查询健康检查的 Data Center多 DC 部署时指定否则使用默认 DCallow_staletrue允许任意 Consul 节点非 Leader直接响应读请求牺牲极小的强一致性换取高可用与低延迟require_consistentfalse强制读请求完全一致走 Raft 多数派确认在需要绝对精确读的场景开启会明显增加延迟通常不建议kv_prefix空从该前缀开始暴露 KV 键值对留空则默认不采集 KVkv_filter.*决定暴露哪些键的正则表达式仅对匹配到的键采集非数值的键会被自动忽略tls_ca/tls_cert/tls_key空TLS 客户端证书三件套scheme https时生效insecure_skip_verifyfalse跳过证书链与主机名校验仅用于内部测试网络生产不建议开启interval全局采集间隔本实例独立的采集周期单位为秒例如15表示每 15 秒采集一次指标体系详解插件每次采集会输出以下指标括号内为完整语义指标名含义consul_up上次对 Consul 的查询是否成功成功为 1consul_scrape_use_seconds本次抓取消耗的秒数consul_raft_peersRaft 集群中的 peerserver数量consul_raft_leader该节点视角下 Raft 集群是否有 Leader有则为 1consul_serf_lan_members集群 LAN gossip 中的成员数量consul_serf_lan_member_status成员在集群中的状态1Alive2Leaving3Left4Failedconsul_serf_wan_member_status成员在 WAN gossip 集群中的状态取值同上consul_catalog_services集群中注册的服务数量consul_service_tag服务的标签tagconsul_health_node_status与某节点关联的健康检查状态consul_health_service_status与某服务关联的健康检查状态consul_service_checks将 service id 与 check name 关联起来的指标consul_catalog_kvKV 目录中选中键的值非数值的键会被自动省略此外还有一批名称不固定的指标它们来自 Consul Agent 自身的指标接口Agent Metrics可在 Consul 官方文档的 View Metrics 一节查看完整清单。这类指标与上述固定指标的区别在于插件文档只保证consul_*固定指标的存在Agent 指标则随 Consul 版本、启用模块不同而变化。示例输出以下是插件在本地 Consul 实例localhost:8500agent hostname 为hostname上的真实输出形态从中可以直观看到标签结构consul_up addresslocalhost:8500 agent_hostnamehostname 1 consul_scrape_use_seconds addresslocalhost:8500 agent_hostnamehostname 0.015674053 consul_raft_peers addresslocalhost:8500 agent_hostnamehostname 1 consul_raft_leader addresslocalhost:8500 agent_hostnamehostname 1 consul_serf_lan_members addresslocalhost:8500 agent_hostnamehostname 1 consul_serf_lan_member_status addresslocalhost:8500 agent_hostnamehostname memberlocalhost.localdomain 1 consul_serf_wan_member_status addresslocalhost:8500 agent_hostnamehostname dcdc1 memberlocalhost.localdomain.dc1 1 consul_catalog_services addresslocalhost:8500 agent_hostnamehostname 1 consul_health_node_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain statuspassing 1 consul_health_node_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain statuswarning 0 consul_health_node_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain statuscritical 0 consul_health_node_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain statusmaintenance 0 consul_health_service_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain service_iddemo service_namedemo statuspassing 1 consul_health_service_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain service_iddemo service_namedemo statuswarning 0 consul_health_service_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain service_iddemo service_namedemo statuscritical 0 consul_health_service_status addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain service_iddemo service_namedemo statusmaintenance 0 consul_service_checks addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain service_iddemo service_namedemo statuscritical 1 consul_service_tag addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain service_iddemo service_namedemo tagtag1 1 consul_service_tag addresslocalhost:8500 agent_hostnamehostname check_idservice:demo check_nameService demo check nodelocalhost.localdomain service_iddemo service_namedemo tagtag2 1解读要点每个指标都携带address与agent_hostname两个公共标签用于区分采集来源与 Consul 实例。consul_health_node_status与consul_health_service_status是多值设计同一条健康检查会按passing、warning、critical、maintenance四种状态各输出一行且指标名与标签集合完全相同、仅status标签值不同当前命中的状态值为 1其余为 0。这为后文同名样本覆盖陷阱埋下了伏笔。consul_service_tag每行携带一个tag标签同一服务有多个 tag 时会输出多行。consul_serf_wan_member_status额外携带dc标签用于区分 WAN 集群中的数据中心。KV 类指标consul_catalog_kv只有在配置了kv_prefix后才会出现且仅保留数值型键值。开箱即用的告警规则模板仓库为 Consul 插件配套提供了一套完整的 PromQL 告警规则模板 integrations/Consul/alerts/consul_by_categraf.json可直接导入 Nightingale 告警规则中心使用。规则覆盖了 Consul 集群最核心的 7 个故障场景规则名称核心 PromQL严重级别Consul 实例不可达consul_up 01严重Consul 集群没有 Leaderconsul_raft_leader 01严重Consul Autopilot 判定集群不健康consul_autopilot_healthy 01严重Consul 集群容错度归零consul_autopilot_failure_tolerance 02重要Consul 服务健康检查 criticalcount by (address, node, service_name, check_name) (consul_health_service_status{statuscritical}) 02重要Consul 节点健康检查 criticalcount by (address, node, check_name) (consul_health_node_status{statuscritical}) 02重要Consul 集群成员失联consul_serf_lan_member_status ! 12重要其中前四条规则还引用了consul_autopilot_healthy、consul_autopilot_failure_tolerance等 Agent 侧指标——这些正是上文提到的名称不固定指标依赖 Consul Agent 指标接口输出导入时请确认你的 Consul 版本提供了对应指标。模板中每条规则都带有action注解运行手册描述了标准故障处置动作例如Consul 集群没有 Leader的处置流程为先在每台 server 上执行consul operator raft list-peers确认存活 server 数是否仍构成多数派存活数不足时优先拉起宕机节点恢复仲裁存活数足够但仍选不出主时检查 server 间 8300/8301 端口连通性与时钟偏差chronyc tracking最后才考虑按官方 outage recovery 流程用raft/peers.json手工重建 peer 列表。配套的 integrations/Consul/i18n/en_US.json 提供了这些告警名称与处置文案的英文对照便于国际化告警渠道展示。实战要点同名样本覆盖陷阱与规避这是 Consul 插件落地时最容易踩的坑仓库在告警模板的注释中做了专门说明见 consul_by_categraf.json 中Consul 服务健康检查 critical规则的note字段categraf 对同一条检查会按 passing/warning/critical/maintenance 各推一个同名同标签的样本落库后数值会互相覆盖因此这里用 status 标签的存在性判断而不是比较数值。翻译成白话由于四种状态的样本指标名和标签完全相同在时序数据库中它们会落到同一个序列后写入的值覆盖先写入的值。因此在 PromQL 中直接写consul_health_service_status{statuscritical} 1是不可靠的——这个值很可能已被同一采集周期的passing1样本覆盖成 1导致误报或漏报。仓库给出的正确做法是利用标签存在性判断count by (address, node, service_name, check_name) (consul_health_service_status{statuscritical}) 0。只要该状态标签存在即视为命中而不是比较数值大小。这一点与consul_serf_lan_member_status这类一个样本一个状态值的指标可安全使用! 1判断失联形成鲜明对比写告警时务必区分。与 Prometheus 插件的协同与边界在 Categraf 插件体系中Consul 插件与 integrations/Prometheus/markdown/README.md 所描述的 prometheus 插件分工明确Consul 插件负责采集 Consul 自身的健康状态与集群视图prometheus 插件则负责抓取各类 exporter 暴露的/metrics数据。值得注意的是prometheus 插件fork 自 telegraf/prometheus 并做了删减改造同样支持基于 Consul 做服务发现来管理抓取目标地址这意味着同一套 Consul 集群可以同时扮演被监控对象与服务发现源两个角色。如果需要在 Nightingale 中同时纳管 Consul 集群的自身状态与 Consul 上注册服务的业务指标推荐组合Consul 插件本插件采集集群健康 prometheus 插件配合 Consul 服务发现抓取服务 metrics两类数据汇入同一套告警规则体系即可形成完整的 Consul 可观测闭环。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考