pgwatch 指标定义完整指南如何用纯 SQL 自定义监控指标无需任何扩展【免费下载链接】pgwatchpgwatch: PostgreSQL metrics monitor/dashboard项目地址: https://gitcode.com/gh_mirrors/pg/pgwatchpgwatch 是一款轻量级 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.yamlselect (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必须返回epoch_ns时间列(extract(epoch from now()) * 1e9)::int8 as epoch_ns。若省略pgwatch 会用采集守护进程的服务端时间戳兜底精度略有损失。列类型只支持 4 种文本、整数、布尔、浮点数double precision。含 NULL 的列不会被存储建议用coalesce兜底。查询要快执行时间必须低于 Statement timeout默认 5 秒超时会被强制终止。列名要自解释且简短列名会被直接存入库中过长会增加存储成本。另有两个加分项tag_前缀以tag_开头的列如tag_schema、tag_table_name会被 PostgreSQL 建索引Grafana 自动发现维度时更快更准。gauges 声明对接 Prometheus 时列默认按只增不减的 Counter 处理像活跃连接数这类可增可减的列需在定义中声明为 Gauge。指标定义结构逐项拆解YAML 格式的指标定义包含以下字段一个最小可运行的例子完整版见 contrib/sample.metrics.yamlmetrics: 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 秒采集一次字段作用sqls指标查询文本键是最小支持的 PostgreSQL 版本。查询在 v14~v18 都可用时只需写14若某版本内部目录有破坏性变化再加一条新版本键即可gauges声明哪些列是可增可减的 Gauge仅对 Prometheus 输出生效*表示全部列is_instance_level开启实例级缓存同一实例的多个数据库共享指标数据降低监控负载node_status设为primary或standby后指标只在该状态下执行适合只与主库/备库相关的查询statement_timeout_seconds单条指标查询的超时时间默认 5 秒storage_name存储层改名让两个相似指标的数据写入同一张表init_sql指标查询前的初始化 SQL例如创建辅助函数本文场景用不到 小技巧用pgwatch metric list custom-metrics.yaml一条命令即可导出全部内置指标作为你编写自定义指标的模板命令详情见 docs/reference/cli_env.md。三步添加一个自定义监控指标方式一Web UI 图形化操作推荐新手打开 pgwatch Web UI进入METRICS页面点击 NEW按钮填写指标名称、选择最小支持的 PostgreSQL 版本粘贴你的 SQL 查询可加 gauges 等属性点击ADD METRIC在PRESETS页面把新指标加入某个预设并设置采集间隔整秒数或直接到SOURCES页面编辑目标库的 METRICS 选项卡单独指定。前端实现位于 internal/webui/src/pages/MetricsPage/表单分基本信息 / SQL / 设置三步引导式填写对新手非常友好。方式二YAML 文件方式直接编辑安装时自带的metrics.yaml内置全量定义在 internal/metrics/metrics.yaml在metrics数组中新增一个条目并按需加入某个presets。适合版本化管理配置的场景。效果验证指标数据在 Grafana 中呈现自定义指标入库后即可用 pgwatch 配套的 Grafana 面板源码见 grafana/直接绘图、配置告警无需自己写任何可视化代码常见问题速查 ⚡问题解决办法指标没数据检查是否已加入 Preset 或直接配置到 Source检查采集日志Web UI LOGS 页查询超时缩短 SQL 逻辑或调大该指标的statement_timeout_seconds某版本查询报错在sqls中为该版本单独增加一条查询监控负载偏高对实例级指标设置is_instance_level: true启用共享缓存需要操作系统指标CPU 等属于 PL/Python helper 范畴见 docs/tutorial/preparing_databases.md不属于纯 SQL能力范围总结pgwatch 把监控指标还原成了最朴素的形态——一条 SQL。只要会写SELECT你无需安装任何扩展、无需超级用户权限就能用纯 SQL 为 PostgreSQL 定义自定义监控指标理解epoch_ns与列类型约束 → 按 YAML 结构编写定义 → 通过 Web UI 或 YAML 接入预设三步即可让全新指标出现在 Grafana 面板中。【免费下载链接】pgwatchpgwatch: PostgreSQL metrics monitor/dashboard项目地址: https://gitcode.com/gh_mirrors/pg/pgwatch创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考