其实我个人对 PostgreSQL 不熟，对 PostgreSQL 熟悉的同事都在忙，也不好意思问，我就自己摸索了一下，写了这篇文章，希望对大家有帮助。
本文记录的是一条最短路径：用 Categraf 采集 PostgreSQL 指标，用夜莺导入 PostgreSQL 大盘和告警规则，再按需要补充自定义 SQL 指标。
核心要点
- Categraf 默认带 PostgreSQL 插件，配置文件位于
conf/input.postgresql/postgresql.toml。 address用于配置 PostgreSQL 连接信息，outputaddress可以给监控对象设置更容易识别的别名。- 使用
./categraf --test --inputs postgresql可以先验证插件输出，再接入正式采集链路。 - 夜莺内置 PostgreSQL 仪表盘和告警规则，可以克隆到自己的业务组后按实际情况调整。
- 如果内置指标不够，可以通过
[[instances.metrics]]配置自定义 SQL 采集更多指标。
配置 Categraf
Categraf 默认带了 PostgreSQL 数据库监控插件，配置文件在：conf/input.postgresql/postgresql.toml。我的简化版本的配置如下：
[[instances]]
address = "host=localhost user=postgres password=1234 sslmode=disable"
outputaddress = "db001"
上面的配置，除了配置数据库连接地址，还额外配置了 outputaddress，相当于给数据库起了一个别名，更容易记忆，你可以按照自己的习惯来命名 outputaddress，一般都是 IP 地址或者业务名。
详细配置参考这里：https://github.com/flashcatcloud/categraf/blob/main/conf/input.postgresql/postgresql.toml
配置时要注意两点：第一，连接串里可能包含账号密码，不要把敏感信息暴露到截图、日志或指标标签里；第二，outputaddress 会影响后续仪表盘和告警里看到的对象名称，建议使用团队能识别的稳定名称。
测试 Categraf
通过下面的命令可以测试 postgresql 的插件输出。尤其是 server 那个标签，就是 outputaddress 指定的值，可以按照您的喜好调整，千万不要在这个字段暴露敏感认证信息。
./categraf --test --inputs postgresql
我的输出如下：
...
15:32:14 postgresql_up agent_hostname=ubuntu-linux-22-04-desktop server=db001 1
15:32:14 postgresql_session_time agent_hostname=ubuntu-linux-22-04-desktop db=postgres_global server=db001 0
15:32:14 postgresql_blks_read agent_hostname=ubuntu-linux-22-04-desktop db=postgres_global server=db001 22
15:32:14 postgresql_tup_deleted agent_hostname=ubuntu-linux-22-04-desktop db=postgres_global server=db001 0
15:32:14 postgresql_xact_commit agent_hostname=ubuntu-linux-22-04-desktop db=postgres_global server=db001 0
...
测试输出里至少要确认三件事：postgresql_up 是否为 1，server 标签是否符合预期，核心指标是否能正常返回。如果测试阶段就没有数据，先不要急着导入告警规则，应先排查连接、权限和插件配置。
导入大盘
去内置大盘里找到 PostgreSQL 的大盘，克隆自己的业务组就可以使用了：
最终大盘效果：
大家如果觉得大盘有设置不合理的地方，可以自行修改。也欢迎提 PR 给我们。
导入大盘后，建议先检查变量、数据源、server 标签和时间范围是否正确。如果一个面板没有数据，优先确认指标是否存在，再确认标签是否匹配。
导入规则
PostgreSQL 也有内置的告警规则：
可以克隆到自己的业务组下调整使用。大家如果觉得这些规则有设置不合理的地方，可以自行调整，也欢迎提 PR 给我们。
内置规则适合作为起点，不建议直接无修改用于所有生产库。不同业务库的连接数、事务量、慢查询、复制状态和容量增长差异很大，阈值要结合业务基线和维护窗口调整。
自定义采集
仔细查看 conf/input.postgresql/postgresql.toml 配置，可以看到 [[instances.metrics]] 部分，这是自定义 SQL 的地方，如果觉得内置的指标不够用，可以自定义 SQL 语句，采集更多的指标。
各个配置项解释如下：
mesurement指标名。指标名称最终为postgresql_${mesurement}_${metric_fields}[x],${metric_fields}[x]表示metric_fields的元素。request指定查询监控数据的 sql 语句metrics_fields返回的列中，指定哪些列作为监控数据的 value 上报label_fields返回的列中，指定哪些列作为监控数据的 label 上报field_to_append表示这个列附加到 metric_name 后面，作为 metric_name 的一部分timeout超时时间
自定义 SQL 采集适合补充业务特定指标或 PostgreSQL 插件未覆盖的状态信息。写自定义 SQL 时要控制查询成本，避免监控查询反过来影响数据库。
使用流程总结
| 步骤 | 动作 | 验收点 |
|---|---|---|
| 1 | 配置 conf/input.postgresql/postgresql.toml |
连接串和 outputaddress 正确 |
| 2 | 执行 ./categraf --test --inputs postgresql |
能看到 postgresql_up 和核心指标 |
| 3 | 启动正式采集 | 夜莺或后端时序库能收到 PostgreSQL 指标 |
| 4 | 克隆 PostgreSQL 大盘 | 面板变量、数据源和标签匹配 |
| 5 | 克隆告警规则 | 阈值、通知组和业务组按实际调整 |
| 6 | 按需添加自定义 SQL | 查询成本可控，指标名和标签清晰 |
扩展阅读：
FAQ
Q1：PostgreSQL 监控最短路径是什么？
A：配置 Categraf PostgreSQL 插件，先用 --test 验证输出，再在夜莺导入内置大盘和告警规则，最后按业务情况调整阈值。
Q2：outputaddress 有什么用？
A：它相当于给数据库起一个监控别名，测试输出里的 server 标签就是这个值。建议用稳定、可识别且不包含敏感信息的名称。
Q3：什么时候需要自定义 SQL 采集？
A：当内置指标不能覆盖你的监控需求时，可以通过 [[instances.metrics]] 增加自定义 SQL。但要控制 SQL 成本，避免监控查询影响数据库。
