RabbitMQ Monitoring with Nightingale: Scraping rabbitmq_prometheus Metrics via Categraf for 3.8+ and Legacy Versions

本文基于 Nightingale 仓库内 RabbitMQ 集成模块（integrations/RabbitMQ）的官方说明撰写。它讲解如何在 Nightingale 体系中完成 RabbitMQ 的指标采集、看板与告警闭环：对 RabbitMQ 3.8+ 推荐启用内置 rabbitmq_prometheus 插件并用 Categraf 的 Prometheus input 抓取 15692 端口；对低于 3.8 的旧版本则回退到 rabbitmq_management 插件 + Categraf input.rabbitmq 采集 15672 端口。读完本文，你将掌握两套采集方案的完整配置、仓库中 4 个内置看板与 6 条内置告警规则的用法，以及这些模板在 Nightingale 服务端如何被加载注册。

采集方案选型：两条链路，按版本二选一

RabbitMQ 从 3.8.0 起在发行版中内置了 Prometheus 指标采集支持，即 rabbitmq_prometheus 插件。该插件在独立 TCP 端口上以 Prometheus 文本格式暴露全部 RabbitMQ 指标，命名空间统一为 rabbitmq_*，可以直接对接任何 Prometheus 兼容的抓取端。

因此本集成给出两条链路：

版本	插件	端口	采集方式	使用的看板模板
RabbitMQ 3.8+	rabbitmq_prometheus（内置）	15692	Categraf input.prometheus	rabbitmq_v3.8_gt.json（含中文版 rabbitmq_CN_v3.8_gt.json）
RabbitMQ < 3.8	rabbitmq_management	15672	Categraf input.rabbitmq	rabbitmq_v3.8_lt.json / rabbitmq_by_categraf.json

关键提醒：两条链路的指标名并不相同（3.8+ 为 rabbitmq_process_*、rabbitmq_queue_messages_* 这类原生 Prometheus 指标，旧版则为 rabbitmq_node_*、rabbitmq_overview_* 这类管理插件风格指标），因此必须选择与版本匹配的看板，混用会导致面板无数据。

第一步：启用并验证 RabbitMQ 内置 Prometheus 插件

在 RabbitMQ 3.8+ 节点上执行：

rabbitmq-plugins enable rabbitmq_prometheus

插件默认监听 15692 端口。启用后先做一次冒烟验证，确认指标端点确实在工作：

curl -fsS http://127.0.0.1:15692/metrics | grep rabbitmq_build_info

rabbitmq_build_info 是版本相关的元指标（携带 rabbitmq_version、prometheus_plugin_version 等标签），也是后续集群节点计数、Erlang 分布链路告警（见下文告警规则）的依赖项。能抓到它即说明 Prometheus 插件已正常对外输出。

第二步：用 Categraf 的 Prometheus input 抓取指标

在运行 Categraf 的机器上新建 conf/input.prometheus/rabbitmq.toml（Nightingale 的采集端 Categraf 约定采集配置统一放在 conf/input.prometheus/ 目录下，一个组件一个 toml）：

interval = 15

[[instances]]
urls = ["http://127.0.0.1:15692/metrics"]
url_label_key = "instance"
url_label_value = "{{.Host}}"
labels = { job = "rabbitmq" }

各参数作用如下：

• interval = 15：抓取间隔（秒）。速率类指标（如发布/投递速率）的面板依赖该采样周期，间隔越小数据越平滑，但会增大 Prometheus 与 RabbitMQ 的负载；默认值 15s 是官方模板验证过的取值。
• urls：Prometheus 指标端点列表。支持一次配置多个 URL（多节点/多集群场景下会各自生成一条序列）。
• url_label_key / url_label_value：为每个抓取目标附加"目标标识"标签。{{.Host}} 是 Categraf 的模板变量，运行时被替换为目标 URL 的主机部分，用于在多节点抓取时区分不同 RabbitMQ 节点；instance 标签键与 Prometheus 惯例一致。
• labels = { job = "rabbitmq" }：为所有抓取到的指标附加静态标签，job 标签用于标识采集任务来源，方便在 Nightingale 查询与看板中按 job 过滤。

保存并重启 Categraf 后，即可在 Nightingale 的 Prometheus 数据源中查询 rabbitmq_build_info 等指标验证链路连通。

第三步：按版本选择看板模板

仓库 integrations/RabbitMQ/dashboards 下提供 4 个可直接导入 Nightingale 的看板：

文件	看板名称	适用版本	说明
rabbitmq_v3.8_gt.json	RabbitMQ 3.8+	≥ 3.8	基于内置 Prometheus 指标验证，英文面板
rabbitmq_CN_v3.8_gt.json	RabbitMQ 3.8+ 中文版	≥ 3.8	同上，中文面板
rabbitmq_v3.8_lt.json	RabbitMQ 3.8-	< 3.8	匹配 input.rabbitmq 采集的旧版指标
rabbitmq_by_categraf.json	RabbitMQ 3.8	旧版	同样面向 Categraf rabbitmq 输入

3.8+ 看板的面板构成与核心指标

从 rabbitmq_v3.8_gt.json 的 JSON 内容看，看板按 Overview / CHANNELS / CONNECTIONS / QUEUES / INCOMING MESSAGES / OUTGOING MESSAGES / QUEUED MESSAGES 等分组组织面板，覆盖三类信息：

• 资源水位：rabbitmq_process_open_fds 与 rabbitmq_process_max_fds（文件描述符）、rabbitmq_process_open_tcp_sockets 与 rabbitmq_process_max_tcp_sockets（TCP 套接字）、rabbitmq_process_resident_memory_bytes（驻留内存）、rabbitmq_disk_space_available_bytes（可用磁盘），以及发布者阻塞阈值相关面板（内存/磁盘 watermark 前的剩余可用量）。
• 连接与通道：rabbitmq_connections（总连接数）、rabbitmq_channels（通道数）、rabbitmq_connections_opened_total / rabbitmq_connections_closed_total（连接开/闭速率）、rabbitmq_channels_opened_total / rabbitmq_channels_closed_total（通道开/闭速率）。
• 消息流转（吞吐、积压与确认）：rabbitmq_channel_messages_published_total（发布速率）、rabbitmq_channel_messages_delivered_total（投递速率）、rabbitmq_channel_messages_acked_total（确认速率）、rabbitmq_channel_messages_redelivered_total（重投递速率）、rabbitmq_channel_messages_unroutable_dropped_total 与 rabbitmq_channel_messages_unroutable_returned_total（不可路由丢弃/退回速率）、rabbitmq_queue_messages_ready（待消费消息）、rabbitmq_queue_messages_unacked（待确认消息）、rabbitmq_queue_messages_published_total（入队速率）、rabbitmq_queues / rabbitmq_queues_declared_total / rabbitmq_queues_created_total / rabbitmq_queues_deleted_total（队列数与生命周期速率）。

官方说明特别强调：3.8/3.8+ 模板是按内置 Prometheus 指标验证的。在检查吞吐（rate）、积压（backlog）和确认（ack）相关面板之前，应当先创建真实的 exchange 和 queue，并实际执行 publish/consume 操作，否则这些面板将长时间处于零值或空数据状态，容易被误判为采集故障。

旧版看板的指标差异

rabbitmq_v3.8_lt.json 面向 < 3.8 的管理插件指标链路，其指标风格与 3.8+ 明显不同：节点级指标为 rabbitmq_node_*（如 rabbitmq_node_fd_used、rabbitmq_node_mem_limit、rabbitmq_node_disk_free、rabbitmq_node_sockets_used、rabbitmq_node_uptime），集群概览为 rabbitmq_overview_*（如 rabbitmq_overview_connections、rabbitmq_overview_channels、rabbitmq_overview_queues、rabbitmq_overview_messages_delivered），队列级为 rabbitmq_queue_*（如 rabbitmq_queue_messages_ready、rabbitmq_queue_messages_unack、rabbitmq_queue_messages_publish）。这正是两套模板必须严格按版本选用、不可混用的根本原因。

旧版本（< 3.8）的替代采集：Categraf input.rabbitmq

对于 3.8 之前的 RabbitMQ，无法使用内置 Prometheus 插件，此时启用管理插件并让 Categraf 的 input.rabbitmq 访问默认管理端口 15672：

rabbitmq-plugins enable rabbitmq_management

仓库内 integrations/RabbitMQ/collect/rabbitmq/rabbitmq.toml 给出了该输入的完整可参考配置（默认全部注释，按需放开）：

# collect interval
# interval = 15

[[instances]]
# Management Plugin url
# url = "http://localhost:15672"
# username = "guest"
# password = "guest"

## Optional TLS Config
# use_tls = false
# tls_min_version = "1.2"
# tls_ca = "/etc/categraf/ca.pem"
# tls_cert = "/etc/categraf/cert.pem"
# tls_key = "/etc/categraf/key.pem"
## Use TLS but skip chain & host verification
# insecure_skip_verify = true

## Optional request timeouts
# header_timeout = "3s"
# client_timeout = "4s"

## A list of nodes to gather as the rabbitmq_node measurement.
# nodes = ["rabbit@node1", "rabbit@node2"]

## A list of exchanges to gather as the rabbitmq_exchange measurement.
# exchanges = ["categraf"]

## Metrics to include and exclude. Globs accepted.
## Supported: "exchange", "federation", "node", "overview", "queue"
# metric_include = []
# metric_exclude = []

## Queues to include and exclude. Globs accepted.
# queue_name_include = []
# queue_name_exclude = []

## Federation upstreams to include and exclude, array of glob patterns.
# federation_upstream_include = []
# federation_upstream_exclude = []

# interval = global.interval * interval_times
# interval_times = 1

# important! use global unique string to specify instance
# labels = { instance="rabbitmq-001" }

要点说明：

• 认证：url 指向管理插件端口 15672，默认账号 guest/guest 只能在本机使用，远程采集务必配置具备监控权限的专用账号。
• TLS：启用 use_tls 后可配合 tls_min_version、tls_ca、tls_cert、tls_key 配置双向/单向 TLS；insecure_skip_verify 仅建议在测试环境使用。
• 超时：header_timeout（等待响应头的时长）与 client_timeout（单次请求总时限）用于避免采集端被慢接口拖死。
• 采集范围裁剪：nodes、exchanges、queue_name_include/exclude、metric_include/exclude（支持的指标类别为 exchange、federation、node、overview、queue）以及 federation_upstream_include/exclude 均可按 glob 模式收敛采集范围——节点多、队列多时务必按需裁剪，否则管理接口压力会随队列数线性增长。
• 采集频率与实例标识：interval_times 以全局 interval 为基数放大间隔；labels = { instance="rabbitmq-001" } 用于为每套被采集实例打上全局唯一的 instance 标识，是 Nightingale 侧区分多套 RabbitMQ 的关键。

该文件头部注释还明确指出（与 README 结论一致）：自 3.8.0 起 RabbitMQ 自带 Prometheus/Grafana 支持，rabbitmq_prometheus 插件在专用端口暴露全部指标，应优先用 Categraf 的 prometheus 插件抓取 15692，而不是继续用本 rabbitmq 输入——即 input.rabbitmq 仅作为旧版兼容通道保留。

内置告警规则：开箱即用的 6 条 PromQL

仓库 integrations/RabbitMQ/alerts/alerts.json 预置了 6 条告警规则，全部基于 3.8+ 的 Prometheus 指标编写，类别为 prometheus，且默认处于 disabled（"disabled": 1）状态，导入后需按需启用：

规则名称	PromQL 核心逻辑	告警含义
File Descriptors Near Limit	sum(max_over_time(rabbitmq_process_open_fds[5m])) / sum(rabbitmq_process_max_fds) > 0.8	5 分钟窗口内打开的文件描述符峰值超过上限的 80%
TCP Sockets Near Limit	sum(max_over_time(rabbitmq_process_open_tcp_sockets[5m])) / sum(rabbitmq_process_max_tcp_sockets) > 0.8	TCP 套接字占用接近上限，新连接可能被拒绝
High Connection Churn	(sum(rate(rabbitmq_connections_closed_total[5m])) + sum(rate(rabbitmq_connections_opened_total[5m]))) / sum(rabbitmq_connections) > 0.1 unless sum(rabbitmq_connections) < 100	连接开/闭速率之和占当前连接数比例过高（连接数小于 100 时豁免），典型于客户端频繁重连
Insufficient Established Erlang Distribution Links	count(erlang_vm_dist_node_state) < count(rabbitmq_build_info) * (count(rabbitmq_build_info) - 1)	已建立的 Erlang 分布链路数少于节点两两组合数，集群可能存在失联节点
Low Disk Watermark Predicted	predict_linear(rabbitmq_disk_space_available_bytes[24h], 60*60*24) < rabbitmq_disk_space_available_limit_bytes（叠加 count_over_time(...offset 22h) > 0 排除数据不足场景）	按过去 24h 线性外推，24 小时后可用磁盘将低于 watermark
Unroutable Messages	sum(increase(rabbitmq_channel_messages_unroutable_dropped_total[5m])) >= 1 or sum(increase(rabbitmq_channel_messages_unroutable_returned_total[5m])) >= 1	5 分钟内出现丢弃或退回的不可路由消息

每条规则的 annotations.action 字段都附带了可操作的排查步骤（英文文案见 integrations/RabbitMQ/i18n/en_US.json），例如：文件描述符告警建议用 rabbitmq-diagnostics status 对比 file_descriptors 的 total_used 与 total_limit、检查 LimitNOFILE/ulimit；磁盘预测告警建议用 rabbitmqctl list_queues name messages message_bytes 定位堆积队列后先恢复消费止血；不可路由告警建议核对 list_bindings 绑定关系、配置 alternate-exchange 兜底并开启生产端 mandatory 标志处理 Basic.Return。这些动作文本可以直接作为告警通知中的处置指引。

这些模板在 Nightingale 服务端如何生效

RabbitMQ 集成与仓库中其他集成模块一样，遵循 Nightingale 的"integration 目录约定"：每个组件目录下固定有 dashboards/（看板 JSON）、alerts/（告警 JSON）、markdown/（README 及语言副本）、i18n/（词条表）、icon/（图标）、可选的 collect/（采集配置样例）与 metrics/（内置指标定义）。

服务端启动时，center/integration/init.go 的 Init 函数会遍历 integrations 目录（默认 runner.Cwd/integrations，可配置 disable_integration_init 关闭）：

• 读取每个组件的 markdown/ 目录，将 README.md 写入 builtin_component 表，并把 README.<lang>.md 语言副本按语言码归一化后放入内存，随请求头 X-Language 按回退链返回（见 Readme 与 PickReadmeFiles 逻辑）；
• 解析 dashboards/*.json 与 alerts/*.json，灌入 builtin_payloads 表（类型分别为 dashboard 与 alert），并借助组件 i18n/ 词条表渲染其他语言变体（AddBuiltinPayload → renderVariant）；
• 解析 metrics/ 下的指标定义构建 builtin_metrics 缓存，支持按 collector/type/query 过滤与语言翻译（BuiltinMetricGets）。

也就是说，用户既可以在前端"集成中心"直接浏览/导入 RabbitMQ 的内置看板与告警，也可以直接用仓库中的 JSON 文件手工导入，两条路径得到的是同一批经过校验的模板。

实践清单：从零接入 RabbitMQ 到 Nightingale

1. 启用插件：3.8+ 节点执行 rabbitmq-plugins enable rabbitmq_prometheus，并用 curl -fsS http://127.0.0.1:15692/metrics | grep rabbitmq_build_info 验证；旧版执行 rabbitmq-plugins enable rabbitmq_management。
2. 配置采集：3.8+ 新建 conf/input.prometheus/rabbitmq.toml（含 urls、url_label_key、url_label_value、labels）；旧版配置 input.rabbitmq（含 url、username、password 及可选的 TLS、超时、范围裁剪参数）。
3. 准备业务流量：创建真实的 exchange 与 queue，执行 publish/consume，再查看吞吐、积压与确认面板，避免误判空面板。
4. 导入看板：3.8+ 用 rabbitmq_v3.8_gt.json（或中文版 rabbitmq_CN_v3.8_gt.json）；旧版用 rabbitmq_v3.8_lt.json / rabbitmq_by_categraf.json，切勿混用。
5. 启用告警：从 alerts.json 导入 6 条规则并按环境启用，重点覆盖文件描述符、TCP 套接字、连接抖动、磁盘水位预测、集群链路与不可路由消息六类典型故障。