From 0c314290bc55a604d653a2c50f6cfabfe232efd6 Mon Sep 17 00:00:00 2001 From: messere1 <189848840+messere1@users.noreply.github.com> Date: Sun, 9 Aug 2026 20:30:55 +0800 Subject: [PATCH] docs: add pgnodemx integration guide Assisted-by: OpenAI:gpt-5 --- CN/modules/ROOT/nav.adoc | 1 + CN/modules/ROOT/pages/5.0.adoc | 1 + CN/modules/ROOT/pages/5.14.adoc | 181 ++++++++++++++++++++++++++++++++ EN/modules/ROOT/nav.adoc | 1 + EN/modules/ROOT/pages/5.0.adoc | 1 + EN/modules/ROOT/pages/5.14.adoc | 181 ++++++++++++++++++++++++++++++++ 6 files changed, 366 insertions(+) create mode 100644 CN/modules/ROOT/pages/5.14.adoc create mode 100644 EN/modules/ROOT/pages/5.14.adoc diff --git a/CN/modules/ROOT/nav.adoc b/CN/modules/ROOT/nav.adoc index f1a1baab..cc046246 100644 --- a/CN/modules/ROOT/nav.adoc +++ b/CN/modules/ROOT/nav.adoc @@ -52,6 +52,7 @@ *** xref:5.9.adoc[pgrouting] *** xref:5.10.adoc[system_stats] *** xref:5.11.adoc[pgtt] +*** xref:5.14.adoc[pgnodemx] * 监控运维 ** xref:3.2.adoc[日常监控] ** xref:3.3.adoc[日常维护] diff --git a/CN/modules/ROOT/pages/5.0.adoc b/CN/modules/ROOT/pages/5.0.adoc index d9a776d9..2cf4ae31 100644 --- a/CN/modules/ROOT/pages/5.0.adoc +++ b/CN/modules/ROOT/pages/5.0.adoc @@ -22,6 +22,7 @@ IvorySQL 作为一款兼容 Oracle 且基于 PostgreSQL 的高级开源数据库 | 9 | xref:5.9.adoc[pgrouting] | 3.8.0 | 提供地理空间数据的路由计算功能，支持多种算法和数据格式 | 地理空间分析、路径规划、物流优化 | 10 | xref:5.10.adoc[system_stats] | 3.2 | 提供用于访问系统级统计信息的函数 | 系统监控 | 11 | xref:5.11.adoc[pgtt] | 4.5 | 创建、管理与使用Oracle风格临时表 | 业务开发 +| 12 | xref:5.14.adoc[pgnodemx] | 1.7 | 通过 SQL 提供 Linux 节点、进程、文件系统、cgroup 和 Kubernetes 指标 | 数据库主机监控、容器可观测性和容量分析 |==== 这些插件均经过 IvorySQL 团队的测试和适配，确保在 IvorySQL 环境下稳定运行。用户可以根据业务需求选择合适的插件，进一步提升数据库系统的能力和灵活性。 diff --git a/CN/modules/ROOT/pages/5.14.adoc b/CN/modules/ROOT/pages/5.14.adoc new file mode 100644 index 00000000..4cda09ab --- /dev/null +++ b/CN/modules/ROOT/pages/5.14.adoc @@ -0,0 +1,181 @@ +:sectnums: +:sectnumlevels: 5 + += pgnodemx + +== 概述 + +`pgnodemx` 通过 SQL 提供 Linux 操作系统、进程、文件系统、cgroup 和 Kubernetes Downward API 指标。监控程序可以复用数据库连接采集节点及 IvorySQL 进程指标，无需额外部署独立的 exporter 端点。 + +本文在 Ubuntu 22.04 x86_64 环境中使用 IvorySQL 5.4（PostgreSQL 18.4）和 pgnodemx 1.7 完成验证。 + +== 已验证的兼容能力 + +[cols="2,1,3"] +|=== +|能力 |状态 |验证结果 + +|PGXS 编译安装 +|支持 +|pgnodemx 1.7 使用 IvorySQL 5.4 头文件和库成功编译 + +|Linux `/proc` 指标 +|支持 +|内存、磁盘、进程、网络、负载和挂载信息函数均能返回数据 + +|cgroup 检测 +|支持，存在限制 +|`cgroup_mode()` 能识别主机布局；上游 pgnodemx 1.7 不支持读取 hybrid 模式指标 + +|Oracle 兼容会话 +|支持 +|切换兼容模式后，版本、内存和磁盘指标查询均成功 + +|Kubernetes Downward API +|取决于环境 +|配置的 Downward API 卷存在时可用 +|=== + +== 前提条件 + +* IvorySQL 5.4 已安装服务端开发头文件和 PGXS。 +* 目标系统为 Linux，并向 IvorySQL 服务进程提供所需的 `/proc` 和 cgroup 文件。 +* 已安装 C 编译器和 GNU make。 +* pgnodemx 必须使用与 IvorySQL 相同的 OpenSSL 头文件和库进行编译。 + +[IMPORTANT] +不要在 IvorySQL 服务进程中混用不同 OpenSSL 主版本。如果加入 pgnodemx 后启动时报 OpenSSL 未定义符号，应在与 IvorySQL 匹配的构建环境中重新编译 pgnodemx。将另一个不兼容的 OpenSSL 库直接链接进扩展不是安全的解决方案。 + +== 编译安装 + +[source,shell] +---- +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： + +[source,shell] +---- +/usr/local/ivorysql/ivorysql-5/bin/pg_config --version +---- + +== 配置预加载 + +在 `postgresql.conf` 中将 pgnodemx 追加到已有的 `shared_preload_libraries`，不要删除 IvorySQL 原有预加载库。 + +[source,ini] +---- +shared_preload_libraries = 'liboracle_parser, ivorysql_ora, gb18030_2022, pgnodemx' +---- + +非 Kubernetes 主机可以关闭 Downward API 访问，避免无意义的启动警告： + +[source,ini] +---- +pgnodemx.kdapi_enabled = off +---- + +其他相关默认配置如下： + +[source,ini] +---- +pgnodemx.cgroup_enabled = on +pgnodemx.containerized = off +pgnodemx.cgrouproot = '/sys/fs/cgroup' +pgnodemx.kdapi_path = '/etc/podinfo' +---- + +修改 `shared_preload_libraries` 后重启 IvorySQL，并在每个需要提供指标的数据库中创建扩展： + +[source,sql] +---- +CREATE EXTENSION pgnodemx; + +SELECT extversion +FROM pg_extension +WHERE extname = 'pgnodemx'; +---- + +预期扩展版本为 `1.7`。 + +== 授予监控权限 + +pgnodemx 要求调用者属于预定义的 `pg_monitor` 角色。应将该角色授予专用监控账户，不要让监控程序使用超级用户连接。 + +[source,sql] +---- +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 配置限制只有监控系统可以连接。 + +== 查询指标 + +=== 扩展和运行环境信息 + +[source,sql] +---- +SELECT pgnodemx_version(); +SELECT exec_path(); +SELECT openssl_version(); +SELECT cgroup_mode(); +---- + +=== 内存、CPU、磁盘和网络信息 + +[source,sql] +---- +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(); +---- + +=== IvorySQL 进程信息 + +[source,sql] +---- +SELECT * FROM proc_pid_cmdline(); +SELECT * FROM proc_pid_io(); +SELECT * FROM proc_pid_stat(); +---- + +这些函数读取 IvorySQL 进程可见的操作系统视图。在容器中，查询结果反映的是容器可访问的命名空间和挂载文件系统。 + +== Oracle 兼容模式 + +会话切换模式后扩展仍然可用： + +[source,sql] +---- +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 验证通过。 + +== 限制与安全建议 + +* pgnodemx 1.7 支持 cgroup v1（`legacy`）和 cgroup v2（`unified`），不支持混合的 `hybrid` 布局。cgroup 指标不可用时，`/proc` 系列函数仍可使用。 +* `pgnodemx.kdapi_path` 不存在时，Kubernetes 函数返回 NULL 或空结果；非 Kubernetes 环境应关闭此功能。 +* 主机文件可能包含敏感的进程、挂载和环境变量信息，只应向可信监控角色授予 `pg_monitor`。 +* 指标采集会增加 SQL 和文件读取负载，应设置合理轮询间隔，并只查询必要的函数和字段。 +* 该扩展仅适用于 Linux，并依赖内核、容器运行时和安全策略暴露的文件。 + +完整函数列表请参阅 https://access.crunchydata.com/documentation/pgnodemx/1.7/[pgnodemx 1.7 官方文档]。 diff --git a/EN/modules/ROOT/nav.adoc b/EN/modules/ROOT/nav.adoc index 6b480fbd..0f803fbb 100644 --- a/EN/modules/ROOT/nav.adoc +++ b/EN/modules/ROOT/nav.adoc @@ -52,6 +52,7 @@ *** xref:5.9.adoc[pgrouting] *** xref:5.10.adoc[system_stats] *** xref:5.11.adoc[pgtt] +*** xref:5.14.adoc[pgnodemx] * Monitor and O&M ** xref:3.2.adoc[Monitoring] ** xref:3.3.adoc[Maintenance] diff --git a/EN/modules/ROOT/pages/5.0.adoc b/EN/modules/ROOT/pages/5.0.adoc index 42144711..f28e4f2e 100644 --- a/EN/modules/ROOT/pages/5.0.adoc +++ b/EN/modules/ROOT/pages/5.0.adoc @@ -23,6 +23,7 @@ IvorySQL, as an advanced open-source database compatible with Oracle and based o |*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 |*10*| xref:5.10.adoc[system_stats] | 3.2 | Provide functions for accessing system-level statistics. | system monitor |*11*| xref:5.11.adoc[pgtt] | 4.5 | Create, manage and use Oracle-style Global Temporary Tables. | Business development +|*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 |==== 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. diff --git a/EN/modules/ROOT/pages/5.14.adoc b/EN/modules/ROOT/pages/5.14.adoc new file mode 100644 index 00000000..56d8e8d3 --- /dev/null +++ b/EN/modules/ROOT/pages/5.14.adoc @@ -0,0 +1,181 @@ +:sectnums: +:sectnumlevels: 5 + += pgnodemx + +== Overview + +`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. + +This guide was verified with IvorySQL 5.4 (PostgreSQL 18.4) and pgnodemx 1.7 on Ubuntu 22.04 x86_64. + +== Verified compatibility + +[cols="2,1,3"] +|=== +|Capability |Status |Verification + +|PGXS build and installation +|Supported +|pgnodemx 1.7 built against IvorySQL 5.4 headers and libraries + +|Linux `/proc` metrics +|Supported +|Memory, disk, process, network, load, and mount functions returned data + +|cgroup detection +|Supported with limitations +|`cgroup_mode()` detected the host layout; upstream pgnodemx 1.7 does not support hybrid-mode metric reads + +|Oracle-compatible sessions +|Supported +|Version, memory, and disk metric queries succeeded after switching compatibility mode + +|Kubernetes Downward API +|Environment dependent +|Available when the configured Downward API volume exists +|=== + +== Prerequisites + +* IvorySQL 5.4 was built with server development headers and PGXS installed. +* The target is Linux and exposes the required `/proc` and cgroup files to the IvorySQL server process. +* A C compiler and GNU make are installed. +* pgnodemx must be built with the same OpenSSL headers and libraries used by IvorySQL. + +[IMPORTANT] +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. + +== Build and install + +[source,shell] +---- +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 +---- + +Confirm that the selected `pg_config` belongs to IvorySQL 5.4 before compiling: + +[source,shell] +---- +/usr/local/ivorysql/ivorysql-5/bin/pg_config --version +---- + +== Configure preloading + +Append pgnodemx to the existing `shared_preload_libraries` value in `postgresql.conf`. Do not remove IvorySQL's existing preload libraries. + +[source,ini] +---- +shared_preload_libraries = 'liboracle_parser, ivorysql_ora, gb18030_2022, pgnodemx' +---- + +For a non-Kubernetes host, disable Downward API access to avoid unnecessary startup warnings: + +[source,ini] +---- +pgnodemx.kdapi_enabled = off +---- + +The other relevant defaults are: + +[source,ini] +---- +pgnodemx.cgroup_enabled = on +pgnodemx.containerized = off +pgnodemx.cgrouproot = '/sys/fs/cgroup' +pgnodemx.kdapi_path = '/etc/podinfo' +---- + +Restart IvorySQL after changing `shared_preload_libraries`, then create the extension in each database that will expose metrics: + +[source,sql] +---- +CREATE EXTENSION pgnodemx; + +SELECT extversion +FROM pg_extension +WHERE extname = 'pgnodemx'; +---- + +The expected extension version is `1.7`. + +== Grant monitoring access + +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. + +[source,sql] +---- +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; +---- + +Also restrict `pg_hba.conf`, network access, and TLS configuration to the monitoring system. + +== Query metrics + +=== Extension and runtime information + +[source,sql] +---- +SELECT pgnodemx_version(); +SELECT exec_path(); +SELECT openssl_version(); +SELECT cgroup_mode(); +---- + +=== Memory, CPU, disk, and network information + +[source,sql] +---- +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(); +---- + +=== IvorySQL process information + +[source,sql] +---- +SELECT * FROM proc_pid_cmdline(); +SELECT * FROM proc_pid_io(); +SELECT * FROM proc_pid_stat(); +---- + +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. + +== Oracle-compatible mode + +The extension remains available after a session changes mode: + +[source,sql] +---- +SET ivorysql.compatible_mode = oracle; + +SELECT pgnodemx_version() FROM dual; +SELECT val FROM proc_meminfo() WHERE key = 'MemTotal'; +SELECT count(*) FROM proc_diskstats(); +---- + +All three queries completed successfully in the IvorySQL 5.4 validation. + +== Limitations and security + +* 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. +* Kubernetes functions return NULL or no rows when `pgnodemx.kdapi_path` is absent; disable the facility outside Kubernetes. +* Host files can contain sensitive process, mount, and environment information. Grant `pg_monitor` only to trusted monitoring roles. +* Metric collection adds SQL and filesystem-read workload. Set an appropriate polling interval and select only required columns/functions. +* This extension is Linux-specific and depends on the files exposed by the kernel, container runtime, and security policy. + +For the complete function list, see the https://access.crunchydata.com/documentation/pgnodemx/1.7/[pgnodemx 1.7 documentation].