postgres_exporter 是 Prometheus 生态中用于采集 PostgreSQL 运行状态的官方 exporter，它除了内置默认指标外，还支持通过自定义 SQL 文件扩展采集逻辑。pg_stat_activity 视图记录了当前所有数据库连接的实时状态，是排查慢查询、连接泄漏和锁等待的核心数据源。将其转化为 exporter 指标，需要理解模板语法与指标命名约定。
一、postgres_exporter 自定义模板基本结构
postgres_exporter 从指定目录加载以 .sql 结尾的文件，每个文件对应一组指标。文件开头通过注释声明指标元信息，例如指标名、类型与帮助文本。SQL 查询结果的每一列若以数字类型返回，就会被暴露为指标；列名中的下划线会被转换为标签或指标后缀。
下面是一个最小可用的模板文件头部示例，它告诉 exporter 这是一个 gauge 类型的指标组，并描述其用途：
-- 指标组声明必须放在文件最前面
-- TYPE pg_stat_activity_count gauge
-- HELP pg_stat_activity_count Number of connections grouped by state and database
SELECT
datname AS database,
state,
count(*) AS count
FROM pg_stat_activity
GROUP BY datname, state;
在上述模板中，database 与 state 会成为指标标签，count 是实际的指标值。exporter 自动生成类似 pg_stat_activity_count{database="test",state="active"} 15 的时序数据。注意，SELECT 中的别名会直接影响 Prometheus 中的标签名，因此命名要稳定且不含特殊字符。
二、针对 pg_stat_activity 的实用采集模板
生产环境中我们往往不只关心连接数，还需要观察空闲事务、等待锁的连接比例。以下模板在基础连接数之上，增加了对 idle in transaction 的单独统计，并引入一个常量标签 instance 以便多实例区分。
该模板使用 CASE 表达式将状态归类，避免 pg_stat_activity 原生 state 取值过多导致标签膨胀。同时限定只统计后台非系统库，减少噪音：
-- TYPE pg_connections gauge
-- HELP pg_connections Grouped connection metrics from pg_stat_activity
SELECT
'{{.Labels.instance}}' AS instance,
datname AS database,
CASE
WHEN state = 'active' THEN 'active'
WHEN state = 'idle' THEN 'idle'
WHEN state LIKE 'idle in transaction%' THEN 'idle_in_transaction'
ELSE 'other'
END AS conn_type,
count(*) AS connections,
coalesce(sum(extract(epoch FROM now() - query_start)) FILTER (WHERE state='active'), 0) AS active_seconds
FROM pg_stat_activity
WHERE datname IS NOT NULL
AND backend_type = 'client backend'
GROUP BY datname, conn_type;
这里 {{.Labels.instance}} 是 postgres_exporter 支持的 Go 模板变量，需在启动 exporter 时通过配置注入。active_seconds 利用 FILTER 子句只累加活跃查询的耗时，帮助识别长事务。该写法在 PostgreSQL 9.6 及以上版本均可运行。
执行此类模板时，pg_stat_activity 是系统视图，读取不会加表锁，但在连接数极高的实例上 GROUP BY 仍会带来短暂 CPU 开销。建议采集间隔设为 15 秒以上，并在资源空闲期观察其执行计划。
三、常见误区与优化建议
很多用户在模板里直接 SELECT * FROM pg_stat_activity，企图把 query 字段也做成标签，这会引发 Prometheus 标签基数灾难，因为每个 SQL 文本都不同。正确的做法是绝不把易变文本作为标签输出，如需审计应走日志通道。
另一个误区是忽略 superuser 权限。pg_stat_activity 中部分字段（如其他用户的 query）在低权限账号下为 null，导致统计偏差。应为 exporter 创建专属只读账号并授予 pg_monitor 角色：
-- 创建专用监控账号 CREATE ROLE monitoring WITH LOGIN PASSWORD 'strong_password' NOINHERIT; GRANT pg_monitor TO monitoring;
使用 pg_monitor 角色后，账号可读取全部连接的聚合信息而不触碰数据安全边界。配合上文模板，既能拿到准确指标，又不需要 superuser。最后，记得在 exporter 启动参数中指定自定义模板目录：
postgres_exporter --collector.custom_query_path=/etc/postgres_exporter/queries --constant.labels=instance=node1
通过目录挂载与常量标签，同一套 SQL 模板可横向复用于多个数据库节点，实现统一监控接入。当指标进入 Prometheus 后，便可基于 pg_connections{conn_type="idle_in_transaction"} 配置告警，提前发现连接池污染问题。
四、模板调试与验证
编写完模板后，应先在 psql 中手动运行 SQL，确认返回行列符合预期，再交由 exporter 加载。exporter 启动日志会打印无法解析的指标文件及原因，例如类型声明缺失或列名含非法字符。
也可访问 exporter 的 /metrics 端点，搜索 pg_connections 前缀验证输出。若发现某标签值忽有忽无，通常是因为数据库名大小写或 state 映射分支遗漏。保持 CASE 分支覆盖所有现实状态，是保证面板稳定的关键。
postgres_exporterpg_stat_activitySQL模板修改时间：2026-08-01 15:21:29