news 2026/9/23 4:01:06

用 Grafana 监控 RabbitMQ Stream：RabbitMQ-Stream 仪表盘部署与指标解读实战

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
用 Grafana 监控 RabbitMQ Stream：RabbitMQ-Stream 仪表盘部署与指标解读实战

用 Grafana 监控 RabbitMQ Stream：RabbitMQ-Stream 仪表盘部署与指标解读实战

【免费下载链接】rabbitmq-serverOpen source RabbitMQ: core server and tier 1 (built-in) plugins项目地址: https://gitcode.com/gh_mirrors/ra/rabbitmq-server

Stream 协议自 RabbitMQ 3.9.0 引入，配合 Stream（流）这种持久化、可复制的 append-only 日志数据结构使用，成为事件溯源、日志收集等场景的核心能力。本文基于 rabbitmq-server 仓库中 RabbitMQ-Stream 仪表盘说明文档 及其配套的 RabbitMQ-Stream.json 仪表盘定义，讲解该官方 Grafana 仪表盘展示的每一项指标、其底层 PromQL 查询与对应源码实现，并给出从插件启用到仪表盘导入的完整部署步骤，读完即可独立搭建一套 RabbitMQ Stream 的可观测性面板。

Stream 协议与 Streams 是什么

在进入监控面板之前，先明确被监控的对象。Stream 协议是 RabbitMQ 在 3.9.0 版本中引入的一种基于二进制帧的协议，专用于与 Streams（流）配合使用。Streams 是一种新的持久化、可复制的数据结构，它建模了一个只追加（append-only）的日志，消息只能追加到末尾，消费过程不会破坏数据，即所谓"非破坏性消费（non-destructive consumer semantics）"——消费者可以反复、从任意偏移量重新读取同一段历史消息，这与经典队列"消费即删除"的语义有本质区别。

在该仓库中，Stream 协议的实现在 deps/rabbitmq_stream 插件内，核心进程包括负责协议帧解析与连接处理的 rabbit_stream_reader.erl，以及专门负责生产者/消费者指标采集的 rabbit_stream_metrics.erl。仪表盘文档中给出了三篇官方博客（Streams Overview、First Application with Streams、Connecting to Streams）作为扩展阅读，帮助你理解协议如何连接、发布与订阅。

仪表盘能看什么：六类核心指标总览

RabbitMQ-Stream 仪表盘（Grafana 面板 ID 14798）聚焦于 Stream 协议的消息速率与错误统计，文档明确列出的指标共六项：

指标面板类型含义
Stream publishersStat + Pie + Time series当前 Stream 生产者数量
Stream messages received / sStat + Pie + Time series每秒接收（写入）的消息数
Stream messages confirmed to publishers / sStat + Pie + Time series每秒确认给生产者的消息数
Stream consumersStat + Pie + Time series当前 Stream 消费者数量
Stream messages delivered / sStat + Pie + Time series每秒投递给消费者的消息数
Errors since bootStat + Time series节点启动以来累计的 Stream 协议错误数

仪表盘 JSON 的description字段写的是 "Stream protocol message rates and errors"，即"Stream 协议消息速率与错误"，与文档描述完全一致。六项指标在面板布局上采用三层结构：

  1. 第一行（Stat 数字面板）：六个指标各占一格，以背景色块 + 大数字形式展示当前值；
  2. 第二行（Pie 饼图 + Learn more 文本面板）：前五个指标各配一个饼图，按节点（rabbitmq_node）展示分布占比，最后一个格子是 Learn more 链接面板；
  3. 第三、四行（Time series 时序面板）：前五个指标与 Errors since boot 各自呈现为随时间变化的曲线，图例表格给出 mean/max/min/last 统计值。

指标背后的 PromQL：读懂每一个查询表达式

仪表盘的全部数据来源于rabbitmq-prometheus插件暴露的 Prometheus 指标。下面的表达式全部来自 RabbitMQ-Stream.json，理解它们有助于你按需改造面板。

连接标识指标：rabbitmq_identity_info

几乎所有查询都通过on(instance, job) group_left(rabbitmq_cluster, rabbitmq_node) rabbitmq_identity_info{...}这段模式，把instance/job标签映射到集群名与节点名，实现按集群聚合。筛选条件里出现的$namespace、$rabbitmq_cluster、$endpoint都是仪表盘顶部定义的模板变量（详见下文"过滤器"一节）。

生产与消费速率

Stat 面板和 Time series 面板中的速率指标使用irate()计算每秒瞬时速率，如接收速率：

sum by(rabbitmq_cluster) ( irate(rabbitmq_global_messages_received_total{protocol="stream"}[$__rate_interval]) * on(instance, job) group_left(rabbitmq_cluster, rabbitmq_node) rabbitmq_identity_info{rabbitmq_cluster="$rabbitmq_cluster", namespace="$namespace", rabbitmq_endpoint="$endpoint"} )

对应的确认速率使用rabbitmq_global_messages_confirmed_total{protocol="stream"}，投递速率使用rabbitmq_global_messages_delivered_total{protocol="stream"}，三者均以protocol="stream"标签精确筛选 Stream 协议流量，与 AMQP 等其他协议的流量互不干扰。

生产与消费连接数

生产者数量与消费者数量是瞬时量（gauge），不需要irate，直接查询：

sum by(rabbitmq_cluster) ( rabbitmq_global_publishers{protocol="stream"} * on(instance, job) group_left(rabbitmq_cluster, rabbitmq_node) rabbitmq_identity_info{rabbitmq_cluster="$rabbitmq_cluster", namespace="$namespace", rabbitmq_endpoint="$endpoint"} )

消费者数量同理，使用rabbitmq_global_consumers{protocol="stream"}。

这些全局计数指标的写入源头在 rabbit_stream_metrics.erl：每当一个 Stream 消费者建立时调用rabbit_global_counters:consumer_created(stream)，取消时调用consumer_deleted(stream)（见该文件的consumer_created/10与consumer_cancelled/4）；生产者建立与删除则分别调用publisher_created(stream)与publisher_deleted(stream)。同时该模块还会把消费者的 credits、offset、offset_lag、active 状态等写入 ETS 表并同步到rabbit_core_metrics，为管理 UI 和 per-object 指标提供数据。可以推断，rabbitmq_global_*系列指标正是由rabbit_global_counters模块按协议维度累加后，再由rabbitmq-prometheus插件以protocol标签导出的。

Errors since boot：14 类 Stream 错误码的累计值

这是仪表盘中最复杂的一组查询。Stat 面板把 14 个_total计数器相加得到总错误数，而 Time series 面板（面板 id 23）则逐条列出每一种错误类型，图例格式分别为：

  • access_refused：rabbitmq_global_stream_error_access_refused_total
  • error_authentication_failure：rabbitmq_global_stream_error_authentication_failure_total
  • frame_too_large：rabbitmq_global_stream_error_frame_too_large_total
  • internal_error：rabbitmq_global_stream_error_internal_error_total
  • precondition_failed：rabbitmq_global_stream_error_precondition_failed_total
  • publisher_does_not_exist：rabbitmq_global_stream_error_publisher_does_not_exist_total
  • sasl_authentication_failure_loopback：rabbitmq_global_stream_error_sasl_authentication_failure_loopback_total
  • sasl_challenge：rabbitmq_global_stream_error_sasl_challenge_total
  • sasl_error：rabbitmq_global_stream_error_sasl_error_total
  • sasl_mechanism_not_supported：rabbitmq_global_stream_error_sasl_mechanism_not_supported_total
  • stream_already_exists：rabbitmq_global_stream_error_stream_already_exists_total
  • stream_does_not_exist：rabbitmq_global_stream_error_stream_does_not_exist_total
  • stream_not_available：rabbitmq_global_stream_error_stream_not_available_total
  • subscription_id_already_exists：rabbitmq_global_stream_error_subscription_id_already_exists_total
  • subscription_id_does_not_exist：rabbitmq_global_stream_error_subscription_id_does_not_exist_total
  • error_unknown_frame：rabbitmq_global_stream_error_unknown_frame_total
  • vhost_access_failure：rabbitmq_global_stream_error_vhost_access_failure_total

这些错误码覆盖了 Stream 协议帧层面的常见故障：帧过大（frame_too_large）、未知帧（unknown_frame）、订阅 ID 冲突或不存在、Stream 不存在/不可用/已存在、SASL 认证相关的多种失败，以及 vhost 或资源访问被拒。生产实践中，当Errors since boot持续上升时，可以直接在该面板上按图例定位到具体错误类型，再结合rabbitmq_stream插件日志排查（例如 SASL 认证类错误往往指向客户端凭证配置问题，stream_not_available通常与目标节点故障或迁移有关）。

过滤器与模板变量：Namespace 与 RabbitMQ Cluster

仪表盘提供两个用户可见的下拉过滤器（文档 "Filter by" 一节），外加一个隐藏的 Endpoint 变量，它们由 RabbitMQ-Stream.json 末尾的templating段定义：

  • Namespace（变量名namespace）：查询label_values(rabbitmq_identity_info, namespace)，从数据中动态列出所有命名空间。命名空间是 RabbitMQ Prometheus 指标在 Kubernetes 等多集群部署场景下的分组维度。
  • RabbitMQ Cluster（变量名rabbitmq_cluster）：查询label_values(rabbitmq_identity_info{namespace="$namespace"}, rabbitmq_cluster)，随 Namespace 的选择联动，列出该命名空间下的集群。
  • Endpoint（变量名endpoint，默认隐藏）：label_values(rabbitmq_identity_info{namespace="$namespace", rabbitmq_cluster="$rabbitmq_cluster", rabbitmq_endpoint!="memory-breakdown"},rabbitmq_endpoint)，用于排除memory-breakdown等细分端点，保证查询落到默认的聚合指标端点。

所有面板查询都会引用这三个变量做联合筛选，因此切换 Namespace 或 Cluster 时，整块仪表盘会立即联动刷新——这正是该仪表盘适合多集群统一监控的原因。

部署前提：两个必须启用的插件

文档 "Requires" 一节明确了使用该仪表盘的前置条件：

  1. rabbitmq-stream插件必须启用：提供 Stream 协议端点与流存储能力（实现于 deps/rabbitmq_stream）。在 RabbitMQ 3.9.0 及以后版本中，该插件随发行版内置。
  2. rabbitmq-prometheus插件必须启用：提供 Prometheus 指标抓取端点。启用方式在 deps/rabbitmq_prometheus/README.md 中有明确说明：
rabbitmq-plugins enable rabbitmq_prometheus rabbitmq-plugins enable rabbitmq_stream

rabbitmq-prometheus插件默认监听15692端口，指标路径为/metrics，可用 curl 验证：

curl -v -H "Accept:text/plain" "http://localhost:15692/metrics"

若在聚合指标中按协议区分流量，可以看到形如rabbitmq_global_messages_received_total{protocol="stream"}的序列；rabbitmq-stream插件的流监听端口（默认5552，可通过stream.tcp.port配置）则用于客户端接入。

动手部署：三步导入官方仪表盘

仓库在 deps/rabbitmq_prometheus/docker/grafana/dashboards 下存放了全部官方仪表盘 JSON，其中 RabbitMQ-Stream 对应 RabbitMQ-Stream.json。导入方式有两种：

方式一：docker-compose 一键拉起完整监控栈（推荐用于试用）

仓库提供了 docker-compose-metrics.yml，包含 Grafana 8.3.4、Prometheus v2.53.3、node-exporter 与 cadvisor。在deps/rabbitmq_prometheus目录下执行：

make metrics

该目标会启动完整 Prometheus + Grafana 栈并加载示例负载（文档见 deps/rabbitmq_prometheus/docker/grafana/README.md），随后：

  1. 浏览器访问http://localhost:3000，默认账号密码均为admin；
  2. 数据源与仪表盘已通过 provisioning 自动配置：./grafana/datasources.yml挂载为 Prometheus 数据源配置，./grafana/dashboards.yml挂载为仪表盘自动加载配置，./grafana/dashboards目录被挂载到容器/dashboards；
  3. 在 Grafana 左侧 Dashboard 列表中找到RabbitMQ-Stream打开即可。

用完可执行make down拆除环境。如需更换 Grafana 版本，编辑 docker-compose-metrics.yml 中services.grafana.image后重新make metrics。

方式二：手动导入（适用于已有 Grafana）

  1. 打开 Grafana → Dashboards → Import；
  2. 上传 RabbitMQ-Stream.json 或粘贴其内容；
  3. 数据源选择你的 Prometheus（该面板定义__inputs中的DS_PROMETHEUS，导入时会提示绑定数据源）；
  4. 导入后在顶部通过 Namespace / RabbitMQ Cluster 下拉框筛选目标环境。

无论哪种方式，前提都是 Prometheus 已能抓取到rabbitmq-prometheus插件的/metrics端点，且目标 RabbitMQ 节点上rabbitmq-stream插件已启用，否则面板中的 Stream 指标会恒为零值。

进阶：自行改版仪表盘时应注意什么

如果你希望基于该面板扩展（例如增加超时告警、按 vhost 拆分速率），仓库 deps/rabbitmq_prometheus/docker/grafana/README.md 给出了官方改版流程：先在deps/rabbitmq_prometheus下make overview metrics启动本地开发环境，在 Grafana UI 中编辑，随后通过 Share → Export 勾选 "Export for sharing externally" 导出 JSON 回填到仓库。实践中需要重点注意两点：

  • 保持查询模板一致：新增面板也应沿用on(instance, job) group_left(...) rabbitmq_identity_info{...}的标签映射模式与$namespace/$rabbitmq_cluster模板变量，否则在多集群场景下无法联动筛选；
  • 速率面板使用irate+$__rate_interval：这是 Grafana 推荐写法，能根据面板时间范围自动选择合理的速率计算窗口，避免固定窗口导致的锯齿或失真。

小结

RabbitMQ-Stream 官方 Grafana 仪表盘把 Stream 协议的生产/消费速率、连接数与启动以来错误计数浓缩为三层可视化结构：Stat 数字面板一眼掌握全局，饼图按节点定位热点，Time series 曲线还原历史趋势。配合rabbitmq_identity_info的标签映射，它天然支持 Namespace + Cluster 级别的多集群筛选。若想深入底层，可继续阅读 rabbit_stream_metrics.erl 了解指标采集源头，或查看 metrics.md 获取rabbitmq-prometheus插件暴露的完整指标清单。

【免费下载链接】rabbitmq-serverOpen source RabbitMQ: core server and tier 1 (built-in) plugins项目地址: https://gitcode.com/gh_mirrors/ra/rabbitmq-server

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/23 4:00:57

传输网络安全组网三大刚性约束与落地验证

简介：本资源是一份面向通信行业网络工程师、传输维护人员及高校相关专业师生的实战型技术培训课件，聚焦传输网络安全组网的核心原则与落地实践。内容系统梳理WDM/OTN、SDH、PTN、PON四大主流传输技术的安全组网规范，涵盖物理路由冗余、波道保…

作者头像 李华
网站建设 2026/9/23 4:00:54

计及调峰主动性的多能互补优化调度模型与Matlab实现

1. 从"被动调峰"到"主动调峰"：这组概念决定了调度模型的走向电力系统的优化调度，归根到底是在回答一个问题：明天（或未来某个时段）每台机组该发多少电，才能既满足负荷需求，又…

作者头像 李华
网站建设 2026/9/23 4:00:16

客服Agent生产化指南：从Demo到生产的36记血泪经验

1. 为什么一个客服Agent会在“审”字上卡这么久先说个场景。你花了两个星期，搭出一个客服Agent的Demo：能回答问题、能查订单、能转人工，demo演示的时候客户眼前一亮，老板当场拍板“这玩意儿赶紧上生产”。然后真正的噩梦开始了——…

作者头像 李华
网站建设 2026/9/23 3:58:05

IIS管理器实战：从服务引擎到配置入口，一文搞定网站部署与排错

前阵子帮朋友收拾一台 Windows Server 2019 的服务器，站点挂了，网站访问直接 503。他打开服务器桌面上的 IIS 管理器，一脸懵地问我：这个“文件夹树 中间一堆图标 右边操作栏”的窗口到底是干嘛的？我为什么在里边找不…

作者头像 李华
网站建设 2026/9/23 3:48:47

CTF入门三个月实战路线图：从零基础到独立完赛

1. 先定个现实的目标：三个月后你该会什么，不该会什么1.1 三个月的目标不是“拿奖”，而是“独立完赛”CTF（Capture The Flag，夺旗赛）这几年在网络安全圈子里出现的频率越来越高，很多高校战队、安…

作者头像 李华