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:8161Webadmin 根路径为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字段则优先使用urlscheme 必须以http开头https://同样合法因为校验逻辑为strings.HasPrefix(u.Scheme, http)主机名hostname不能为空否则分别返回invalid scheme或invalid hostname错误。兼容性提示早期版本使用server与port两个字段自v1.11.0起被标记为 deprecateddeprecated: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.pemtls_cert/tls_key客户端证书与私钥对默认/etc/telegraf/cert.pem、/etc/telegraf/key.peminsecure_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 productionname_prefix会在测量名前附加前缀tags可为每条指标补充自定义标签此外还可用name_override、name_suffix、fieldpass/fielddrop、tagpass/tagdrop等实现更精细的整形。三、指标定义字段语义与标签说明插件尽最大努力保留了 ActiveMQ Console API 原始 XML 响应中的命名因此字段名与 XML 属性一一对应。共输出三类测量measurement1.activemq_queues—— 队列指标tagsname队列名已做TrimSpace处理、sourceWeb Console 主机名、port端口fields字段对应 XML 属性含义sizesize队列中当前积压的消息条数consumer_countconsumerCount当前订阅该队列的消费者数量enqueue_countenqueueCount累计入队消息条数dequeue_countdequeueCount累计出队被消费消息条数2.activemq_topics—— 主题指标tagsname主题名注意源码中 topic 名称未做TrimSpace参见 gatherTopicsMetrics、source、portfields与队列相同的size、consumer_count、enqueue_count、dequeue_count3.activemq_subscribers—— 订阅者指标tagsclient_id、subscription_name、connection_id、destination_name、selector消息选择器表达式、active订阅是否激活值为yes/no、source、portfields字段对应 XML 属性含义pending_queue_sizependingQueueSize该订阅者待派发pending的消息队列大小dispatched_queue_sizedispatchedQueueSize已派发dispatched但尚未确认的消息数dispatched_counterdispatchedCounter累计派发消息次数enqueue_counterenqueueCounter累计入队次数dequeue_counterdequeueCounter累计出队次数上述 tags 与 fields 的映射逻辑可在 gatherQueuesMetrics、gatherTopicsMetrics 与 gatherSubscribersMetrics 三个函数中逐行核实测试 TestGatherQueuesMetrics、TestGatherTopicsMetrics、TestGatherSubscribersMetrics 分别用与 README 示例输出完全一致的 XML 数据验证了字段标签映射的正确性。四、采集原理从 HTTP 请求到 Influx 行协议理解插件内部流程有助于排查采集异常与字段口径问题完整调用链如下初始化Init校验 URL、设置默认超时、构建http.Client与baseURL并发拉取Gather依次顺序执行请求三个 XML 端点见 Gather()XML 解码使用encoding/xml将响应体反序列化为queues/topics/subscribers结构体。XML 结构定义于 activemq.go例如队列节点为queue name...stats size... consumerCount... ...//queue非 200 处理若端点返回非 200 状态码直接返回形如{url} returned HTTP status {status}的错误getMetrics()组装指标将各节点的属性按映射写入 fields主机名与端口写入 tags调用acc.AddFields(...)输出到 Accumulator最终由输出插件序列化为 InfluxDB 行协议。对 XML 格式感兴趣的读者可参考测试中的原始报文如 activemq_test.go其中feed节点内的 RSS/Atom 浏览链接会被忽略仅解析stats属性这正是“尽力保留 XML 命名”的具体体现。五、示例输出解读插件 README 给出了真实的输出样例以下节选两行进行解读activemq_queues,namesandra,sourcelocalhost,port8161 consumer_count0i,enqueue_count0i,dequeue_count0i,size0i 1492610703000000000 activemq_subscribers,connection_idNOTSET,destination_nameAAA,selectorAA,activeno,sourcelocalhost,port8161,client_idAAA,subscription_nameAAA pending_queue_size0i,dispatched_queue_size0i,dispatched_counter0i,enqueue_counter0i,dequeue_counter0i 1492610703000000000可从中确认以下事实所有字段以i结尾表明是整型integerhost标签如示例中的88284b2fe51b由 Telegraf 全局注入表示采集主机的 hostname非插件产生source、port标签来自 Web Console 的地址localhost、8161时间戳为纳秒级 Unix 时间戳1492610703000000000对应 2017-04-19 附近实际数值取决于采集时刻标签activeno表示该订阅者当前处于非激活状态可用于告警场景。注意示例中部分行存在逗号转义或标签顺序差异如nameAAA\与nameActiveMQ.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考