Telegraf pgbouncer 输入插件详解采集 PgBouncer 连接池监控指标的配置与实现原理【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf本文以 Telegraf 的 pgbouncer 输入插件 文档为核心系统讲解如何通过[[inputs.pgbouncer]]配置采集 PgBouncer 负载均衡器的运行时指标stats / pools / lists / databases 四类SHOW命令并结合插件源码深入剖析地址解析、简单协议模式、空闲连接复用等关键实现细节帮助你在生产环境中正确部署并读懂每一条指标的底层含义。该插件自 Telegraf v1.8.0 引入支持所有平台分类标签为 server、web要求 PgBouncer 版本不低于 v1.5。插件通过 PostgreSQL 协议连接 PgBouncer 的管理控制台admin console执行SHOW STATS、SHOW POOLS、SHOW LISTS、SHOW DATABASES四条管理命令将结果转换为 Telegraf 指标并发送给输出端。插件注册与运行前提插件通过标准的init()注册机制在 pgbouncer.go 中注册到 Telegraf 输入插件注册表inputs.Add(pgbouncer, ...)并在默认实例中设置了三个关键初始值inputs.Add(pgbouncer, func() telegraf.Input { return PgBouncer{ Config: postgresql.Config{ MaxIdle: 1, MaxOpen: 1, IsPgBouncer: true, }, } })MaxIdle: 1、MaxOpen: 1连接池只保留单条连接。PgBouncer 的管理控制台不需要并发单连接即可满足采集需求IsPgBouncer: true这是一个内部标记toml:-不暴露为配置项用于告知共享的 PostgreSQL 驱动适配层对面是 PgBouncer 管理控制台从而切换行为详见后文协议适配一节。插件的通用配置继承自 plugins/common/postgresql/config.go 中的postgresql.Config因此除了address和show_commands之外还可以使用max_idle、max_open、max_lifetime等共享的 PostgreSQL 连接池参数。插件入口文件通过//go:embed sample.conf将 sample.conf 内嵌进二进制运行telegraf --usage时输出的即是该示例配置。配置详解下面是 sample.conf 的完整内容该文件同时是插件SampleConfig()的返回值# Read metrics from one or many pgbouncer servers [[inputs.pgbouncer]] ## specify address via a url matching: ## postgres://[pqgotest[:password]]host:port[/dbname]\ ## ?sslmode[disable|verify-ca|verify-full] ## or a simple string: ## hostlocalhost port5432 userpqgotest password... sslmode... dbnameapp_production ## ## All connection parameters are optional. ## address hostlocalhost userpgbouncer sslmodedisable ## Specify which show commands to gather metrics for. ## Choose from: stats, pools, lists, databases # show_commands [stats, pools]address两种等价写法address支持两种格式插件文档给出了明确约定PostgreSQL 连接 URLpostgres://[pqgotest[:password]]host:port[/dbname]?sslmode[disable|verify-ca|verify-full]键值对字符串host/run/postgresql port6432 usertelegraf databasepgbouncer所有连接参数都是可选的。文档特别强调了一点容易误解的语义不写dbname时驱动会默认连接到与用户名同名的数据库dbname仅用于建立连接并不限制后续可查询的数据库范围PgBouncer 的SHOW命令是管理命令天然覆盖全部数据库。从 config.go 的CreateService()可以看到当address为空或恰好是字符串localhost时会被替换为hostlocalhost sslmodedisable。另外address的类型是config.Secret意味着它兼容 Telegraf 的 secretstore 机制可以写成address ${secretstore:pgbouncer_addr}的形式而不把凭据明文落盘。show_commands默认值与合法性校验show_commands决定每次采集周期执行哪些管理命令可选值为stats、pools、lists、databases四者的任意子集。在 Init() 中未配置时的默认值为[stats, pools]——即不开启lists和databases任何不在白名单内的值都会直接返回错误invalid setting %q for show_command插件初始化失败。Gather()按配置顺序依次调用showStats→showPools→showLists→showDatabase四个方法见 Gather 实现任一命令执行失败即中断本轮采集并上报错误。四类指标及字段说明以下四张指标表完整继承自 README 文档字段的含义可参考 PgBouncer 官方文档中的SHOW命令说明并结合源码补充了 tag 的产生位置pgbouncer来自SHOW STATS类型名称说明tagsdb行中database列的值若结果集中无该列则回退为字符串pgbouncer见 accRowtagsserver脱敏后的连接串SanitizedAddressfieldsavg_query_count该数据库的平均查询次数fieldsavg_query_time平均查询耗时毫秒fieldsavg_wait_time平均等待耗时毫秒fieldsavg_xact_count平均事务数fieldsavg_xact_time平均事务耗时毫秒fieldstotal_query_count累计查询数fieldstotal_query_time累计查询耗时fieldstotal_received累计接收字节数fieldstotal_sent累计发送字节数fieldstotal_wait_time累计等待耗时fieldstotal_xact_count累计事务数fieldstotal_xact_time累计事务耗时showStats中有一个值得注意的版本兼容逻辑源码注释PgBouncer 1.5 至 1.9 的SHOW STATS数值列以整数类型返回而 1.12 起改为字符串返回。插件对两种情况分别处理——int64直接赋值string则用strconv.ParseInt转回整数若字符串解析失败会返回错误中断采集。pgbouncer_pools来自SHOW POOLS类型名称说明tagsdb数据库名tagsserver脱敏连接串tagsuser取自行中user列非空时才添加tagspool_mode取自pool_mode列非空时才添加fieldscl_active池中已连接客户端数fieldscl_waiting池中等待的客户端数fieldsmaxwait最大等待时间毫秒fieldsmaxwait_us最大等待时间微秒PgBouncer 1.15fieldssv_active活动服务器连接数fieldssv_idle空闲服务器连接数fieldssv_login正在登录的服务器连接数fieldssv_tested已被测试的服务器连接数fieldssv_used已使用的服务器连接数pgbouncer_lists来自SHOW LISTS类型名称说明tagsdb结果集中无database列故固定回退为pgbouncertagsserver脱敏连接串fieldsdatabases已知数据库数量fieldsusers已知用户数量fieldspools池数量fieldsfree_clients空闲客户端数量fieldsused_clients已使用客户端数量fieldslogin_clients正在登录的客户端数量fieldsfree_servers空闲服务器连接数fieldsused_servers已使用服务器连接数fieldsdns_namesDNS 缓存中名字数量fieldsdns_zonesDNS 缓存中 zone 数量fieldsdns_queriesDNS 查询数量SHOW LISTS的结果是列式的每行是list、items两列showLists会把它转置成fields[name] value的扁平字段showLists并显式跳过dns_pending行——因为它在旧版本中不是整数计数无法安全转换为int64。整个结果集最终合并为一条pgbouncer_lists指标。pgbouncer_databases来自SHOW DATABASES类型名称说明tagsdbPgBouncer 侧的数据库名name列刻意覆盖accRow的默认值以保持与其他三张测量一致tagspg_dbname实际指向的 PostgreSQL 数据库名database列tagsserver脱敏连接串fieldscurrent_connections当前连接数fieldspool_size池大小fieldsmin_pool_size最小池大小fieldsreserve_pool保留池大小fieldsmax_connections最大连接数fieldspaused是否暂停0/1fieldsdisabled是否禁用0/1SHOW DATABASES的输出中name是 PgBouncer 中的库名database是底层 PostgreSQL 库名。showDatabase 将前者写入dbtag与其余测量对齐便于跨测量做关联查询后者写入pg_dbnametag从而在代理名 ≠ 真实库名的场景下仍可区分两者。字段过滤ignoredColumns 黑名单四类命令的结果集中混有不少结构性列插件用一个全局黑名单 ignoredColumns 统一过滤避免把无监控价值甚至语义会被误用的列输出为字段var ignoredColumns map[string]bool{user: true, database: true, pool_mode: true, avg_req: true, avg_recv: true, avg_sent: true, avg_query: true, force_user: true, host: true, port: true, name: true, }其中user、database、pool_mode被提升为 tag因为 tag 更适合做分组维度而avg_req/avg_recv/avg_sent/avg_query这类 PgBouncer 1.14 才出现的每请求平均字节/耗时列则被直接丢弃host、port、force_user、name同理。这个黑名单是列名 → 是否忽略的映射后续 PgBouncer 新增的列若不在黑名单中会自动作为新字段输出——这是一种前向兼容的采集设计。协议适配为什么连接 PgBouncer 要特殊处理IsPgBouncer标记驱动了两处对 PostgreSQL 驱动行为的修正均在 plugins/common/postgresql/config.go强制简单查询协议Simple Protocol。PgBouncer 的管理控制台不理解PREPARE语句因此当IsPgBouncer或SimpleProtocol为真时连接配置的DefaultQueryExecMode被设为pgx.QueryExecModeSimpleProtocol禁用预编译语句。这与通过 transaction 模式的 PgBouncer 访问后端数据库的场景是同一类约束禁用空闲连接探活。database/sql驱动在复用空闲连接前会发送-- ping探活查询但管理控制台不是 SQL 解析器会拒绝该查询导致 PgBouncer 日志被刷满并迫使每个采集周期都重连。因此对 PgBouncer 场景通过stdlib.OptionShouldPing直接返回false关闭探活config.go 中的注释与实现。这两处修正对应的回归测试见 TestPgBouncerIdleConnectionReuseIntegration它专门验证空闲连接在连续Gather之间被复用、不会触发重连。server tag 的脱敏机制所有指标共用的servertag 并不是原始连接串而是SanitizedAddress。sanitizedAddress()先用正则把password、sslkey、sslcert、sslrootcert、sslmode等敏感片段整体删除再交给strings.TrimSpace规整config.go。如果连接用的是 URL 形式还会先经toKeyValue()解析为排序后的键值对形式保证 tag 输出稳定可复现。此外用户也可以直接用outputaddress参数指定servertag 的展示内容覆盖自动脱敏结果。实际输出示例以下是插件文档给出的influx格式示例输出时间戳1581569936000000000展示了四类测量在一次采集周期中的形态pgbouncer,dbpgbouncer,serverhost\debian-buster-postgres\ user\dbn\ port\6432\ dbname\pgbouncer\ avg_query_count0i,avg_query_time0i,avg_wait_time0i,avg_xact_count0i,avg_xact_time0i,total_query_count26i,total_query_time0i,total_received0i,total_sent0i,total_wait_time0i,total_xact_count26i,total_xact_time0i 1581569936000000000 pgbouncer_pools,dbpgbouncer,pool_modestatement,serverhost\debian-buster-postgres\ user\dbn\ port\6432\ dbname\pgbouncer\ ,userpgbouncer cl_active1i,cl_waiting0i,maxwait0i,maxwait_us0i,sv_active0i,sv_idle0i,sv_login0i,sv_tested0i,sv_used0i 1581569936000000000 pgbouncer_lists,dbpgbouncer,serverhost\debian-buster-postgres\ user\dbn\ port\6432\ dbname\pgbouncer\ ,userpgbouncer databases1i,dns_names0i,dns_queries0i,dns_zones0i,free_clients47i,free_servers0i,login_clients0i,pools1i,used_clients3i,used_servers0i,users4i 1581569936000000000 pgbouncer_databases,dbpgbouncer,pg_dbnamepgbouncer,serverhost\debian-buster-postgres\ user\dbn\ port\6432\ dbname\pgbouncer\ namepgbouncer disabled0i,pool_size2i,current_connections0i,min_pool_size0i,reserve_pool0i,max_connections0i,paused0i 1581569936000000000 pgbouncer_databases,dbpostgres,pg_dbnamepostgres,serverhost\debian-buster-postgres\ user\dbn\ port\6432\ dbname\pgbouncer\ namepostgres current_connections0i,disabled0i,pool_size20i,min_pool_size0i,reserve_pool0i,paused0i,max_connections0i 1581569936000000000注意两点pgbouncer_pools每行携带user与pool_modetag因为SHOW POOLS的粒度是数据库 × 用户pgbouncer_databases中同一实例会输出多行每个配置过的数据库一行且dbtag 使用的是 PgBouncer 侧的库名。端到端验证集成测试如何工作pgbouncer_test.go 中的TestPgBouncerGeneratesMetricsIntegration演示了完整的真实环境验证流程用testcontainers启动一个postgres:alpine后端POSTGRES_HOST_AUTH_METHODtrust和一个z9pascal/pgbouncer-container:1.24.1-latest代理端口 6432用户/密码均为pgbouncer以键值对连接串构造插件实例Init()→Start()→Gather()断言pgbouncer测量包含total_received、total_sent、total_query_time、avg_query_count等 7 个 int64 字段pgbouncer_pools测量包含cl_active、cl_waiting、sv_active等 8 个 int64 字段。测试默认在短模式go test -short下跳过因为它依赖 Docker 容器在没有容器环境时以本地已部署的 PgBouncer 手动配置插件做小规模验证即可。插件全局配置选项与 Telegraf 的其他输入插件一样[[inputs.pgbouncer]]还支持 全局插件配置 中定义的通用选项例如name_override、alias、tags、ignore/pass字段过滤器、measurement_rename、measurement_rename_func、fieldpass/fielddrop等可用于修改指标名、tag 与字段、创建实例别名或控制插件执行顺序。这些选项在 CONFIGURATION.md 的 Plugins 章节有完整说明。部署建议小结连接 PgBouncer 管理控制台而非透传到后端时务必使用插件提供的userpgbouncer或你在pgbouncer.ini中配置的 admin 用户因为只有 admin 用户才能执行SHOW管理命令需要lists/databases指标时显式配置show_commands [stats, pools, lists, databases]默认只有stats和pools通过 PgBouncer 代理访问的普通业务库监控请使用postgresql输入插件其SimpleProtocol场景同样被共享层处理本插件专用于采集代理自身的运行状态address支持 secretstore 与outputaddress脱敏展示敏感凭据不必出现在指标 tag 中。通过上述配置[[inputs.pgbouncer]]可以完整覆盖 PgBouncer 的连接池水位cl_waiting、sv_*、查询与事务负载pgbouncer测量、资源清单pgbouncer_lists以及数据库级池配置pgbouncer_databases四个维度的监控需求。【免费下载链接】telegrafAgent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.项目地址: https://gitcode.com/GitHub_Trending/te/telegraf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考