企业官网建设流程全解析

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 socket（Unix 域套接字）、TCP 套接字或 HTTP 状态页端点，将前端、后端、服务器与监听器的实时运行状态采集为结构化的haproxy指标。读完本文，你将掌握完整的配置写法、端点寻址规则、字段重命名机制、指标结构与标签语义，并了解插件在源码层面的采集与 CSV 解析原理，可直接在真实环境中落地部署与排查。

插件概览

inputs.haproxy是 Telegraf 自带的官方输入插件，用于收集 HAProxy 服务器的统计信息，数据源可以是stats socket（Unix 域套接字），也可以是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

各配置项的含义与取值说明如下：

需要说明的是，从 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）。测试用例TestHaproxyDefaultGetFromLocalhost（haproxy_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）：

1. 以http://或https://开头：走 HTTP/HTTPS 请求，访问 HAProxy 状态页。
2. 以tcp://开头：走 TCP 套接字连接，向远端发送show stat命令。
3. 其他地址（不以 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），并逐一连接采集。若通配符没有匹配到任何文件，插件会按原路径尝试连接。

这一行为在测试用例TestHaproxyGeneratesMetricsUsingSocket（haproxy_test.go）中有完整验证：测试创建了 5 个随机命名的 Unix socket，然后以 glob 掩码test-haproxy*.sock一次性采集全部 5 个 socket 的指标；而对不存在的test-fail-haproxy*.sock掩码则会得到采集错误。

HTTP Basic Auth 两种写法

插件支持两种 Basic Auth 配置方式：

1. URL userinfo 方式：直接在 URL 中携带凭据，形如http://user:password@1.2.3.4/haproxy?stats。从源码看，插件解析 URL 后通过req.SetBasicAuth(u.User.Username(), p)把凭据写入 HTTPAuthorization请求头，并将 userinfo 从 URL 中剥离后再发起请求（haproxy.go），因此凭据不会出现在实际请求的 URL 中，避免了日志泄露。
2. 独立配置项方式：在[[inputs.haproxy]]表段中显式配置username/password，插件会以SetBasicAuth写入请求头（haproxy.go）。

测试用例TestHaproxyGeneratesMetricsWithAuthentication（haproxy_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），完整对照表如下：

注意http_response.*系列字段名中包含点号，在 InfluxDB 行协议中会被解释为字段键中的命名空间前缀，从而在查询时可以按http_response.2xx、http_response.5xx等分层聚合。

测试用例TestHaproxyKeepFieldNames（haproxy_test.go）验证了keep_field_names = true时字段保留pxname、svname、act、bck、cli_abrt、hrsp_*等原始名称，且pxname、svname会作为标签（tag）存在。

指标结构与语义

插件的输出测量名为haproxy，结构与语义如下（详细字段清单以 HAProxy CSV 格式文档为准）：

• 标签（tags）：
  • server：数据来源的服务器地址（HTTP 端点为 host，socket 端点为 socket 路径）
  • proxy：代理名称（原始列pxname）
  • sv：服务名称（原始列svname，例如FRONTEND、BACKEND或具体服务器名）
  • type：代理会话类型（frontend、backend、server、listener）
• 字符串字段（fields，string 类型）：status、check_status、last_chk、mode、tracked、agent_status、last_agt、addr、cookie
• 整数字段（fields，int 类型）：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 解析

从源码的importCsvResult（haproxy.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，一次完整采集的调用链如下：

1. Gather检查servers是否为空，为空则回退到默认端点http://127.0.0.1:1936/haproxy?stats。
2. 遍历每个端点：以http:///https:///tcp://前缀区分类别；其余地址走 socket 分支，并用filepath.Glob展开通配符。
3. 对展开后的全部端点启动并发 goroutine，各自调用gatherServer。
4. gatherServer中：非 HTTP 端点调用gatherServerSocket，建立unix或tcp连接后写入show stat\n命令（haproxy.go）；HTTP 端点则追加;csv后发起 GET 请求，附带 Basic Auth。
5. 最终统一走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,proxy=public,sv=FRONTEND,type=frontend http_response.other=0i,req_rate_max=1i,comp_byp=0i,status="OPEN",rate_lim=0i,dses=0i,req_rate=0i,comp_rsp=0i,bout=9287i,comp_in=0i,mode="http",smax=1i,slim=2000i,http_response.1xx=0i,conn_rate=0i,dreq=0i,ereq=0i,iid=2i,rate_max=1i,http_response.2xx=1i,comp_out=0i,intercepted=1i,stot=2i,pid=1i,http_response.5xx=1i,http_response.3xx=0i,http_response.4xx=0i,conn_rate_max=1i,conn_tot=2i,dcon=0i,bin=294i,rate=0i,sid=0i,req_tot=2i,scur=0i,dresp=0i 1513293519000000000

从示例可以看出：server标签记录了 socket 路径/run/haproxy/admin.sock；proxy为public、sv为FRONTEND、type为frontend；字段中既有status="OPEN"、mode="http"等字符串状态，也有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 个 socket）；
• TestHaproxyGeneratesMetricsUsingTcp：验证tcp://端点采集；
• TestHaproxyDefaultGetFromLocalhost：验证未配置servers时回退到127.0.0.1:1936/haproxy?stats/;csv；
• TestHaproxyKeepFieldNames：验证keep_field_names = true时保留原始列名。

总结与使用建议

inputs.haproxy插件提供了一套轻量、可靠的 HAProxy 可观测性采集方案，核心要点可归纳为：

1. 端点三通道：HTTP 状态页（自动补;csv）、Unix socket（支持 glob 通配符）、TCP socket 均可采集，且支持并行与混用；
2. 认证安全：URL userinfo 中的凭据会被转移到Authorization请求头，不会出现在实际请求 URL 中；
3. 字段可读性：默认将pxname→proxy、act→active_servers、hrsp_5xx→http_response.5xx等重命名，必要时可用keep_field_names = true关闭；
4. 标签语义清晰：server+proxy+sv+type四元组可以唯一定位到 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