企业官网建设流程全解析

• 可观测性
• 后端
• 微服务
• 云原生

本篇技术指南以 SkyWalking 社区 SWIP-8（SkyWalking Improvement Proposal 8，"Support ActiveMQ classic Monitoring"）为核心骨架，讲解如何将 Apache ActiveMQ Classic 的 JMX 指标通过 jmx_prometheus_javaagent 与 OpenTelemetry Collector 接入 SkyWalking OAP 的 Meter System，实现 Cluster / Broker / Destination 三个维度的多维监控。读完本文，你将掌握完整的链路搭建步骤、三类监控面板对应的全部指标定义、底层 MAL 表达式规则文件的结构与工作原理，以及如何基于仓库内已有的 e2e 测试配置快速复现整套监控环境。

一、方案背景与动机

Apache ActiveMQ Classic 是广受欢迎且功能强大的开源消息与集成模式服务器，支持多种跨语言客户端与协议，内置易用的企业集成模式（Enterprise Integration Patterns）与大量高级特性。但在 SkyWalking 的生态中，它此前缺少原生的指标监控能力，因此 SWIP-8 提出：通过 OpenTelemetry Collector 抓取以 Java Agent 方式运行的 jmx_prometheus_exporter 暴露的指标，将其送入 SkyWalking OAP Server，从而为 ActiveMQ Classic 提供监控支持。

该方案的核心设计意图是复用 SkyWalking 已有的 OpenTelemetry 接收能力与 Meter 系统，不引入任何新的第三方依赖（详见 SWIP-8 的 "Imported Dependencies libs and their licenses" 一节：No new dependency.），且不带来任何破坏性变更（no breaking changes），属于纯增量式的监控能力扩展。

二、整体架构与数据流

SWIP-8 指出本方案没有显著的架构级变化（"There is no significant architecture-level change."）。其完整数据流在仓库的 backend-activemq-monitoring.md 中被拆分为四个步骤：

1. JMX 采集源头：ActiveMQ Classic 对 JMX 有广泛支持，通过 JMX MBeans 暴露 broker 的行为数据，用于监控与控制。
2. 指标暴露：jmx_prometheus_exporter 以 Java Agent（推荐方式）挂载到 ActiveMQ Classic 的 JVM 中，在本机启动一个 HTTP Server，将本地 JVM 与 broker 的 JMX 指标转换为 Prometheus 格式对外服务。
3. 指标传输：OpenTelemetry Collector 通过 Prometheus Receiver 定时抓取 jmx_prometheus_exporter 的指标，再经 OpenTelemetry gRPC exporter 推送到 SkyWalking OAP Server。
4. 指标加工入库：OAP Server 使用 MAL（Meter Analysis Language） 解析规则对原始指标进行过滤（filter）、计算（calculate）、聚合（aggregate），最终落库并提供查询。

对应的配置示例存放在 e2e 测试目录 test/e2e-v2/cases/activemq 中，包括 ActiveMQ 配置、jmx_exporter 配置与 Collector 配置三份关键文件。

三、环境搭建：四步接入 ActiveMQ Classic

3.1 启用 ActiveMQ 的 JMX

在 ActiveMQ 的activemq.xml中启用 JMX。仓库 e2e 用例提供了完整可用的示例：activemq.xml，其中与 JMX 直接相关的片段如下：

<broker xmlns="http://activemq.apache.org/schema/core" brokerName="${ACTIVEMQ_BROKER_NAME}" dataDirectory="${activemq.data}"> ... <!-- The managementContext is used to configure how ActiveMQ is exposed in JMX --> <managementContext> <managementContext createConnector="false"/> </managementContext> ... <systemUsage> <systemUsage> <memoryUsage> <memoryUsage percentOfJvmHeap="70" /> </memoryUsage> <storeUsage> <storeUsage limit="100 gb"/> </storeUsage> <tempUsage> <tempUsage limit="50 gb"/> </tempUsage> </systemUsage> </systemUsage> ... </broker>

JMX 远程端口默认为1616，可以通过环境变量ACTIVEMQ_SUNJMX_START修改。e2e 用例的 docker-compose.yml 展示了具体的启动参数：

amq: image: apache/activemq-classic:6.0.1 expose: - 1616 environment: ACTIVEMQ_SUNJMX_START: "-Dcom.sun.management.jmxremote.port=1616 -Dcom.sun.management.jmxremote.rmi.port=1616 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false" ACTIVEMQ_BROKER_NAME: activemq-broker

3.2 部署 jmx_prometheus_exporter

jmx_prometheus_exporter 推荐以Java Agent方式随 ActiveMQ Classic 的 JVM 一起启动，在本地暴露一个 HTTP 端口提供 Prometheus 格式指标。若使用 Docker，也可以像 e2e 用例那样部署独立的 exporter 服务（基于bitnami/jmx-exporter镜像），通过远程 JMX 端口抓取指标。

其抓取规则配置文件示例见 config.yaml，核心参数说明如下：

其中includeObjectNames决定了后续 MAL 规则能否取到对应数据，e2e 用例的白名单覆盖了 ActiveMQ 业务 MBean 与 JVM 基础 MBean：

includeObjectNames: ["org.apache.activemq:*","java.lang:type=OperatingSystem","java.lang:type=GarbageCollector,*","java.lang:type=Threading","java.lang:type=Runtime","java.lang:type=Memory","java.lang:name=*"]

注意：backend-activemq-monitoring.md 特别提示要关注includeObjectNames的配置——若 MBean 未被白名单包含，对应指标将无法进入 SkyWalking 的监控体系。

3.3 配置 OpenTelemetry Collector

OpenTelemetry Collector 在本链路中扮演"指标搬运工"：用 Prometheus Receiver 抓取 jmx_exporter，再用 OTLP exporter 推送给 OAP。仓库提供的完整示例为 otel-collector-config.yaml：

receivers: prometheus: config: scrape_configs: - job_name: "activemq-monitoring" scrape_interval: 30s static_configs: - targets: ['amqexporter:5556'] labels: cluster: activemq-cluster exporters: otlp: endpoint: oap:11800 tls: insecure: true processors: batch: service: pipelines: metrics: receivers: - prometheus processors: - batch exporters: - otlp

其中两个关键点直接决定了 OAP 侧规则的匹配：

• job_name: "activemq-monitoring"：与后续 MAL 规则文件顶部的filter条件一一对应（见第四节）；
• labels.cluster: activemq-cluster：为所有抓取到的样本打上cluster标签，OAP 将依据该标签把数据归属到对应的 ActiveMQ 集群服务，而service_instance_id标签则由 OpenTelemetry Receiver 根据资源属性自动附加（见 3.4）。

e2e 的 docker-compose.yml 中还演示了通过otel/opentelemetry-collector:${OTEL_COLLECTOR_VERSION}镜像与--config=/etc/otel-collector-config.yaml参数启动 Collector 的方式。

3.4 配置 SkyWalking OpenTelemetry Receiver

OAP 侧需要激活receiver-otel（OpenTelemetry 接收器）。根据 opentelemetry-receiver.md：

• 通过系统环境变量SW_OTEL_RECEIVER=default，或在application.yml中设置receiver-otel/selector=${SW_OTEL_RECEIVER:default}来激活接收器；
• 默认启用otlpgRPC handler（enabledHandlers: ${SW_OTEL_RECEIVER_ENABLED_HANDLERS:"otlp-metrics"}）；
• 需要将 ActiveMQ 的规则文件加入启用列表，例如enabledOtelMetricsRules: ${SW_OTEL_RECEIVER_ENABLED_OTEL_METRICS_RULES:"...activemq-cluster,activemq-broker,activemq-destination"}（该列表以逗号分隔，可按需增删）。

规则文件位于$CLASSPATH/otel-rules目录下（打包后即oap-server/server-starter/src/main/resources/otel-rules），OAP 在启动时加载；若配置格式不合法，OAP 可能启动失败，因此修改规则后需仔细校验 YAML 语法。此外，OpenTelemetry Receiver 会给采集到的样本附加node_identifier_host_name标签（取自 OTLP 资源属性net.host.name或host.name），用于标识数据来源；同时注意：资源作用域内属性名中的点（.）会被转换为下划线（_），而指标作用域内不做转换。

四、监控模型：Layer / Service / Instance / Endpoint 的映射

按照 backend-activemq-monitoring.md 的说明，ActiveMQ Classic 监控在 OAP 中被建模为Layer: ActiveMQ下的Service。在每个集群内部：

• Broker被表示为Instance（实例）；
• Destination（队列/主题）被表示为Endpoint（端点）。

这一映射关系在三个 MAL 规则文件的expSuffix中直接可见：

• 集群维度：activemq-cluster.yaml 中expSuffix: tag({tags -> tags.cluster = 'activemq::' + tags.cluster}).service(['cluster'], Layer.ACTIVEMQ)——按cluster标签构建Service，并统一加activemq::前缀避免与其他服务冲突；
• Broker 维度：activemq-broker.yaml 中expSuffix: tag(...).instance(['cluster'], ['brokerName'], Layer.ACTIVEMQ)——在集群下按brokerName构建Instance；
• Destination 维度：activemq-destination.yaml 中expSuffix: tag(...).endpoint(['cluster'], ['destinationName'], Layer.ACTIVEMQ)——在集群下按destinationName构建Endpoint。

三个规则文件都使用metricPrefix（meter_activemq_cluster/meter_activemq_broker/meter_activemq_destination）为最终落库的指标名添加前缀，这正是 SWIP-8 指标表中所有meter_activemq_*指标名的由来。

五、指标清单：Cluster / Broker / Destination 三类监控面板

以下三张指标表完整继承自 SWIP-8 与 backend-activemq-monitoring.md，数据源统一为JMX Prometheus Exporter。

5.1 ActiveMQ Cluster（集群级，即 JVM 级）指标

5.2 ActiveMQ Broker 指标

5.3 ActiveMQ Destination 指标

六、MAL 规则源码级解析：指标是如何被加工出来的

SWIP-8 的指标表只是"结果"，真正决定指标语义的是 OAP 启动时加载的 MAL 规则文件。三个文件均位于 otel-rules/activemq，以下逐一解读其关键表达式。

6.1 通用结构

每个规则文件都由四部分组成：

• filter：入口过滤条件。三个文件均为filter: "{ tags -> tags.job_name == 'activemq-monitoring' }"，即只处理 OpenTelemetry Collector 中job_name为activemq-monitoring的样本——这与 otel-collector-config.yaml 中的job_name必须严格一致；
• expSuffix：维度映射后缀，决定数据归属到 Service / Instance / Endpoint（见第四节）；
• metricPrefix：指标名前缀；
• metricsRules：每条规则的name（指标后缀名）与exp（MAL 表达式，含原始 Prometheus 指标名与聚合算子）。

6.2 Cluster 规则的典型表达式

Cluster 规则同时加工 JVM 指标与 ActiveMQ Broker 全局计数指标（activemq-cluster.yaml）：

# The average system load, range:[0,10000]. - name: system_load_average exp: java_lang_OperatingSystem_SystemLoadAverage.avg(['cluster','service_instance_id'])*10000 # Threads currently used by the JVM. - name: thread_count exp: java_lang_Threading_ThreadCount.sum(['cluster','service_instance_id']) # The gc count of G1 Old Generation(JDK[9,17]). - name: gc_g1_old_collection_count exp: java_lang_G1_Old_Generation_CollectionCount.tagEqual('type','GarbageCollector').sum(['cluster','service_instance_id']).increase("PT1M") # Number of messages that have been sent to the broker per second. - name: enqueue_rate exp: org_apache_activemq_Broker_TotalEnqueueCount.sum((['cluster'])).rate("PT1M")

可以观察到几个值得注意的实现细节：

• JVM 原始指标名直接来自 jmx_exporter 的命名规则（包名、类型名用下划线连接），如java_lang_OperatingSystem_SystemLoadAverage、java_lang_Threading_ThreadCount；
• GC 指标区分了 JDK 版本：JDK[9,17] 使用 G1 专用指标名（java_lang_G1_Old_Generation_CollectionCount），JDK[6,8] 则退化为通用java_lang_GarbageCollector_CollectionCount并用tagEqual('name','PS MarkSweep')或'PS Scavenge'过滤——这解释了 SWIP-8 指标表中对两种 GC 系列的标注；
• 聚合粒度：sum/avg/max算子后的维度数组决定了按什么标签维度聚合，如['cluster','service_instance_id']表示在同一集群、同一 JVM 实例内聚合；
• 时间窗口算子：.rate("PT1M")计算每分钟速率，.increase("PT1M")计算每分钟增量（PT1M为 ISO-8601 时长格式，表示 1 分钟）；
• 量纲换算：系统负载原始值为 [0,1] 的小数，规则中*10000放大为 [0,10000] 的整数，与指标表中描述一致；
• ActiveMQ 业务指标：org_apache_activemq_Broker_TotalEnqueueCount等来自 ActiveMQ 的org.apache.activemqMBean，与 config.yaml 中includeObjectNames: ["org.apache.activemq:*", ...]的白名单严格对应。

6.3 Broker 规则的典型表达式

Broker 规则以brokerName为实例维度（activemq-broker.yaml）：

# Uptime of the broker in day. - name: uptime exp: org_apache_activemq_Broker_UptimeMillis.max(['cluster','brokerName','service_instance_id']) # If slave broker 1 else 0. - name: state exp: org_apache_activemq_Broker_Slave.sum(['cluster','brokerName','service_instance_id']) # The total number of messages sent to the broker. - name: enqueue_count exp: org_apache_activemq_Broker_TotalEnqueueCount.sum(['cluster','brokerName','service_instance_id']).increase("PT1M") # Memory used by undelivered messages in bytes. - name: memory_usage exp: org_apache_activemq_Broker_MemoryUsageByteCount.sum(['cluster','brokerName','service_instance_id']) # Number of messages on this broker that have been dispatched but not acknowledged. - name: queue_size exp: org_apache_activemq_Broker_QueueSize.sum(['cluster','brokerName','destinationName'])

6.4 Destination 规则的典型表达式

Destination 规则以destinationName、destinationType为端点维度，并演示了标签过滤的用法（activemq-destination.yaml）：

# Number of consumers subscribed to the topics. - name: topic_consumer_count exp: org_apache_activemq_Broker_ConsumerCount.tagEqual('destinationType','Topic').sum(['cluster','destinationName']) # The number of messages that have been dispatched to but not acknowledged by consumers. - name: inflight_count exp: org_apache_activemq_Broker_InFlightCount.sum(['cluster','destinationName','destinationType'])

其中tagEqual('destinationType','Topic')只保留 Topic 类型的样本，从而单独计算主题消费者数——这是 MAL 标签过滤算子在实际监控规则中的典型应用。

七、UI 面板与自定义扩展

7.1 内置监控面板

仓库在 ui-initialized-templates/activemq 目录下提供了四份开箱即用的 UI 模板：

• activemq-root.json：入口面板；
• activemq-cluster.json：集群级（JVM 与全局吞吐）面板；
• activemq-broker.json：broker 实例面板；
• activemq-destination.json：destination 端点面板。

并在 menu.yaml 中注册了菜单项，因此 OAP 启动后 SkyWalking UI 即可在菜单中看到 ActiveMQ 相关面板，无需额外导入。

7.2 自定义指标与面板

根据 backend-activemq-monitoring.md 的 "Customizations" 一节，你可以按需扩展：

• 指标定义与表达式规则：修改或新增 otel-rules/activemq 下的activemq-cluster.yaml、activemq-broker.yaml、activemq-destination.yaml，可自定义指标、过滤/计算/聚合表达式，规则语法遵循 MAL；
• UI 面板：自定义ui-initialized-templates/activemq目录下的 dashboard 面板配置。

由于该链路完全走 OpenTelemetry 通用接收通道，规则文件遵循 MAL 通用方案；但需注意 opentelemetry-receiver.md 的说明：receiver-otel由于是推模式（push mode），只支持group、defaultMetricLevel和metricsRules节点，不支持拉模式相关的其他节点。

八、端到端验证：e2e 测试如何复现整套监控

仓库在 test/e2e-v2/cases/activemq 下提供了完整的端到端验证用例，是快速复现本文整套方案的最佳参考，各文件职责如下：

• activemq.xml：启用了managementContext的 ActiveMQ 主配置，并定义了systemUsage（内存 70% JVM 堆、store 100GB、temp 50GB 上限，对应memory_limit/store_limit/temp_limit等指标的量程）与 openwire/amqp/stomp/mqtt/ws 多个 transportConnector；
• config.yaml：jmx_exporter 的抓取规则（见 3.2）；
• otel-collector-config.yaml：Collector 的 Prometheus Receiver + OTLP exporter 管道（见 3.3）；
• docker-compose.yml：一键编排oap、amq、amqexporter、otel-collector四个核心服务，以及amq-producer-mock、amq-consumer-mock两个压测容器——它们通过activemq producer/consumer命令行工具向queue://testQueue与topic://testTopic生产/消费消息，为监控指标提供真实流量；
• expected 目录：断言文件（service.yml、instance.yml、endpoint.yml、metrics-has-value*.yml），验证 OAP 是否生成了预期的 Service / Instance / Endpoint 实体，以及cluster、service_instance_id、destinationName、destinationType等标签是否携带了正确取值。

其中metrics-has-value-label-destinationname.yml等文件直接证明了 Destination 级指标确实按destinationName标签打点，是第五节指标表在真实运行环境中的行为验证。

九、兼容性与影响面

SWIP-8 明确了本方案的两个约束：

• 无新增依赖：整条链路只复用 jmx_prometheus_exporter、OpenTelemetry Collector 与 SkyWalking 已有的 OpenTelemetry Receiver / Meter 能力，SkyWalking 本身不引入新的第三方库；
• 无破坏性变更：监控能力以增量规则（otel-rules）与新增 UI 模板（ui-initialized-templates）的形式落地，不影响既有 trace / metric / log 链路。

需要特别留意的前提条件：

• JDK 版本差异：GC 指标区分了 JDK[9,17] 的 G1 指标与 JDK[6,8] 的 Parallel 指标，若使用其他 GC 组合（如 JDK 8 上的 G1），部分 GC 指标可能为空，属预期行为；
• JMX 端口与认证：远程 JMX（1616端口）的 SSL/认证开关须在ACTIVEMQ_SUNJMX_START与 jmx_exporter 的hostPort/username/password/ssl配置之间保持一致；
• 规则文件一致性：Collector 的job_name、jmx_exporter 的includeObjectNames白名单与 MAL 规则中的指标名必须相互匹配，任何一环缺失都会导致对应指标无法展示。

十、总结

从 SWIP-8 提案到仓库中完整的落地实现，SkyWalking 对 ActiveMQ Classic 的监控遵循了一条清晰的通用化路线：JMX MBeans → jmx_prometheus_exporter（Java Agent/独立服务）→ OpenTelemetry Collector（Prometheus Receiver + OTLP exporter）→ OAP 的 OpenTelemetry Receiver → MAL 规则聚合 → UI 面板展示。它不引入新依赖、无破坏性变更，并通过 Cluster / Broker / Destination 三层模型覆盖了从 JVM 资源、broker 吞吐与存储，到每个队列/主题的生产消费细节。无论是直接复用仓库中的 e2e 配置快速搭建监控，还是基于 MAL 规则与 UI 模板做深度自定义，本文提供的指标清单、规则源码与配置文件都已覆盖到可直接动手实践的程度。

• 可观测性
• 后端
• 微服务
• 云原生