Prometheus 监控 Apache Pulsar 全栈实战：从租户吞吐到 Bookie 延迟的分布式可观测性

jjj_web

386人浏览 · 2026-07-15 08:30:00

jjj_web · 2026-07-15 08:30:00 发布

Prometheus 监控 Apache Pulsar 全栈实战：从租户吞吐到 Bookie 延迟的分布式可观测性

Apache Pulsar 作为下一代云原生消息和流处理平台，其 分层架构（Broker + BookKeeper + ZooKeeper）带来了极高的扩展性，同时也增加了运维复杂度。Prometheus 原生集成是 Pulsar 的亮点之一——每个组件都内建了 HTTP 指标端点，无需任何外部导出器。本文将带你从零开启 Pulsar 的 Prometheus 端点，统一收集 Broker、Bookie、ZooKeeper、Proxy 的指标，结合 Grafana 大屏与告警规则，构建贯穿整个消息生命周期的可观测体系。

1. Pulsar 原生 Prometheus 支持概述

组件	默认 Metrics 端口	关键指标范围
Broker	`8080` (默认)	消息进出速率、订阅、消费者、生产者、存储大小、延迟、连接数
Bookie	`8000`	写入/读取延迟、日志大小、磁盘用量、Journal 队列、复制
ZooKeeper	`8000` (若启用)	会话数、延迟、数据大小
Proxy	`8080` (Pulsar Proxy)	前端连接、代理延迟、限流
Function Worker	`8080` (若独立部署)	函数实例、处理延迟、错误数

Pulsar 的指标格式完全符合 Prometheus 文本规范，只需在组件的配置中确认 exposeTopicLevelMetricsInPrometheus 等参数，然后让 Prometheus 直接抓取对应端口即可，零额外 Agent。

2. 启用 Pulsar 的 Prometheus 端点

2.1 Broker 配置

编辑 conf/broker.conf，确保以下设置：

# 开启 Prometheus 指标暴露
exposeTopicLevelMetricsInPrometheus=true          # 暴露主题级指标
exposeConsumerLevelMetricsInPrometheus=true       # 暴露消费者级指标
exposeProducerLevelMetricsInPrometheus=true       # 暴露生产者级指标（Pulsar 2.10+）

# 指标端口（默认 8080，与 admin 端口共用，也可以拆分开）
metricsPort=8080
metricsServletPath=/metrics

注意：如果担心指标量爆炸，可在生产环境仅暴露 topic 和 consumer 级别，或通过 prometheusMetricsServletExclude 排除不需要的指标。

重启 Broker。

2.2 Bookie 配置

编辑 conf/bookkeeper.conf：

# 启用 Prometheus HTTP 端点
prometheusStatsHttpPort=8000

Bookie 会自动暴露详细的读写、Journal、Ledger 指标。

2.3 ZooKeeper 配置

虽然 Pulsar 自带 ZK，但若你使用独立的 ZooKeeper 集群（版本 3.6+），可启用 Prometheus 指标。在 zoo.cfg 中增加：

metricsProvider.className=org.apache.zookeeper.metrics.prometheus.PrometheusMetricsProvider
metricsProvider.httpPort=7000

2.4 Proxy 与 Function Worker

Proxy：通常复用 Broker 的配置，通过 proxy.conf 设置 metricsPort 为独立端口（如 8081）以避免冲突。
Function Worker：若以 pulsar-admin functions-worker 或 K8s 部署，Worker 也会暴露 /metrics 端点。

3. 配置 Prometheus 抓取

在 prometheus.yml 中，按组件分组以便管理：

scrape_configs:
  # Pulsar Broker
  - job_name: 'pulsar-broker'
    scrape_interval: 30s
    static_configs:
      - targets:
          - 'broker1:8080'
          - 'broker2:8080'
          - 'broker3:8080'
        labels:
          cluster: 'pulsar-prod'
          component: 'broker'

  # Pulsar Bookie
  - job_name: 'pulsar-bookie'
    scrape_interval: 30s
    static_configs:
      - targets:
          - 'bookie1:8000'
          - 'bookie2:8000'
          - 'bookie3:8000'
        labels:
          cluster: 'pulsar-prod'
          component: 'bookie'

  # ZooKeeper (如果启用了 Prometheus)
  - job_name: 'pulsar-zookeeper'
    scrape_interval: 30s
    static_configs:
      - targets:
          - 'zk1:7000'
          - 'zk2:7000'
          - 'zk3:7000'
        labels:
          cluster: 'pulsar-prod'
          component: 'zookeeper'

  # Pulsar Proxy (如有)
  - job_name: 'pulsar-proxy'
    scrape_interval: 30s
    static_configs:
      - targets:
          - 'proxy1:8081'
          - 'proxy2:8081'
        labels:
          cluster: 'pulsar-prod'
          component: 'proxy'

如果启用 TLS/认证，Prometheus 支持 bearer_token 或 tls_config，可在抓取配置中声明。

4. 核心监控指标与 PromQL

Pulsar 的指标命名规范为 pulsar_<component>_<metric_name>，常用 Broker 和 Bookie 指标如下：

分类	关键指标（Broker）	含义	PromQL 示例
消息速率	`pulsar_rate_in` `pulsar_rate_out`	消息入/出速率（条/秒）	直接用或 `rate(pulsar_rate_in[1m])`
吞吐量	`pulsar_throughput_in` `pulsar_throughput_out`	入/出字节速率（字节/秒）	`rate(pulsar_throughput_in[1m])`
订阅与主题	`pulsar_subscriptions_count` `pulsar_topics_count`	订阅数/主题数	聚合看趋势
消息确认	`pulsar_entry_ack_rate`	消息确认速率	观察消费速度
存储大小	`pulsar_storage_size` `pulsar_storage_write_rate`	存储空间使用 / 写速率	结合磁盘告警
连接数	`pulsar_active_connections`	活跃客户端连接数	高水位告警
延迟 (Pulsar 2.9+)	`pulsar_storage_write_latency_le_*` (Histogram)	存储写入延迟分布	`histogram_quantile(0.99, rate(pulsar_storage_write_latency_bucket[5m]))`
未确认消息	`pulsar_msg_backlog`	积压消息总数（各主题）	> 阈值告警

Bookie 关键指标：

指标	含义	PromQL 示例
`bookie_ADD_ENTRY_REQUEST` / `READ_ENTRY_REQUEST` 计数器	写入/读取请求数	`rate(bookie_ADD_ENTRY_REQUEST[1m])`
`bookie_ADD_ENTRY_LATENCY` / `READ_ENTRY_LATENCY`	请求延迟直方图	P99 写入延迟：`histogram_quantile(0.99, rate(bookie_ADD_ENTRY_LATENCY_bucket[5m]))`
`bookie_journal_JOURNAL_SYNC_TIME`	Journal 同步耗时	高表示磁盘压力
`bookie_SERVER_STATUS`	Bookie 是否可写（1=可写，0=只读）	告警：`bookie_SERVER_STATUS == 0`
`bookie_LEDGER_CACHE_HIT_RATE`	读缓存命中率	低于 90% 需关注
`bookie_NUM_LEDGERS`	本机 Ledger 数量	过大可能负载不均

实际指标名可通过 /metrics 端点查询确认。Pulsar 版本不同可能有细微差别。

重要计算：

整体消息吞吐 (MB/s)：rate(pulsar_throughput_in[1m]) / 1024 / 1024
某主题的未确认消息数：pulsar_msg_backlog{namespace="...", topic="..."}
Bookie 写 P99 (ms)：histogram_quantile(0.99, rate(bookie_ADD_ENTRY_LATENCY_bucket[5m])) * 1000

5. Grafana 仪表盘推荐

Pulsar 社区提供了优质的官方仪表盘，可直接导入：

Pulsar Dashboard (Official)：Dashboard ID 14751（适用于 Pulsar 2.8+），包含 Broker、Bookie、ZooKeeper 的综合面板，基于 Prometheus 指标。这是首选。
Pulsar Broker：ID 11196，专注 Broker 侧消息速率、订阅等。
Pulsar BookKeeper Cluster：ID 2189，覆盖 Bookie 读写延迟、Journal、磁盘。

导入后选择数据源，将变量 cluster 绑定到你的 cluster 标签即可。

6. 告警规则实战

groups:
  - name: pulsar_alerts
    rules:
      - alert: PulsarBrokerDown
        expr: up{job="pulsar-broker"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Pulsar Broker {{ $labels.instance }} 宕机"

      - alert: PulsarBookieReadOnly
        expr: bookie_SERVER_STATUS == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Bookie {{ $labels.instance }} 进入只读状态，可能磁盘满或错误"

      - alert: PulsarHighMessageBacklog
        expr: pulsar_msg_backlog > 1000000
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "积压消息超过 100 万 (命名空间/主题: {{ $labels.namespace }}/{{ $labels.topic }})"

      - alert: PulsarHighBookieWriteLatency
        expr: histogram_quantile(0.99, rate(bookie_ADD_ENTRY_LATENCY_bucket[5m])) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Bookie 写 P99 延迟超过 500ms"

      - alert: PulsarStorageCapacityLow
        expr: (pulsar_storage_size / pulsar_storage_allocated_size) > 0.85
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "Broker 存储使用率超过 85%"

      - alert: PulsarNoActiveBroker
        expr: sum(up{job="pulsar-broker"}) == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "所有 Pulsar Broker 均已下线，服务完全不可用"

可根据业务特点增加 ZK 延迟、消费者数量为 0 等告警。

7. 进阶：多集群、安全与性能优化

7.1 多集群 / 跨地域监控

Pulsar 支持内置的跨地域复制。你只需为每个数据中心部署一套 Prometheus，或在中央 Prometheus 中通过远程写入汇聚，同时保持 cluster 标签区分。Grafana 面板中的变量可以切换集群。

7.2 TLS 与认证

Prometheus 抓取 Pulsar 的 /metrics 端点可以配置 TLS：

scrape_configs:
  - job_name: 'pulsar-broker'
    scheme: https
    tls_config:
      ca_file: /path/to/ca-cert.pem
    basic_auth:
      username: prometheus
      password: monitoring_pass

Pulsar 可以通过 broker.conf 配置 metricsAuthentication 以要求客户端证书或 token。生产环境务必开启。

7.3 指标量控制

Pulsar 的主题和消费者/生产者级指标会产生大量时间序列（特别是多租户环境）。可以使用 Prometheus 的 metric_relabel_configs 丢弃不关心的标签，或在 Pulsar Broker 中配置 prometheusMetricsServletInclude / exclude 过滤。例如只保留特定命名空间：

metric_relabel_configs:
  - source_labels: [namespace]
    regex: 'public/default|myapp'
    action: keep

7.4 函数与连接器监控

Pulsar Functions / Sink / Source 作为独立的 Worker 进程，默认也暴露 /metrics。为它们配置单独的抓取 Job，指标前缀通常为 pulsar_function_*。可以监控函数调用速率、错误数、处理延迟等。

8. 安全与运维建议

端口隔离：Broker 的 8080 端口既提供 Admin API 也提供 Prometheus 指标，通过防火墙或配置 metricsServletPath 与 admin 路径分离，或仅限 Prometheus 服务器访问。
Bookie 磁盘监控至关重要：Bookie 磁盘满会立即转为只读，直接导致写入失败。结合 node_exporter 的磁盘使用率告警双保险。
定期升级：Pulsar 新版本会持续优化指标命名、增加直方图，建议保持版本在 2.9 以上。

至此，你的 Pulsar 全组件——从 Broker 消息速率、Bookie 写延迟到跨地域复制状态——都被统一接入 Prometheus 体系。任何消息堆积、存储不足或节点异常，都会在 Grafana 上一目了然并实时告警，真正实现云原生消息平台的可观测性闭环。结合已有的主机与应用监控，你的数据管道将坚如磐石。