Skip to content

Commit 0c31429

Browse files
messere1messere1
committed
docs: add pgnodemx integration guide
Assisted-by: OpenAI:gpt-5
1 parent daefd13 commit 0c31429

6 files changed

Lines changed: 366 additions & 0 deletions

File tree

‎CN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.14.adoc[pgnodemx]
5556
* 监控运维
5657
** xref:3.2.adoc[日常监控]
5758
** xref:3.3.adoc[日常维护]

‎CN/modules/ROOT/pages/5.0.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库
2222
| 9 | xref:5.9.adoc[pgrouting] | 3.8.0 | 提供地理空间数据的路由计算功能，支持多种算法和数据格式 | 地理空间分析、路径规划、物流优化
2323
| 10 | xref:5.10.adoc[system_stats] | 3.2 | 提供用于访问系统级统计信息的函数 | 系统监控
2424
| 11 | xref:5.11.adoc[pgtt] | 4.5 | 创建、管理与使用Oracle风格临时表 | 业务开发
25+
| 12 | xref:5.14.adoc[pgnodemx] | 1.7 | 通过 SQL 提供 Linux 节点、进程、文件系统、cgroup 和 Kubernetes 指标 | 数据库主机监控、容器可观测性和容量分析
2526
|====
2627

2728
这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。

‎CN/modules/ROOT/pages/5.14.adoc‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= pgnodemx
5+
6+
== 概述
7+
8+
`pgnodemx` 通过 SQL 提供 Linux 操作系统、进程、文件系统、cgroup 和 Kubernetes Downward API 指标。监控程序可以复用数据库连接采集节点及 IvorySQL 进程指标，无需额外部署独立的 exporter 端点。
9+
10+
本文在 Ubuntu 22.04 x86_64 环境中使用 IvorySQL 5.4（PostgreSQL 18.4）和 pgnodemx 1.7 完成验证。
11+
12+
== 已验证的兼容能力
13+
14+
[cols="2,1,3"]
15+
|===
16+
|能力 |状态 |验证结果
17+
18+
|PGXS 编译安装
19+
|支持
20+
|pgnodemx 1.7 使用 IvorySQL 5.4 头文件和库成功编译
21+
22+
|Linux `/proc` 指标
23+
|支持
24+
|内存、磁盘、进程、网络、负载和挂载信息函数均能返回数据
25+
26+
|cgroup 检测
27+
|支持，存在限制
28+
|`cgroup_mode()` 能识别主机布局；上游 pgnodemx 1.7 不支持读取 hybrid 模式指标
29+
30+
|Oracle 兼容会话
31+
|支持
32+
|切换兼容模式后，版本、内存和磁盘指标查询均成功
33+
34+
|Kubernetes Downward API
35+
|取决于环境
36+
|配置的 Downward API 卷存在时可用
37+
|===
38+
39+
== 前提条件
40+
41+
* IvorySQL 5.4 已安装服务端开发头文件和 PGXS。
42+
* 目标系统为 Linux，并向 IvorySQL 服务进程提供所需的 `/proc` 和 cgroup 文件。
43+
* 已安装 C 编译器和 GNU make。
44+
* pgnodemx 必须使用与 IvorySQL 相同的 OpenSSL 头文件和库进行编译。
45+
46+
[IMPORTANT]
47+
不要在 IvorySQL 服务进程中混用不同 OpenSSL 主版本。如果加入 pgnodemx 后启动时报 OpenSSL 未定义符号，应在与 IvorySQL 匹配的构建环境中重新编译 pgnodemx。将另一个不兼容的 OpenSSL 库直接链接进扩展不是安全的解决方案。
48+
49+
== 编译安装
50+
51+
[source,shell]
52+
----
53+
git clone --branch v1.7 --depth 1 \
54+
https://github.com/CrunchyData/pgnodemx.git
55+
cd pgnodemx
56+
57+
make USE_PGXS=1 \
58+
PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config
59+
sudo make USE_PGXS=1 \
60+
PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config install
61+
----
62+
63+
编译前确认选中的 `pg_config` 属于 IvorySQL 5.4：
64+
65+
[source,shell]
66+
----
67+
/usr/local/ivorysql/ivorysql-5/bin/pg_config --version
68+
----
69+
70+
== 配置预加载
71+
72+
在 `postgresql.conf` 中将 pgnodemx 追加到已有的 `shared_preload_libraries`，不要删除 IvorySQL 原有预加载库。
73+
74+
[source,ini]
75+
----
76+
shared_preload_libraries = 'liboracle_parser, ivorysql_ora, gb18030_2022, pgnodemx'
77+
----
78+
79+
非 Kubernetes 主机可以关闭 Downward API 访问，避免无意义的启动警告：
80+
81+
[source,ini]
82+
----
83+
pgnodemx.kdapi_enabled = off
84+
----
85+
86+
其他相关默认配置如下：
87+
88+
[source,ini]
89+
----
90+
pgnodemx.cgroup_enabled = on
91+
pgnodemx.containerized = off
92+
pgnodemx.cgrouproot = '/sys/fs/cgroup'
93+
pgnodemx.kdapi_path = '/etc/podinfo'
94+
----
95+
96+
修改 `shared_preload_libraries` 后重启 IvorySQL，并在每个需要提供指标的数据库中创建扩展：
97+
98+
[source,sql]
99+
----
100+
CREATE EXTENSION pgnodemx;
101+
102+
SELECT extversion
103+
FROM pg_extension
104+
WHERE extname = 'pgnodemx';
105+
----
106+
107+
预期扩展版本为 `1.7`。
108+
109+
== 授予监控权限
110+
111+
pgnodemx 要求调用者属于预定义的 `pg_monitor` 角色。应将该角色授予专用监控账户，不要让监控程序使用超级用户连接。
112+
113+
[source,sql]
114+
----
115+
CREATE ROLE node_monitor LOGIN PASSWORD 'replace-with-a-strong-password';
116+
GRANT pg_monitor TO node_monitor;
117+
GRANT CONNECT ON DATABASE monitoring TO node_monitor;
118+
----
119+
120+
同时应通过 `pg_hba.conf`、网络访问控制和 TLS 配置限制只有监控系统可以连接。
121+
122+
== 查询指标
123+
124+
=== 扩展和运行环境信息
125+
126+
[source,sql]
127+
----
128+
SELECT pgnodemx_version();
129+
SELECT exec_path();
130+
SELECT openssl_version();
131+
SELECT cgroup_mode();
132+
----
133+
134+
=== 内存、CPU、磁盘和网络信息
135+
136+
[source,sql]
137+
----
138+
SELECT * FROM proc_meminfo()
139+
WHERE key IN ('MemTotal', 'MemAvailable');
140+
141+
SELECT * FROM proc_loadavg();
142+
SELECT * FROM proc_cputime();
143+
SELECT * FROM proc_diskstats();
144+
SELECT * FROM proc_network_stats();
145+
----
146+
147+
=== IvorySQL 进程信息
148+
149+
[source,sql]
150+
----
151+
SELECT * FROM proc_pid_cmdline();
152+
SELECT * FROM proc_pid_io();
153+
SELECT * FROM proc_pid_stat();
154+
----
155+
156+
这些函数读取 IvorySQL 进程可见的操作系统视图。在容器中，查询结果反映的是容器可访问的命名空间和挂载文件系统。
157+
158+
== Oracle 兼容模式
159+
160+
会话切换模式后扩展仍然可用：
161+
162+
[source,sql]
163+
----
164+
SET ivorysql.compatible_mode = oracle;
165+
166+
SELECT pgnodemx_version() FROM dual;
167+
SELECT val FROM proc_meminfo() WHERE key = 'MemTotal';
168+
SELECT count(*) FROM proc_diskstats();
169+
----
170+
171+
以上三条查询均已在 IvorySQL 5.4 验证通过。
172+
173+
== 限制与安全建议
174+
175+
* pgnodemx 1.7 支持 cgroup v1（`legacy`）和 cgroup v2（`unified`），不支持混合的 `hybrid` 布局。cgroup 指标不可用时，`/proc` 系列函数仍可使用。
176+
* `pgnodemx.kdapi_path` 不存在时，Kubernetes 函数返回 NULL 或空结果；非 Kubernetes 环境应关闭此功能。
177+
* 主机文件可能包含敏感的进程、挂载和环境变量信息，只应向可信监控角色授予 `pg_monitor`。
178+
* 指标采集会增加 SQL 和文件读取负载，应设置合理轮询间隔，并只查询必要的函数和字段。
179+
* 该扩展仅适用于 Linux，并依赖内核、容器运行时和安全策略暴露的文件。
180+
181+
完整函数列表请参阅 https://access.crunchydata.com/documentation/pgnodemx/1.7/[pgnodemx 1.7 官方文档]。

‎EN/modules/ROOT/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@
5252
*** xref:5.9.adoc[pgrouting]
5353
*** xref:5.10.adoc[system_stats]
5454
*** xref:5.11.adoc[pgtt]
55+
*** xref:5.14.adoc[pgnodemx]
5556
* Monitor and O&M
5657
** xref:3.2.adoc[Monitoring]
5758
** xref:3.3.adoc[Maintenance]

‎EN/modules/ROOT/pages/5.0.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o
2323
|*9*| xref:5.9.adoc[pgrouting] | 3.8.0 | Provides routing computation for geospatial data, supporting multiple algorithms and data formats | Geospatial analysis, route planning, logistics optimization
2424
|*10*| xref:5.10.adoc[system_stats] | 3.2 | Provide functions for accessing system-level statistics. | system monitor
2525
|*11*| xref:5.11.adoc[pgtt] | 4.5 | Create, manage and use Oracle-style Global Temporary Tables. | Business development
26+
|*12*| xref:5.14.adoc[pgnodemx] | 1.7 | Exposes Linux node, process, filesystem, cgroup, and Kubernetes metrics through SQL | Database host monitoring, container observability, and capacity analysis
2627
|====
2728

2829
These plugins have all been tested and adapted by the IvorySQL team to ensure stable operation in the IvorySQL environment. Users can select appropriate plugins based on business needs to further enhance the capabilities and flexibility of the database system.

‎EN/modules/ROOT/pages/5.14.adoc‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
:sectnums:
2+
:sectnumlevels: 5
3+
4+
= pgnodemx
5+
6+
== Overview
7+
8+
`pgnodemx` exposes Linux operating-system, process, filesystem, cgroup, and Kubernetes Downward API metrics through SQL. Monitoring agents can collect node and IvorySQL process metrics over an existing database connection without deploying a separate exporter endpoint.
9+
10+
This guide was verified with IvorySQL 5.4 (PostgreSQL 18.4) and pgnodemx 1.7 on Ubuntu 22.04 x86_64.
11+
12+
== Verified compatibility
13+
14+
[cols="2,1,3"]
15+
|===
16+
|Capability |Status |Verification
17+
18+
|PGXS build and installation
19+
|Supported
20+
|pgnodemx 1.7 built against IvorySQL 5.4 headers and libraries
21+
22+
|Linux `/proc` metrics
23+
|Supported
24+
|Memory, disk, process, network, load, and mount functions returned data
25+
26+
|cgroup detection
27+
|Supported with limitations
28+
|`cgroup_mode()` detected the host layout; upstream pgnodemx 1.7 does not support hybrid-mode metric reads
29+
30+
|Oracle-compatible sessions
31+
|Supported
32+
|Version, memory, and disk metric queries succeeded after switching compatibility mode
33+
34+
|Kubernetes Downward API
35+
|Environment dependent
36+
|Available when the configured Downward API volume exists
37+
|===
38+
39+
== Prerequisites
40+
41+
* IvorySQL 5.4 was built with server development headers and PGXS installed.
42+
* The target is Linux and exposes the required `/proc` and cgroup files to the IvorySQL server process.
43+
* A C compiler and GNU make are installed.
44+
* pgnodemx must be built with the same OpenSSL headers and libraries used by IvorySQL.
45+
46+
[IMPORTANT]
47+
Do not mix OpenSSL major versions in the IvorySQL server process. If startup reports an undefined OpenSSL symbol after adding pgnodemx, rebuild pgnodemx against the matching IvorySQL build environment. Linking a second incompatible OpenSSL library into the extension is not a safe workaround.
48+
49+
== Build and install
50+
51+
[source,shell]
52+
----
53+
git clone --branch v1.7 --depth 1 \
54+
https://github.com/CrunchyData/pgnodemx.git
55+
cd pgnodemx
56+
57+
make USE_PGXS=1 \
58+
PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config
59+
sudo make USE_PGXS=1 \
60+
PG_CONFIG=/usr/local/ivorysql/ivorysql-5/bin/pg_config install
61+
----
62+
63+
Confirm that the selected `pg_config` belongs to IvorySQL 5.4 before compiling:
64+
65+
[source,shell]
66+
----
67+
/usr/local/ivorysql/ivorysql-5/bin/pg_config --version
68+
----
69+
70+
== Configure preloading
71+
72+
Append pgnodemx to the existing `shared_preload_libraries` value in `postgresql.conf`. Do not remove IvorySQL's existing preload libraries.
73+
74+
[source,ini]
75+
----
76+
shared_preload_libraries = 'liboracle_parser, ivorysql_ora, gb18030_2022, pgnodemx'
77+
----
78+
79+
For a non-Kubernetes host, disable Downward API access to avoid unnecessary startup warnings:
80+
81+
[source,ini]
82+
----
83+
pgnodemx.kdapi_enabled = off
84+
----
85+
86+
The other relevant defaults are:
87+
88+
[source,ini]
89+
----
90+
pgnodemx.cgroup_enabled = on
91+
pgnodemx.containerized = off
92+
pgnodemx.cgrouproot = '/sys/fs/cgroup'
93+
pgnodemx.kdapi_path = '/etc/podinfo'
94+
----
95+
96+
Restart IvorySQL after changing `shared_preload_libraries`, then create the extension in each database that will expose metrics:
97+
98+
[source,sql]
99+
----
100+
CREATE EXTENSION pgnodemx;
101+
102+
SELECT extversion
103+
FROM pg_extension
104+
WHERE extname = 'pgnodemx';
105+
----
106+
107+
The expected extension version is `1.7`.
108+
109+
== Grant monitoring access
110+
111+
pgnodemx checks that callers belong to the predefined `pg_monitor` role. Grant that role to a dedicated monitoring login rather than allowing the monitoring agent to connect as a superuser.
112+
113+
[source,sql]
114+
----
115+
CREATE ROLE node_monitor LOGIN PASSWORD 'replace-with-a-strong-password';
116+
GRANT pg_monitor TO node_monitor;
117+
GRANT CONNECT ON DATABASE monitoring TO node_monitor;
118+
----
119+
120+
Also restrict `pg_hba.conf`, network access, and TLS configuration to the monitoring system.
121+
122+
== Query metrics
123+
124+
=== Extension and runtime information
125+
126+
[source,sql]
127+
----
128+
SELECT pgnodemx_version();
129+
SELECT exec_path();
130+
SELECT openssl_version();
131+
SELECT cgroup_mode();
132+
----
133+
134+
=== Memory, CPU, disk, and network information
135+
136+
[source,sql]
137+
----
138+
SELECT * FROM proc_meminfo()
139+
WHERE key IN ('MemTotal', 'MemAvailable');
140+
141+
SELECT * FROM proc_loadavg();
142+
SELECT * FROM proc_cputime();
143+
SELECT * FROM proc_diskstats();
144+
SELECT * FROM proc_network_stats();
145+
----
146+
147+
=== IvorySQL process information
148+
149+
[source,sql]
150+
----
151+
SELECT * FROM proc_pid_cmdline();
152+
SELECT * FROM proc_pid_io();
153+
SELECT * FROM proc_pid_stat();
154+
----
155+
156+
The functions read the operating-system view visible to the IvorySQL process. In a container, results therefore describe the namespaces and mounted filesystems made available to that container.
157+
158+
== Oracle-compatible mode
159+
160+
The extension remains available after a session changes mode:
161+
162+
[source,sql]
163+
----
164+
SET ivorysql.compatible_mode = oracle;
165+
166+
SELECT pgnodemx_version() FROM dual;
167+
SELECT val FROM proc_meminfo() WHERE key = 'MemTotal';
168+
SELECT count(*) FROM proc_diskstats();
169+
----
170+
171+
All three queries completed successfully in the IvorySQL 5.4 validation.
172+
173+
== Limitations and security
174+
175+
* pgnodemx 1.7 supports cgroup v1 (`legacy`) and cgroup v2 (`unified`), but not the mixed `hybrid` layout. `/proc` functions remain usable when cgroup metric access is unavailable.
176+
* Kubernetes functions return NULL or no rows when `pgnodemx.kdapi_path` is absent; disable the facility outside Kubernetes.
177+
* Host files can contain sensitive process, mount, and environment information. Grant `pg_monitor` only to trusted monitoring roles.
178+
* Metric collection adds SQL and filesystem-read workload. Set an appropriate polling interval and select only required columns/functions.
179+
* This extension is Linux-specific and depends on the files exposed by the kernel, container runtime, and security policy.
180+
181+
For the complete function list, see the https://access.crunchydata.com/documentation/pgnodemx/1.7/[pgnodemx 1.7 documentation].

0 commit comments

Comments
 (0)