Telegraf HAProxy 输入插件实战指南：基于 stats socket 与 HTTP 端点采集 HAProxy 运行指标

Telegraf HAProxy 输入插件实战指南基于 stats socket 与 HTTP 端点采集 HAProxy 运行指标【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf导读本文围绕 Telegraf 官方 HAProxy 输入插件plugins/inputs/haproxy展开讲解如何通过 HAProxy 的 stats socketUnix 域套接字、TCP 套接字或 HTTP 状态页端点将前端、后端、服务器与监听器的实时运行状态采集为结构化的haproxy指标。读完本文你将掌握完整的配置写法、端点寻址规则、字段重命名机制、指标结构与标签语义并了解插件在源码层面的采集与 CSV 解析原理可直接在真实环境中落地部署与排查。插件概览inputs.haproxy是 Telegraf 自带的官方输入插件用于收集 HAProxy 服务器的统计信息数据源可以是stats socketUnix 域套接字也可以是HTTP 状态页。插件最早随 Telegraf v0.1.5 发布标签归类为network、server支持所有平台 all。在 plugins/inputs/haproxy/haproxy.go 中可以看到插件通过inputs.Add(haproxy, ...)注册插件名称为haproxy。插件一次Gather会产出名为haproxy的测量measurement其中包含了 HAProxy 状态页 CSV 中几乎所有可用的统计列覆盖连接数、流量字节数、请求速率、健康检查结果、HTTP 状态码分布等关键信息。插件全局配置选项与 Telegraf 其他插件一致inputs.haproxy也支持用于修改指标、标签、字段、创建别名以及控制插件执行顺序的全局与插件级配置选项具体可参见 docs/CONFIGURATION.md 中的说明。配置时可以将inputs.haproxy放入标准的[[inputs.haproxy]]表段并结合namepass、fieldpass、tagexclude等通用选项按需裁剪采集结果。基础配置与完整参数说明插件提供了一份完整、可直接复制使用的示例配置同时存放于 plugins/inputs/haproxy/sample.conf核心配置项如下# Read metrics of HAProxy, via stats socket or http endpoints [[inputs.haproxy]] ## List of stats endpoints. Metrics can be collected from both http and socket ## endpoints. Examples of valid endpoints: ## - http://myhaproxy.com:1936/haproxy?stats ## - https://myhaproxy.com:8000/stats ## - socket:/run/haproxy/admin.sock ## - /run/haproxy/*.sock ## - tcp://127.0.0.1:1936 ## ## Server addresses not starting with http://, https://, tcp:// will be ## treated as possible sockets. When specifying local socket, glob patterns are ## supported. servers [http://myhaproxy.com:1936/haproxy?stats] ## By default, some of the fields are renamed from what haproxy calls them. ## Setting this option to true results in the plugin keeping the original ## field names. # keep_field_names false ## 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各配置项的含义与取值说明如下配置项类型默认值说明serversstring 数组空未配置时回退到默认端点统计端点列表可混用 HTTP/HTTPS、tcp://套接字与本地 Unix socket支持 glob 通配符keep_field_namesboolfalse为true时保留 HAProxy 原始列名不做字段重命名tls_castring空用于 HTTPS 连接的 CA 证书路径tls_certstring空客户端证书路径tls_keystring空客户端私钥路径insecure_skip_verifyboolfalse使用 TLS 但跳过证书链与主机名校验仅测试环境建议开启需要说明的是从 haproxy.go 的插件结构体定义可以确认插件实际还支持username与password两个配置项TOML 键为username、password用于在端点上显式指定 HTTP Basic Auth 凭据未在 sample.conf 中显式列出但可直接写入配置使用。未配置 servers 时的默认行为从源码的Gather实现haproxy.go可以看到当servers为空时插件会默认采集http://127.0.0.1:1936/haproxy?stats即 HAProxy 状态页默认端口 1936。测试用例TestHaproxyDefaultGetFromLocalhosthaproxy_test.go也验证了这一行为。这意味着在没有显式配置的情况下插件会尝试连接本机默认状态页端点。HAProxy 侧的前置配置要让插件能采到数据需要先在 HAProxy 侧开启统计功能。以下信息来自 HAProxy 官方文档可帮助你快速起步完整的最新指令请查阅 HAProxy 配置文档HTTP 状态页使用stats enable指令即可按默认设置开放未经认证的 HTTP 状态页访问。默认情况下状态页通常监听在 1936 端口访问形如http://host:1936/haproxy?stats的地址即可。Unix stats socket如需通过本地 socket 采集需要阅读并配置stats socket指令例如stats socket /run/haproxy/admin.sock mode 666 level admin使插件可以连接该 socket 并发送show stat命令获取 CSV 数据。上述stats enable与stats socket均为 HAProxy 配置文档中的标准指令请以你当前 HAProxy 版本的官方配置手册为准。servers 端点寻址规则详解servers是插件的核心配置支持同时混用多种类型的端点。端点的判定规则如下haproxy.go以http://或https://开头走 HTTP/HTTPS 请求访问 HAProxy 状态页。以tcp://开头走 TCP 套接字连接向远端发送show stat命令。其他地址不以 http/https/tcp 开头一律视为 Unix 域套接字。若地址包含协议前缀如socket:/run/haproxy/admin.sock前缀会被剥离实际使用:之后的部分作为 socket 路径见getSocketAddr实现haproxy.go。Unix socket 与 glob 通配符当使用 socket 名称时插件支持glob 通配符展开从而一次性从多个 socket 采集统计信息。例如配置servers [/run/haproxy/*.sock]插件会在采集前调用filepath.Glob展开所有匹配的 socket 路径haproxy.go并逐一连接采集。若通配符没有匹配到任何文件插件会按原路径尝试连接。这一行为在测试用例TestHaproxyGeneratesMetricsUsingSockethaproxy_test.go中有完整验证测试创建了 5 个随机命名的 Unix socket然后以 glob 掩码test-haproxy*.sock一次性采集全部 5 个 socket 的指标而对不存在的test-fail-haproxy*.sock掩码则会得到采集错误。HTTP Basic Auth 两种写法插件支持两种 Basic Auth 配置方式URL userinfo 方式直接在 URL 中携带凭据形如http://user:password1.2.3.4/haproxy?stats。从源码看插件解析 URL 后通过req.SetBasicAuth(u.User.Username(), p)把凭据写入 HTTPAuthorization请求头并将 userinfo 从 URL 中剥离后再发起请求haproxy.go因此凭据不会出现在实际请求的 URL 中避免了日志泄露。独立配置项方式在[[inputs.haproxy]]表段中显式配置username/password插件会以SetBasicAuth写入请求头haproxy.go。测试用例TestHaproxyGeneratesMetricsWithAuthenticationhaproxy_test.go同时验证了带认证与不带认证两种场景无凭据请求会得到 404/Unauthorized插件会将该端点错误上报。HTTP 请求行为对于 HTTP 端点插件会自动在 URL 末尾追加;csv后缀若尚未包含请求 HAProxy 的 CSV 格式输出haproxy.go同时设置了 3 秒的响应头超时与 4 秒的整体客户端超时haproxy.go。若响应状态码不是 200插件会报错并跳过该端点haproxy.go。并行采集当配置了多个端点时插件会为每个端点启动一个 goroutine 并发采集并通过sync.WaitGroup等待全部完成haproxy.go。单个端点失败不会影响其他端点错误会通过acc.AddError汇总上报。这在批量监控多套 HAProxy 实例时非常实用。keep_field_names 字段重命名机制默认情况下插件会把 HAProxy 状态页中的若干列名重命名为更易读的名称设置keep_field_names true则保留 HAProxy 原始列名。重命名映射在源码中定义于fieldRenames变量haproxy.go完整对照表如下HAProxy 原始列名插件重命名后字段名pxnameproxysvnamesvactactive_serversbckbackup_serverscli_abrtcli_abortsrv_abrtsrv_aborthrsp_1xxhttp_response.1xxhrsp_2xxhttp_response.2xxhrsp_3xxhttp_response.3xxhrsp_4xxhttp_response.4xxhrsp_5xxhttp_response.5xxhrsp_otherhttp_response.other注意http_response.*系列字段名中包含点号在 InfluxDB 行协议中会被解释为字段键中的命名空间前缀从而在查询时可以按http_response.2xx、http_response.5xx等分层聚合。测试用例TestHaproxyKeepFieldNameshaproxy_test.go验证了keep_field_names true时字段保留pxname、svname、act、bck、cli_abrt、hrsp_*等原始名称且pxname、svname会作为标签tag存在。指标结构与语义插件的输出测量名为haproxy结构与语义如下详细字段清单以 HAProxy CSV 格式文档为准标签tagsserver数据来源的服务器地址HTTP 端点为 hostsocket 端点为 socket 路径proxy代理名称原始列pxnamesv服务名称原始列svname例如FRONTEND、BACKEND或具体服务器名type代理会话类型frontend、backend、server、listener字符串字段fieldsstring 类型status、check_status、last_chk、mode、tracked、agent_status、last_agt、addr、cookie整数字段fieldsint 类型lastsess以 int64 解析其他所有统计列int 类型如qcur、qmax、scur、smax、slim、stot、bin、bout、dreq、dresp、ereq、econ、eresp、wretr、wredis、chkfail、chkdown、downtime、rate、rate_lim、rate_max、req_rate、conn_rate、comp_in、comp_out、comp_byp、comp_rsp、intercepted、dcon、dses等均以 uint64 解析从源码的importCsvResulthaproxy.go可以看到逐列的类型处理逻辑pxname、svname被提取为标签type列的数值被映射为可读的会话类型名称0→frontend、1→backend、2→server、3→listener定义于 haproxy.go未知的 type 值会直接报错check_desc、agent_desc两列被显式跳过因为它们是check_status/agent_status的更详细描述属于冗余信息上述 9 个字符串列按 string 类型写入字段lastsess按有符号 int64 解析其余所有数字列一律按 uint64 解析。此外解析器要求 CSV 首行必须是形如# pxname,svname,...的 HAProxy 标准头haproxy.go且每行列数必须与头一致否则报错这保证了数据来源的正确性。源码级采集流程解析结合 plugins/inputs/haproxy/haproxy.go一次完整采集的调用链如下Gather检查servers是否为空为空则回退到默认端点http://127.0.0.1:1936/haproxy?stats。遍历每个端点以http:///https:///tcp://前缀区分类别其余地址走 socket 分支并用filepath.Glob展开通配符。对展开后的全部端点启动并发 goroutine各自调用gatherServer。gatherServer中非 HTTP 端点调用gatherServerSocket建立unix或tcp连接后写入show stat\n命令haproxy.goHTTP 端点则追加;csv后发起 GET 请求附带 Basic Auth。最终统一走importCsvResult读取并校验 CSV 头 → 逐行解析 → 应用字段重命名与类型转换 → 调用acc.AddFields(haproxy, fields, tags, now)提交指标。testdata目录下的 sample_output.csv 提供了真实可用的 HAProxy CSV 样例来自官方 demo 站点包含了pxname,svname,qcur,qmax,scur,smax,slim,stot,bin,bout,...等 70 余列数据覆盖FRONTEND、BACKEND、真实服务器与备份服务器等不同行类型可用来对照理解各字段的含义。示例输出采集结果形如以下 InfluxDB 行协议时间戳为纳秒haproxy,server/run/haproxy/admin.sock,proxypublic,svFRONTEND,typefrontend http_response.other0i,req_rate_max1i,comp_byp0i,statusOPEN,rate_lim0i,dses0i,req_rate0i,comp_rsp0i,bout9287i,comp_in0i,modehttp,smax1i,slim2000i,http_response.1xx0i,conn_rate0i,dreq0i,ereq0i,iid2i,rate_max1i,http_response.2xx1i,comp_out0i,intercepted1i,stot2i,pid1i,http_response.5xx1i,http_response.3xx0i,http_response.4xx0i,conn_rate_max1i,conn_tot2i,dcon0i,bin294i,rate0i,sid0i,req_tot2i,scur0i,dresp0i 1513293519000000000从示例可以看出server标签记录了 socket 路径/run/haproxy/admin.sockproxy为public、sv为FRONTEND、type为frontend字段中既有statusOPEN、modehttp等字符串状态也有scur、smax、bin、bout、http_response.*等连接与流量计数可直接用于监控面板与告警规则。通过单元测试理解行为边界plugins/inputs/haproxy/haproxy_test.go 中的测试用例完整覆盖了插件的核心行为是理解边界条件的绝佳参考TestHaproxyGeneratesMetricsWithAuthentication/TestHaproxyGeneratesMetricsWithoutAuthentication验证带 Basic Auth 与不带认证的 HTTP 采集以及server、proxy、sv、type标签与active_servers、http_response.*等字段的准确性TestHaproxyGeneratesMetricsUsingSocket验证 Unix socket 采集与 glob 通配符展开一次性采集 5 个 socketTestHaproxyGeneratesMetricsUsingTcp验证tcp://端点采集TestHaproxyDefaultGetFromLocalhost验证未配置servers时回退到127.0.0.1:1936/haproxy?stats/;csvTestHaproxyKeepFieldNames验证keep_field_names true时保留原始列名。总结与使用建议inputs.haproxy插件提供了一套轻量、可靠的 HAProxy 可观测性采集方案核心要点可归纳为端点三通道HTTP 状态页自动补;csv、Unix socket支持 glob 通配符、TCP socket 均可采集且支持并行与混用认证安全URL userinfo 中的凭据会被转移到Authorization请求头不会出现在实际请求 URL 中字段可读性默认将pxname→proxy、act→active_servers、hrsp_5xx→http_response.5xx等重命名必要时可用keep_field_names true关闭标签语义清晰serverproxysvtype四元组可以唯一定位到 HAProxy 配置中的每个前端、后端、服务器与监听器配合rate、scur、http_response.*等字段即可构建健康检查、QPS、错误率等告警。如需进一步了解插件的全局配置选项如指标过滤、标签别名、插件执行顺序请参考 docs/CONFIGURATION.md插件完整源码与测试见 plugins/inputs/haproxy/haproxy.go 与 plugins/inputs/haproxy/haproxy_test.go。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考