pgnodemx

1. 概述

pgnodemx 通过 SQL 提供 Linux 操作系统、进程、文件系统、cgroup 和 Kubernetes Downward API 指标。监控程序可以复用数据库连接采集节点及 IvorySQL 进程指标，无需额外部署独立的 exporter 端点。

本文在 Ubuntu 22.04 x86_64 环境中使用 IvorySQL 5.4（PostgreSQL 18.4）和 pgnodemx 1.7 完成验证。

2. 已验证的兼容能力

能力状态验证结果

能力	状态	验证结果
PGXS 编译安装	支持	pgnodemx 1.7 使用 IvorySQL 5.4 头文件和库成功编译
Linux `/proc` 指标	支持	内存、磁盘、进程、网络、负载和挂载信息函数均能返回数据
cgroup 检测	支持，存在限制	`cgroup_mode()` 能识别主机布局；上游 pgnodemx 1.7 不支持读取 hybrid 模式指标
Oracle 兼容会话	支持	切换兼容模式后，版本、内存和磁盘指标查询均成功
Kubernetes Downward API	取决于环境	配置的 Downward API 卷存在时可用

PGXS 编译安装

支持

pgnodemx 1.7 使用 IvorySQL 5.4 头文件和库成功编译

Linux /proc 指标

支持

内存、磁盘、进程、网络、负载和挂载信息函数均能返回数据

cgroup 检测

支持，存在限制

cgroup_mode() 能识别主机布局；上游 pgnodemx 1.7 不支持读取 hybrid 模式指标

Oracle 兼容会话

支持

切换兼容模式后，版本、内存和磁盘指标查询均成功

Kubernetes Downward API

取决于环境

配置的 Downward API 卷存在时可用

3. 前提条件

IvorySQL 5.4 已安装服务端开发头文件和 PGXS。
目标系统为 Linux，并向 IvorySQL 服务进程提供所需的 /proc 和 cgroup 文件。
已安装 C 编译器和 GNU make。
pgnodemx 必须使用与 IvorySQL 相同的 OpenSSL 头文件和库进行编译。

不要在 IvorySQL 服务进程中混用不同 OpenSSL 主版本。如果加入 pgnodemx 后启动时报 OpenSSL 未定义符号，应在与 IvorySQL 匹配的构建环境中重新编译 pgnodemx。将另一个不兼容的 OpenSSL 库直接链接进扩展不是安全的解决方案。

4. 编译安装

git clone --branch v1.7 --depth 1 \
  https://github.com/CrunchyData/pgnodemx.git
cd pgnodemx

make USE_PGXS=1 \
  PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config
sudo make USE_PGXS=1 \
  PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config install

编译前确认选中的 pg_config 属于 IvorySQL 5.4：

/usr/local/ivorysql/ivorysql-5/bin/pg_config --version

5. 配置预加载

在 postgresql.conf 中将 pgnodemx 追加到已有的 shared_preload_libraries，不要删除 IvorySQL 原有预加载库。

shared_preload_libraries = 'liboracle_parser, ivorysql_ora, gb18030_2022, pgnodemx'

非 Kubernetes 主机可以关闭 Downward API 访问，避免无意义的启动警告：

pgnodemx.kdapi_enabled = off

其他相关默认配置如下：

pgnodemx.cgroup_enabled = on
pgnodemx.containerized = off
pgnodemx.cgrouproot = '/sys/fs/cgroup'
pgnodemx.kdapi_path = '/etc/podinfo'

修改 shared_preload_libraries 后重启 IvorySQL，并在每个需要提供指标的数据库中创建扩展：

CREATE EXTENSION pgnodemx;

SELECT extversion
FROM pg_extension
WHERE extname = 'pgnodemx';

预期扩展版本为 1.7。

6. 授予监控权限

pgnodemx 要求调用者属于预定义的 pg_monitor 角色。应将该角色授予专用监控账户，不要让监控程序使用超级用户连接。

CREATE ROLE node_monitor LOGIN PASSWORD 'replace-with-a-strong-password';
GRANT pg_monitor TO node_monitor;
GRANT CONNECT ON DATABASE monitoring TO node_monitor;

同时应通过 pg_hba.conf、网络访问控制和 TLS 配置限制只有监控系统可以连接。

7. 查询指标

7.1. 扩展和运行环境信息

SELECT pgnodemx_version();
SELECT exec_path();
SELECT openssl_version();
SELECT cgroup_mode();

7.2. 内存、CPU、磁盘和网络信息

SELECT * FROM proc_meminfo()
WHERE key IN ('MemTotal', 'MemAvailable');

SELECT * FROM proc_loadavg();
SELECT * FROM proc_cputime();
SELECT * FROM proc_diskstats();
SELECT * FROM proc_network_stats();

7.3. IvorySQL 进程信息

SELECT * FROM proc_pid_cmdline();
SELECT * FROM proc_pid_io();
SELECT * FROM proc_pid_stat();

这些函数读取 IvorySQL 进程可见的操作系统视图。在容器中，查询结果反映的是容器可访问的命名空间和挂载文件系统。

8. Oracle 兼容模式

会话切换模式后扩展仍然可用：

SET ivorysql.compatible_mode = oracle;

SELECT pgnodemx_version() FROM dual;
SELECT val FROM proc_meminfo() WHERE key = 'MemTotal';
SELECT count(*) FROM proc_diskstats();

以上三条查询均已在 IvorySQL 5.4 验证通过。

9. 限制与安全建议

pgnodemx 1.7 支持 cgroup v1（legacy）和 cgroup v2（unified），不支持混合的 hybrid 布局。cgroup 指标不可用时，/proc 系列函数仍可使用。
pgnodemx.kdapi_path 不存在时，Kubernetes 函数返回 NULL 或空结果；非 Kubernetes 环境应关闭此功能。
主机文件可能包含敏感的进程、挂载和环境变量信息，只应向可信监控角色授予 pg_monitor。
指标采集会增加 SQL 和文件读取负载，应设置合理轮询间隔，并只查询必要的函数和字段。
该扩展仅适用于 Linux，并依赖内核、容器运行时和安全策略暴露的文件。

完整函数列表请参阅 pgnodemx 1.7 官方文档。