企业官网建设流程全解析

• 消息队列
• 后端
• 流处理

本指南以 Apache Pulsar 官方文档（version-2.3.1 的 deploy-monitoring.md）为骨架，系统讲解如何对 Pulsar 集群进行监控：从 Broker、ZooKeeper、BookKeeper、Functions Worker 四大组件的指标采集，到 Prometheus 抓取配置、Grafana 仪表盘搭建与告警规则设置。读完本文，你将掌握通过pulsar-admin命令和 HTTP 端点获取 JSON/Prometheus 格式指标的方法，并能在裸机与 Kubernetes 两种部署形态下完成一套完整的可观测性闭环。

概述：Pulsar 监控的两个层面

监控一个 Pulsar 集群，需要同时关注两类信息：主题（Topic）的使用情况和集群各组件的整体健康状况。Pulsar 的指标体系覆盖 Broker、ZooKeeper、BookKeeper 与 Functions Worker 等核心组件，并通过两种格式对外暴露：

• JSON 格式：适合通过pulsar-admin命令按需、交互式地查询快照数据；
• Prometheus 格式：适合被 Prometheus 定时抓取，形成时间序列数据库，再交给 Grafana 渲染仪表盘。

需要特别说明的是，所有消息速率（message rate）类指标每分钟更新一次，在设计告警阈值和 Grafana 面板的时间粒度时需留意这一点。

采集组件指标

Broker 指标

Broker 指标通过pulsar-admin的broker-stats命令组采集，主要分为两类：

（1）目的地转储（Destination dumps）——包含每个独立主题的统计信息：

bin/pulsar-admin broker-stats destinations

（2）Broker 指标（Broker metrics）——包含 Broker 自身信息以及按 namespace 聚合的主题统计：

bin/pulsar-admin broker-stats monitoring-metrics

从 CmdBrokerStats.java 的源码可以看到，broker-stats命令组实际注册了 5 个子命令，除了文档提到的两个，还有：

• mbeans：转储 JMX MBean 统计；
• topics（别名destinations）：转储主题统计；
• allocator-stats：转储指定分配器的内存统计；
• load-report：转储 Broker 负载报告。

monitoring-metrics子命令还支持-i/--indent参数，用于输出带缩进的、更易读的 JSON 结果。这些命令底层均通过PulsarAdmin.brokerStats()客户端接口实现，可在脚本中调用broker-stats monitoring-metrics -i定期抓取 JSON 快照。

此外，聚合后的 Broker 指标还会以 Prometheus 格式暴露在 HTTP 端点：

http://$BROKER_ADDRESS:8080/metrics/

这个端点由 PulsarPrometheusMetricsServlet.java 提供，它在生成指标时支持按配置决定是否导出主题级、消费者级、生产者级指标，并支持将 topic 与 partition 拆分为独立标签（splitTopicAndPartitionLabel）。生产环境中，建议按 namespace 粒度聚合采集，以控制时间序列数量（详见下文「Dashboards」小节）。

ZooKeeper 指标

Pulsar 自带的本地 ZooKeeper、配置存储（configuration store）服务器及其客户端，均可以通过 Prometheus 暴露详细统计：

http://$LOCAL_ZK_SERVER:8000/metrics http://$GLOBAL_ZK_SERVER:8001/metrics

• 本地 ZooKeeper 默认端口为8000；
• 配置存储（global ZooKeeper）默认端口为8001。

如需修改默认端口，可通过指定系统属性stats_server_port来调整（例如-Dstats_server_port=9000）。

BookKeeper 指标

BookKeeper 的统计框架（stats framework）通过修改 conf/bookkeeper.conf 中的statsProviderClass来配置。仓库自带的默认配置已启用 Prometheus 导出器：

http://$BOOKIE_ADDRESS:8000/metrics

对应的配置片段如下（见 conf/bookkeeper.conf）：

# Whether statistics are enabled # enableStatistics=true # Stats Provider Class (if statistics are enabled) statsProviderClass=org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider # Default port for Prometheus metrics exporter prometheusStatsHttpPort=8000

bookie 的默认 Prometheus 端口同为8000，可通过修改conf/bookkeeper.conf中的prometheusStatsHttpPort变更。值得注意的是，Presto 目录配置 conf/presto/catalog/pulsar.properties 中也出现了同类的pulsar.stats-provider-configs参数（含prometheusStatsHttpPort、prometheusStatsHttpEnable等键），说明这套 Stats Provider 机制在 Pulsar SQL 侧同样适用，可按需开关 HTTP 服务与端口。

Managed Cursor 确认状态的持久化指标

Pulsar 的确认状态（acknowledgment state）优先持久化到 Ledger；当写入 Ledger 失败时，则回退持久化到 ZooKeeper。要跟踪确认过程的状态，可以为 managed cursor 配置以下指标（这些指标已加入 Prometheus 接口，可在 Grafana 中监控查看）：

brk_ml_cursor_persistLedgerSucceed(namespace="", ledger_name="", cursor_name:"") brk_ml_cursor_persistLedgerErrors(namespace="", ledger_name="", cursor_name:"") brk_ml_cursor_persistZookeeperSucceed(namespace="", ledger_name="", cursor_name:"") brk_ml_cursor_persistZookeeperErrors(namespace="", ledger_name="", cursor_name:"") brk_ml_cursor_nonContiguousDeletedMessagesRange(namespace="", ledger_name="", cursor_name:"")

这些指标由 ManagedCursorMetrics.java 生成。从源码可见其聚合逻辑：遍历每个 ManagedLedger，解析出namespace，再遍历该 ledger 的全部 cursor，以namespace、ledger_name、cursor_name三个维度组装成指标，其中还额外包含brk_ml_cursor_writeLedgerSize、brk_ml_cursor_writeLedgerLogicalSize、brk_ml_cursor_readLedgerSize等读写大小指标。当brk_ml_cursor_persistLedgerErrors持续增长而brk_ml_cursor_persistZookeeperSucceed同时升高时，说明确认状态正在频繁回退到 ZooKeeper，通常意味着 Ledger 持久化路径存在异常，值得告警关注。

Functions Worker 指标

Functions Worker 的指标同样以 JSON 格式导出，其中包含 Functions Worker 的JVM 指标：

pulsar-admin functions-worker monitoring-metrics

Functions 与 Connectors 的指标可通过以下命令采集：

pulsar-admin functions-worker function-stats

聚合后的 Functions/Connectors 指标以 Prometheus 格式暴露在：

http://$FUNCTIONS_WORKER_ADDRESS:$WORKER_PORT/metrics:

其中FUNCTIONS_WORKER_ADDRESS与WORKER_PORT可在 conf/functions_worker.yml 中获取——仓库默认配置里workerPort: 6750（TLS 端口workerPortTls: 6751，见 conf/functions_worker.yml）。从源码看，Functions 的 Prometheus 采集链路由 FunctionsStatsGenerator.java 汇聚各 function runtime 的 Prometheus 指标，JVM 指标则通过 Prometheus hotspot 默认导出（见 WorkerStatsManager.java）。在 Kubernetes runtime 下，还可在 conf/functions_worker.yml 中为每个 function Pod 配置独立的metricsPort（示例为9094），留空则禁用该 Pod 的 Prometheus 暴露。

配置 Prometheus

采集到上述组件指标后，使用Prometheus统一收集所有组件暴露的指标，再通过Grafana仪表盘进行展示和监控。基本工作流为：

1. 为各组件配置 Prometheus 抓取任务（scrape job），目标分别指向 Broker 的:8080/metrics、本地/全局 ZooKeeper 的:8000/:8001/metrics、Bookie 的:8000/metrics与 Functions Worker 的:6750/metrics；
2. 设置合理的抓取间隔（如 15s/30s）与超时时间，并利用组件节点列表实现自动发现；
3. 将 Prometheus 作为数据源接入 Grafana，导入仪表盘模板。

部署形态差异：

• 裸机部署：需要手动提供要被抓取的节点列表（即把各 Broker、Bookie、ZooKeeper 节点逐一写入 Prometheus 的scrape_configs）；
• Kubernetes 部署：监控会自动配置（Pulsar Helm chart 内置了监控相关组件与抓取配置）。

仪表盘（Dashboards）

当收集时间序列统计时，最大的挑战是防止数据附加的维度数量爆炸。因此，实践中应只采集在 namespace 级别聚合的指标时间序列，避免为主题下的每个 partition、每个 consumer 都保留独立序列，否则 Prometheus 存储与查询开销会随集群规模急剧放大。

Pulsar per-topic 仪表盘

面向单主题维度的仪表盘说明参见 Pulsar Manager 管理指南（仓库内对应文档）。

Grafana

Grafana 可基于 Prometheus 中存储的数据创建仪表盘。在 Kubernetes 上部署 Pulsar 时，pulsar-grafanaDocker 镜像默认启用，并内置了主要仪表盘。如需手动启动该镜像：

docker run -p3000:3000 \ -e PROMETHEUS_URL=http://$PROMETHEUS_HOST:9090/ \ apachepulsar/pulsar-grafana:latest

仓库的 grafana/dashboards 目录中自带一组可直接导入的仪表盘 JSON 模板，覆盖了主要组件：bookkeeper.json、jvm.json、namespace.json、prometheus.json、topic.json、zookeeper.json，可作为裸机或现有 Kubernetes 集群导入 Grafana 的起点。

常用的 Grafana 仪表盘示例包括：

• pulsar-grafana：展示运行在 Kubernetes 上的 Pulsar 集群在 Prometheus 中采集到的指标；
• apache-pulsar-grafana-dashboard：一套面向不同 Pulsar 组件（同时支持 Kubernetes 与本地机器部署）的 Grafana 仪表盘模板合集。

告警规则（Alerting Rules）

根据自身 Pulsar 环境的业务要求，可以针对上述指标设置告警规则。告警规则基于 Prometheus 的规则引擎定义，典型的告警维度包括：

• Broker 层面：brk_ml_cursor_persistLedgerErrors突增、pulsar_broker_topics_count逼近容量阈值、namespace 级消息速率异常；
• BookKeeper 层面：bookie 磁盘使用率、写入失败率、journal 延迟；
• ZooKeeper 层面：节点存活数、请求延迟；
• Functions 层面：function 实例重启次数、处理失败率。

配置告警规则时，请遵循 Prometheus 告警规则语法，为每条规则设置合理的expr、for持续时间与labels/annotations，并通过 Alertmanager 路由到邮件、Webhook 或即时通讯工具。

小结与最佳实践

• 按 namespace 聚合采集指标，控制时间序列基数，是 Pulsar 监控可扩展性的关键；
• 消息速率指标每分钟更新一次，告警与面板的时间窗口应留出足够余量；
• Managed cursor 指标是定位确认状态持久化问题的重要信号，建议纳入默认监控面板；
• 裸机与 Kubernetes 的抓取配置方式不同：前者手动提供节点列表，后者由部署组件自动完成；
• Grafana 仪表盘可复用：Kubernetes 场景直接用pulsar-grafana镜像，裸机场景可导入仓库 grafana/dashboards 中的 JSON 模板二次调整。

本文涉及的配置与源码均在当前仓库中可查：命令实现见 CmdBrokerStats.java，Prometheus 端点实现见 PulsarPrometheusMetricsServlet.java 与 ManagedCursorMetrics.java，配置文件见 conf/bookkeeper.conf 与 conf/functions_worker.yml，仪表盘模板见 grafana/dashboards。

• 消息队列
• 后端
• 流处理