企业官网建设流程全解析

pgwatch 指标定义完整指南：如何用纯 SQL 自定义监控指标，无需任何扩展

【免费下载链接】pgwatch🔬pgwatch: PostgreSQL metrics monitor/dashboard项目地址: https://gitcode.com/gh_mirrors/pg/pgwatch

pgwatch 是一款轻量级 PostgreSQL 指标监控与仪表盘工具，它的最大特色是：所有监控指标都用纯 SQL 查询定义——不需要安装任何扩展、不需要超级用户权限，只要会写 SQL，就能为 PostgreSQL 定义你自己的自定义监控指标。本文带你从零理解 pgwatch 的指标定义结构，掌握 3 步完成一个自定义指标的完整流程。

什么是 pgwatch 指标？💡

在 pgwatch 中，一个指标 = 一条命名的 SQL 查询。pgwatch 采集守护进程会定期在目标数据库上执行这条 SQL，把返回的每一行数据连同时间戳一起存入指标库，之后就能在 Grafana 中绘图或告警。

与写监控 Agent 不同，pgwatch 的指标可以直接引用pg_stat_activity、pg_stat_database、pg_stat_archiver等 PostgreSQL 内置系统视图。以官方内置的 WAL 归档指标为例（源码见 internal/metrics/metrics.yaml）：

select (extract(epoch from now()) * 1e9)::int8 as epoch_ns, archived_count, failed_count, case when coalesce(last_failed_time, '1970-01-01'::timestamptz) > coalesce(last_archived_time, '1970-01-01'::timestamptz) then 1 else 0 end as is_failing_int from pg_stat_archiver;

整个指标就是几行 SQL，没有任何扩展依赖。

自定义指标必须遵守的 4 条规则

想让纯 SQL 指标稳定运行，请遵循以下约定（详见 docs/reference/metric_definitions.md）：

1. 必须返回epoch_ns时间列：(extract(epoch from now()) * 1e9)::int8 as epoch_ns。若省略，pgwatch 会用采集守护进程的服务端时间戳兜底，精度略有损失。
2. 列类型只支持 4 种：文本、整数、布尔、浮点数（double precision）。含 NULL 的列不会被存储，建议用coalesce兜底。
3. 查询要快：执行时间必须低于 Statement timeout（默认 5 秒），超时会被强制终止。
4. 列名要自解释且简短：列名会被直接存入库中，过长会增加存储成本。

另有两个"加分项"：

• tag_前缀：以tag_开头的列（如tag_schema、tag_table_name）会被 PostgreSQL 建索引，Grafana 自动发现维度时更快更准。
• gauges 声明：对接 Prometheus 时，列默认按"只增不减"的 Counter 处理；像活跃连接数这类可增可减的列，需在定义中声明为 Gauge。

指标定义结构逐项拆解

YAML 格式的指标定义包含以下字段，一个最小可运行的例子（完整版见 contrib/sample.metrics.yaml）：

metrics: connections: sqls: 11: | select /* pgwatch_generated */ (extract(epoch from now()) * 1e9)::int8 as epoch_ns, count(*)::int8 as value from pg_stat_activity; gauges: - '*' is_instance_level: true presets: default: metrics: connections: 10 # 每 10 秒采集一次

💡 小技巧：用pgwatch metric list > custom-metrics.yaml一条命令即可导出全部内置指标，作为你编写自定义指标的模板（命令详情见 docs/reference/cli_env.md）。

三步添加一个自定义监控指标

方式一：Web UI 图形化操作（推荐新手）

1. 打开 pgwatch Web UI，进入METRICS页面，点击"+ NEW"按钮；
2. 填写指标名称、选择最小支持的 PostgreSQL 版本，粘贴你的 SQL 查询（可加 gauges 等属性），点击ADD METRIC；
3. 在PRESETS页面把新指标加入某个预设并设置采集间隔（整秒数），或直接到SOURCES页面编辑目标库的 METRICS 选项卡单独指定。

前端实现位于 internal/webui/src/pages/MetricsPage/，表单分"基本信息 / SQL / 设置"三步引导式填写，对新手非常友好。

方式二：YAML 文件方式

直接编辑安装时自带的metrics.yaml（内置全量定义在 internal/metrics/metrics.yaml），在metrics数组中新增一个条目，并按需加入某个presets。适合版本化管理配置的场景。

效果验证：指标数据在 Grafana 中呈现

自定义指标入库后，即可用 pgwatch 配套的 Grafana 面板（源码见 grafana/）直接绘图、配置告警，无需自己写任何可视化代码：

常见问题速查 ⚡

总结

pgwatch 把"监控指标"还原成了最朴素的形态——一条 SQL。只要会写SELECT，你无需安装任何扩展、无需超级用户权限，就能用纯 SQL 为 PostgreSQL 定义自定义监控指标：理解epoch_ns与列类型约束 → 按 YAML 结构编写定义 → 通过 Web UI 或 YAML 接入预设，三步即可让全新指标出现在 Grafana 面板中。

【免费下载链接】pgwatch🔬pgwatch: PostgreSQL metrics monitor/dashboard项目地址: https://gitcode.com/gh_mirrors/pg/pgwatch