企业官网建设流程全解析

• 可观测性
• APM
• 链路追踪
• 指标监控
• 日志分析
• 微服务

本篇指南讲解如何在 Apache SkyWalking 中监控 Apache BookKeeper 集群：通过 OpenTelemetry Collector 抓取 BookKeeper 的 Prometheus 指标并推送到 SkyWalking OAP，经由 OpenTelemetry receiver 与 MAL（Meter Analysis Language）完成过滤、聚合与存储。读完你将掌握从 BookKeeper 到 SkyWalking 的完整数据链路、Layer: BOOKKEEPER的实体建模方式、全部预置监控面板与指标名称，以及如何基于仓库中的otel-rules规则文件自定义自己的监控指标与表达式。

BookKeeper 监控的整体架构

SkyWalking 本身并不直接采集 BookKeeper 指标，而是采用"Prometheus 暴露 + OpenTelemetry Collector 中转 + OAP 解析"的标准接入模式。整体数据流如下：

1. BookKeeper 暴露指标：BookKeeper 集群通过 Prometheus endpoint 暴露自身指标（默认端口8000，路径/metrics），每个 Bookie 节点即为一个 Prometheus target。
2. OpenTelemetry Collector 抓取与推送：Collector 使用 Prometheus Receiver 从 BookKeeper 集群拉取指标，再通过 OpenTelemetry gRPC exporter（OTLP）推送给 SkyWalking OAP Server。
3. OAP 解析与存储：SkyWalking OAP Server 使用 MAL（Meter Analysis Language）解析收到的指标，执行过滤（filter）、计算（calculate）、聚合（aggregate）后写入存储，最终呈现在监控面板上。

从实体模型看，BookKeeper 集群整体被建模为 OAP 中的一个Service，其Layer为BOOKKEEPER；集群内的各个节点（Bookie）则被建模为该 Service 下的Instance。该 Layer 在源码中注册于 Layer.java（register("BOOKKEEPER", 33, true)），因此 BookKeeper 服务与普通业务服务在拓扑、告警、指标面板上完全独立。

前置条件与三步接入 Setup

接入 BookKeeper 监控共三步：

1. 搭建 BookKeeper 集群：按 BookKeeper 官方部署文档搭建集群，并确保其 Prometheus endpoint 可被 Collector 访问。
2. 部署 OpenTelemetry Collector：Collector 负责抓取与转发，其 Kubernetes 部署方式参考 OpenTelemetry 官方文档。仓库中给出了一个可参考的 Collector 配置示例 otel-collector-config.yaml，该示例同时演示了 Pulsar 与 BookKeeper 两类 job 的抓取配置（详见下文）。
3. 配置 SkyWalking OpenTelemetry receiver：确保 OAP 的 OpenTelemetry receiver 已激活，并加载 BookKeeper 的 MAL 规则。

激活 OAP 的 OpenTelemetry receiver

OpenTelemetry receiver 是 OAP 接收 OTLP 指标数据的入口。在 application.yml 中，receiver-otel模块默认处于激活状态，其核心配置如下：

receiver-otel: selector: ${SW_OTEL_RECEIVER:default} default: enabledHandlers: ${SW_OTEL_RECEIVER_ENABLED_HANDLERS:"otlp-traces,otlp-metrics,otlp-logs"} enabledOtelMetricsRules: ${SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES:"apisix,nginx/*,k8s/*,istio-controlplane,vm,mysql/*,postgresql/*,oap,aws-eks/*,windows,aws-s3/*,aws-dynamodb/*,aws-gateway/*,redis/*,elasticsearch/*,rabbitmq/*,mongodb/*,kafka/*,pulsar/*,bookkeeper/*,rocketmq/*,clickhouse/*,activemq/*,kong/*,flink/*,airflow/*,banyandb/*,envoy-ai-gateway/*,ios/*,miniprogram/*,ai-agent/*"}

关键点：

• selector可通过环境变量SW_OTEL_RECEIVER覆盖；只有值为default（或等价配置）时 receiver 才会生效。
• enabledHandlers中必须包含otlp-metrics才能接收指标数据（示例默认已包含）。
• enabledOtelMetricsRules中已默认包含bookkeeper/*，即otel-rules/bookkeeper/目录下的规则会在 OAP 启动时被自动加载。注意：如果 OAP 启动时规则文件格式不合法，可能导致启动失败，修改规则后需谨慎校验。

参考的 OpenTelemetry Collector 配置

仓库中 otel-collector-config.yaml 给出了同时抓取 Pulsar broker 与 BookKeeper bookie 的完整示例，其中与 BookKeeper 相关的片段为：

receivers: prometheus: config: scrape_configs: - job_name: bookkeeper-monitoring scrape_interval: 10s static_configs: - targets: [bookie:8000] labels: cluster: pulsar-cluster relabel_configs: - source_labels: [ __address__ ] regex: (.+) target_label: node replacement: $$1 exporters: otlp: endpoint: oap:11800 tls: insecure: true service: pipelines: metrics: receivers: - prometheus processors: - batch exporters: - otlp

这段配置有两个对 SkyWalking MAL 规则至关重要的细节：

• job_name: bookkeeper-monitoring：MAL 规则文件中的filter正是通过该 job 名来筛选数据的（见下文规则解析），job 名必须与规则中的过滤条件一致。
• cluster与node标签：labels.cluster提供集群名（如pulsar-cluster），relabel_configs将 target 地址写入node标签；这两个标签正是 MAL 规则中服务/实例维度聚合的依据。

BookKeeper Cluster 级监控指标

BookKeeper 集群级指标定义在 bookkeeper-cluster.yaml 中，覆盖 Bookie 的存储与读写能力。全部监控面板如下：

集群级 MAL 规则解析

bookkeeper-cluster.yaml 的核心头部与规则如下：

filter: "{ tags -> tags.job_name == 'bookkeeper-monitoring' }" # OpenTelemetry job 名称 expSuffix: tag({tags -> tags.cluster = 'bookkeeper::' + tags.cluster}).service(['cluster'], Layer.BOOKKEEPER) metricPrefix: meter_bookkeeper metricsRules: - name: bookie_ledgers_count exp: bookie_ledgers_count.sum(['cluster', 'node']) - name: bookie_write_rate exp: bookie_WRITE_BYTES.sum(['cluster', 'node']).rate('PT1M') - name: bookie_read_rate exp: bookie_READ_BYTES.sum(['cluster', 'node']).rate('PT1M') # ... 其余规则见仓库文件

逐项理解：

• filter：只处理job_name == 'bookkeeper-monitoring'的数据。OpenTelemetry Collector 的 Prometheus Receiver 会自动把 Prometheus 的job标签转换为service.name，而 OAP 的 OTLP 入口又将其回填为job_name标签，因此 MAL 中通过tags.job_name即可精确筛选。
• expSuffix：为集群名加上bookkeeper::前缀后，以cluster作为维度生成Layer.BOOKKEEPER的 Service 实体（.service(['cluster'], ...)）。这保证了 OAP 中的 BookKeeper 服务命名唯一，例如bookkeeper::pulsar-cluster。
• metricPrefix: meter_bookkeeper：所有输出指标统一加前缀，形成上文表格中的meter_bookkeeper_*名称。
• sum(['cluster', 'node'])：按集群和节点维度求和——由于一个集群由多个 Bookie 组成，这里实际上把集群内所有节点的同名指标求和为集群级指标。
• .rate('PT1M')：对bookie_WRITE_BYTES/bookie_READ_BYTES这类累加型计数器，计算每分钟的变化率，输出即为表格中的读写速率（bytes/s）。PT1M为 ISO-8601 时长格式（1 分钟）。

BookKeeper Node 级监控指标

节点级指标定义在 bookkeeper-node.yaml 中，覆盖单个 Bookie 的 JVM 运行时状态与线程池状况。监控面板如下：

节点级 MAL 规则要点

bookkeeper-node.yaml 与集群级规则的最大区别在于expSuffix：

filter: "{ tags -> tags.job_name == 'bookkeeper-monitoring' }" expSuffix: tag({tags -> tags.cluster = 'bookkeeper::' + tags.cluster}).instance(['cluster'], ['node'], Layer.BOOKKEEPER) metricPrefix: meter_bookkeeper_node

• 使用.instance(['cluster'], ['node'], ...)而非.service(...)：cluster用于定位 Service（加上bookkeeper::前缀），node用于定位 Instance，从而把每个 Bookie 建模为集群 Service 下的实例。
• metricPrefix变为meter_bookkeeper_node，与集群级规则输出名区分。
• JVM 类指标（如jvm_memory_pool_bytes_used、jvm_gc_collection_seconds_count）直接来自 BookKeeper 内嵌的 JVM Prometheus exporter；线程池类指标则来自bookkeeper_server_*系列（如bookkeeper_server_thread_executor_completed、bookkeeper_server_BookieHighPriorityThread_threads等），这些是 BookKeeper 自身的ServerStatsPrometheus 指标，经.sum(['cluster', 'node'])（部分含pool、gc维度）聚合而来。

规则文件的验证方式：仓库内的 MAL 测试数据

仓库为 BookKeeper 的两份规则文件都提供了配套的测试样例，位于 meter-analyzer-scripts-test：

• bookkeeper-cluster.data.yaml：构造了cluster: test-cluster、node: test-node的输入样本（各指标值为 100.0），并断言输出为meter_bookkeeper_bookie_ledgers_count等指标、实体为scope: SERVICE且service: 'bookkeeper::test-cluster'、layer: BOOKKEEPER。其中读写速率期望值为25.0，验证了rate('PT1M')的计算正确性（100.0 累计值按分钟求导）。
• bookkeeper-node.data.yaml：输入覆盖线程池、JVM 内存、JVM 内存池（含pool: PS_Eden_Space维度）、GC（含gc: PS Scavenge维度）等全部指标，断言输出实体为scope: SERVICE_INSTANCE、service: 'bookkeeper::test-cluster'、instance: test-node，精确验证了 Service + Instance 两层实体建模与各维度标签的保留。

这些测试样例既是规则正确性的回归保障，也是理解"输入 Prometheus 标签 → 输出 MAL 指标与实体"映射关系的最佳参考。

自定义指标、表达式与监控面板

如果你需要监控 BookKeeper 的其他指标（例如 BookKeeper 4.x 新增的指标、或自定义线程池），可以遵循以下路径扩展：

1. 修改/新增 MAL 规则：编辑或仿照 bookkeeper-cluster.yaml 与 bookkeeper-node.yaml。在metricsRules下新增name（输出指标名）与exp（MAL 表达式）即可；注意metricPrefix会自动拼接到输出指标名前。MAL 表达式语法参见 MAL 设计文档。
2. 校验规则合法性：可仿照仓库中的测试数据文件（见上文）构造input与expected，通过 meter-analyzer-scripts-test 模块验证表达式语义，避免 OAP 启动时加载非法规则失败。
3. 配置面板：BookKeeper 的监控面板配置由 SkyWalking Horizon UI bundle（apache/skywalking-horizon-ui）随发行包提供，OAP 后端不再托管 UI dashboard JSON。因此自定义面板应通过 Horizon UI 完成，或参照其面板定义新增仪表盘。

总结

SkyWalking 对 BookKeeper 的监控遵循"Prometheus endpoint → OpenTelemetry Collector → OTLP → OAP MAL"的标准链路，通过 bookkeeper-cluster.yaml 与 bookkeeper-node.yaml 两份规则文件，将集群建模为Layer: BOOKKEEPER的 Service、节点建模为 Instance，并预置了存储、缓存、读写速率、JVM 与线程池等 19 个监控面板。接入时只需保证 Collector 的job_name与规则filter一致、提供cluster/node标签、并在 application.yml 中启用bookkeeper/*规则（默认已启用），即可在 SkyWalking 中看到完整的 BookKeeper 运行视图。

• 可观测性
• APM
• 链路追踪
• 指标监控
• 日志分析
• 微服务