Telegraf ActiveMQ 输入插件实战指南：基于 Console API 采集队列、主题与订阅者指标

Telegraf ActiveMQ 输入插件实战指南：基于 Console API 采集队列、主题与订阅者指标

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf

导读

ActiveMQ 是应用广泛的消息中间件，其内置的 Web Console 提供了基于 XML 的 Console API 端点。Telegraf 的inputs.activemq插件通过请求这些端点，将队列（queues）、主题（topics）与订阅者（subscribers）的运行状态转化为结构化指标，供 InfluxDB、Prometheus 等时序系统消费。本文将围绕 插件 README 展开，结合 activemq.go 源码与 activemq_test.go 测试，完整讲解该插件的配置项、采集原理、指标字段语义与实战部署要点。

一、插件概览与适用场景

inputs.activemq是 Telegraf 官方自带的输入插件，自Telegraf v1.8.0起提供，归属分类为messaging，可运行于all（所有）平台。它直接面向 ActiveMQ 消息代理（message broker）守护进程，无需额外安装探针或 Agent，只要目标 ActiveMQ 开启了 Web Console 且插件进程可访问对应 HTTP(S) 端口即可采集。

其典型应用场景包括：

• 监控队列积压深度（size），在消费端出现故障导致消息堆积时及时告警；
• 跟踪队列/主题的入队（enqueue）与出队（dequeue）吞吐趋势，评估消息生产与消费的速率匹配；
• 观察订阅者的pending_queue_size与dispatched_counter，定位慢消费者与消息延迟来源。

从仓库源码看，插件被注册于 activemq.go 的inputs.Add("activemq", ...)中，初始化默认值如下：

return &ActiveMQ{ Server: "localhost", Port: 8161, Webadmin: "admin", }

也就是说，即使完全不写配置，插件也会默认指向http://localhost:8161，Webadmin 根路径为admin。

二、配置详解：从最小可用到生产级

以下为插件在 sample.conf 中提供的完整配置模板，亦是插件 README 中的核心示例：

# Gather ActiveMQ metrics [[inputs.activemq]] ## ActiveMQ WebConsole URL url = "http://127.0.0.1:8161" ## Credentials for basic HTTP authentication # username = "admin" # password = "admin" ## Required ActiveMQ webadmin root path # webadmin = "admin" ## Maximum time to receive response. # response_timeout = "5s" ## Optional TLS Config # tls_ca = "/etc/telegraf/ca.pem" # tls_cert = "/etc/telegraf/cert.pem" # tls_key = "/etc/telegraf/key.pem" ## Use TLS but skip chain & host verification # insecure_skip_verify = false

各配置项的含义与源码行为如下：

1.url（必需）—— Web Console 地址

指定 ActiveMQ Web Console 的完整 URL，如http://127.0.0.1:8161。在 Init() 中会对其进行严格校验：

• 若同时配置了已废弃的server/port字段，则优先使用url；
• scheme 必须以http开头（https://同样合法，因为校验逻辑为strings.HasPrefix(u.Scheme, "http")）；
• 主机名（hostname）不能为空，否则分别返回invalid scheme或invalid hostname错误。

兼容性提示：早期版本使用server与port两个字段，自v1.11.0起被标记为 deprecated（deprecated:"1.11.0;use 'url' instead"，见 activemq.go），请统一改用url。

2.username/password—— Basic 认证凭据

ActiveMQ 的 Web Console 默认受用户认证保护。插件在每次 GET 请求前判断Username或Password任一非空，便调用req.SetBasicAuth(...)注入 Basic Auth 头（见 getMetrics()）。默认账号通常为admin/admin。

3.webadmin—— Webadmin 根路径

这是拼装 Console API 地址的关键参数，默认值为admin。三个采集端点均由它拼接而成（activemq.go）：

指标对象	请求路径
队列	/{webadmin}/xml/queues.jsp
主题	/{webadmin}/xml/topics.jsp
订阅者	/{webadmin}/xml/subscribers.jsp

测试 TestURLs 通过httptest模拟了/admin/xml/queues.jsp、/admin/xml/topics.jsp、/admin/xml/subscribers.jsp三个路径，并断言非预期路径返回 404，从侧面印证了端点拼装规则。如果你的 ActiveMQ 修改了 Console 的上下文路径，需同步调整该值。

4.response_timeout—— 请求超时

设置等待 HTTP 响应的最长时间，默认5s。源码中的兜底逻辑是：只要配置值小于 1 秒，就重置为 5 秒（activemq.go），随后作为http.Client.Timeout生效（createHTTPClient()）。对于大集群或跨地域采集，可适当调大。

5. TLS 配置组

当 Web Console 通过 HTTPS 暴露时使用：

• tls_ca：自定义 CA 证书路径（默认/etc/telegraf/ca.pem）；
• tls_cert/tls_key：客户端证书与私钥对（默认/etc/telegraf/cert.pem、/etc/telegraf/key.pem）；
• insecure_skip_verify：置为true时跳过证书链与主机名校验（默认false，仅建议在测试环境使用）。

这些字段来自 Telegraf 公共的tls.ClientConfig，在 createHTTPClient() 中通过a.ClientConfig.TLSConfig()统一生成 TLS 配置并注入http.Transport。

6. 全局插件配置

与所有 Telegraf 插件一样，inputs.activemq也支持在插件表中添加全局配置项，用于指标改名、增删标签、字段过滤与插件排序等。详见 docs/CONFIGURATION.md，常用示例包括：

[[inputs.activemq]] url = "http://127.0.0.1:8161" name_prefix = "mq_" [inputs.activemq.tags] env = "production"

name_prefix会在测量名前附加前缀，tags可为每条指标补充自定义标签；此外还可用name_override、name_suffix、fieldpass/fielddrop、tagpass/tagdrop等实现更精细的整形。

三、指标定义：字段语义与标签说明

插件尽最大努力保留了 ActiveMQ Console API 原始 XML 响应中的命名，因此字段名与 XML 属性一一对应。共输出三类测量（measurement）：

1.activemq_queues—— 队列指标

• tags：name（队列名，已做TrimSpace处理）、source（Web Console 主机名）、port（端口）
• fields：

字段	对应 XML 属性	含义
size	size	队列中当前积压的消息条数
consumer_count	consumerCount	当前订阅该队列的消费者数量
enqueue_count	enqueueCount	累计入队消息条数
dequeue_count	dequeueCount	累计出队（被消费）消息条数

2.activemq_topics—— 主题指标

• tags：name（主题名，注意源码中 topic 名称未做TrimSpace，参见 gatherTopicsMetrics）、source、port
• fields：与队列相同的size、consumer_count、enqueue_count、dequeue_count

3.activemq_subscribers—— 订阅者指标

• tags：client_id、subscription_name、connection_id、destination_name、selector（消息选择器表达式）、active（订阅是否激活，值为yes/no）、source、port
• fields：

字段	对应 XML 属性	含义
pending_queue_size	pendingQueueSize	该订阅者待派发（pending）的消息队列大小
dispatched_queue_size	dispatchedQueueSize	已派发（dispatched）但尚未确认的消息数
dispatched_counter	dispatchedCounter	累计派发消息次数
enqueue_counter	enqueueCounter	累计入队次数
dequeue_counter	dequeueCounter	累计出队次数

上述 tags 与 fields 的映射逻辑可在 gatherQueuesMetrics、gatherTopicsMetrics 与 gatherSubscribersMetrics 三个函数中逐行核实，测试 TestGatherQueuesMetrics、TestGatherTopicsMetrics、TestGatherSubscribersMetrics 分别用与 README 示例输出完全一致的 XML 数据验证了字段标签映射的正确性。

四、采集原理：从 HTTP 请求到 Influx 行协议

理解插件内部流程有助于排查采集异常与字段口径问题，完整调用链如下：

1. 初始化（Init）：校验 URL、设置默认超时、构建http.Client与baseURL；
2. 并发拉取（Gather）：依次（顺序执行）请求三个 XML 端点，见 Gather()；
3. XML 解码：使用encoding/xml将响应体反序列化为queues/topics/subscribers结构体。XML 结构定义于 activemq.go，例如队列节点为<queue name="..."><stats size="..." consumerCount="..." .../></queue>；
4. 非 200 处理：若端点返回非 200 状态码，直接返回形如{url} returned HTTP status {status}的错误（getMetrics()）；
5. 组装指标：将各节点的属性按映射写入 fields，主机名与端口写入 tags，调用acc.AddFields(...)输出到 Accumulator，最终由输出插件序列化为 InfluxDB 行协议。

对 XML 格式感兴趣的读者可参考测试中的原始报文（如 activemq_test.go），其中<feed>节点内的 RSS/Atom 浏览链接会被忽略，仅解析stats属性，这正是“尽力保留 XML 命名”的具体体现。

五、示例输出解读

插件 README 给出了真实的输出样例（以下节选两行进行解读）：

activemq_queues,name=sandra,source=localhost,port=8161 consumer_count=0i,enqueue_count=0i,dequeue_count=0i,size=0i 1492610703000000000 activemq_subscribers,connection_id=NOTSET,destination_name=AAA,selector=AA,active=no,source=localhost,port=8161,client_id=AAA,subscription_name=AAA pending_queue_size=0i,dispatched_queue_size=0i,dispatched_counter=0i,enqueue_counter=0i,dequeue_counter=0i 1492610703000000000

可从中确认以下事实：

• 所有字段以i结尾，表明是整型（integer）；
• host标签（如示例中的88284b2fe51b）由 Telegraf 全局注入，表示采集主机的 hostname，非插件产生；
• source、port标签来自 Web Console 的地址（localhost、8161）；
• 时间戳为纳秒级 Unix 时间戳（1492610703000000000对应 2017-04-19 附近），实际数值取决于采集时刻；
• 标签active=no表示该订阅者当前处于非激活状态，可用于告警场景。

注意：示例中部分行存在逗号转义或标签顺序差异（如name=AAA\与name=ActiveMQ.Advisory.MasterBroker\中的空格/转义），这是 InfluxDB 行协议对特殊字符（逗号、空格）的序列化规则所致，与插件本身无直接关系；对比测试 XML 中ActiveMQ.Advisory.MasterBroker名称尾随空格即可理解。

六、实战：启用插件与验证采集

1. 生成并修改配置

使用 Telegraf 自带的配置生成命令，仅启用该插件：

telegraf config --input-filter activemq --output-filter influxdb > telegraf.conf

编辑生成的telegraf.conf，确认[[inputs.activemq]]段落中的url指向正确的 Web Console 地址，并按需开启username/password。

2. 校验配置语法

telegraf --config telegraf.conf --test

--test模式会执行一次完整的 Gather 并在终端直接打印采集到的指标行协议，是验证连接、认证与指标内容最快捷的方式。若出现returned HTTP status 401类错误，请检查认证凭据；若超时，请检查网络连通性与response_timeout。

3. 前提与限制

• 目标 ActiveMQ 必须启用Web Console（默认端口 8161），插件并不支持通过 JMX 或 OpenWire 端口采集；
• 采集频率由[agent]段的interval控制，默认约每 10 秒一次；队列/主题数量庞大时，XML 响应体可能较大，需留意采集耗时与超时配置；
• 插件按 README 标注适用于所有平台，Windows/Linux/macOS 均可直接使用。

七、从源码看可扩展点

若需深度定制，可从以下源码位置入手：

• activemq.go：三个gather*Metrics函数集中了字段标签的映射逻辑，是理解“哪个 XML 属性对应哪个指标字段”的权威参考；
• activemq_test.go：既是行为回归测试，也是 XML 报文格式的现成文档，可在模拟环境中直接复用其中的 XML 片段调试自己的采集链路；
• sample.conf：由//go:generate自动从README.md同步生成，二者保持一致的配置文档可作为基线。

八、常见问题速查

现象	排查方向
401/403 错误	检查username/password是否正确，Web Console 用户是否被授权
invalid scheme/invalid hostname	检查url是否以http://或https://开头且包含有效主机名
404 错误	检查webadmin根路径是否正确（默认admin）
采集超时	调大response_timeout，或检查到 8161 端口的网络与防火墙
HTTPS 证书报错	配置tls_ca或临时启用insecure_skip_verify（仅测试环境）
指标缺失	确认队列/主题/订阅者在 Web Console 中可见，且name未包含特殊字符导致行协议解析问题

结语

inputs.activemq以极低的接入成本，借助 ActiveMQ 自带的 XML Console API，为队列、主题与订阅者三类核心对象提供了完整的可观测指标。本文以 插件 README 为骨架，结合 activemq.go 的配置校验与指标映射源码、activemq_test.go 的验证用例，以及 docs/CONFIGURATION.md 的全局配置机制，完整还原了该插件的配置、原理与排障全流程。读者可直接参照第六节的步骤在真实环境中启用采集，并将size、pending_queue_size等字段接入告警规则，实现对 ActiveMQ 消息链路的精细化监控。

【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf