PostgreSQL New

信息

PostgreSQL New 使用 SmartAgent + Integration Agent 采集 PostgreSQL 指标及 DBM 数据，支持分析 Query 性能、执行计划、活动会话、Schema 元数据以及数据库与应用服务的关联。

快速上手

安装 SmartAgent 10.3.0 或更高版本，并启用 Integration Agent。
安装 postgresql-contrib，创建监控用户，并按 PostgreSQL 版本完成授权。
启用 pg_stat_statements，设置 shared_preload_libraries 与 SQL 长度参数，并重启数据库。
在目标数据库创建 bonree.explain_statement，编辑 ${APM_HOME}/integration/conf/integration.d/postgres.d/conf.yaml，并将 dbm 设置为 true。
运行自检命令确认统计视图与执行计划函数可访问，然后进入 基础设施 → 数据库 查看实例及 Query 数据。

注意

此页面介绍新的 Integration Agent 接入方式。现有 PostgreSQL Legacy 使用 SmartGate/Exporter，部署与配置流程不同，请勿混用。

1. 支持范围

数据库支持版本：

PostgreSQL 9.6/13.22/17.10/18.0

注：其他数据库版本理论上支持，需要自行验证。

数据库端前置条件

数据库侧需安装 postgresql-contrib扩展插件集合包，主要会用到pg_stat_statements性能监控插件（多数发行版默认已含 pg_stat_statements 扩展）

支持系统架构：

Linux x86_64（amd64），需glibc ≥2.17；已验证版本：CentOS 7、CentOS 8、Ubuntu 21.10

注：其他系统版本理论上支持，需要自行验证

探针支持版本：

SmartAgent 10.3.0+

2. 部署

安装 SmartAgent 探针，并开启 integration-agent

3. PostgreSQL 端配置：用户与权限

3.1 创建 bonree 用户

'bonree'：用于插件探针访问数据库的只读用户；<UNIQUEPASSWORD>：设置的数据库访问密码。

以超级用户连接目标库（默认连 postgres 库）：

psql -h <HOST> -p 5432 -U postgres -d postgres

CREATE USER bonree WITH PASSWORD '<UNIQUEPASSWORD>';

-- 建议限制最大连接数，避免 Agent 重启时连接风暴
ALTER ROLE bonree CONNECTION LIMIT 5;

检查是否可以访问：

psql -h <HOST> -p 5432 -U bonree -d postgres -c "SELECT version();"

3.2 基础授权

3.2.1 PostgreSQL 15+（15 / 16 / 17 / 18）

PG 15 起默认角色不再自动继承成员角色权限，需显式开启 INHERIT：

ALTER ROLE bonree INHERIT;

CREATE SCHEMA IF NOT EXISTS bonree;
GRANT USAGE ON SCHEMA bonree TO bonree;
GRANT USAGE ON SCHEMA public TO bonree;

GRANT pg_monitor TO bonree;
GRANT SELECT ON pg_stat_database TO bonree;

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

3.2.2 PostgreSQL （10 / 11 / 12 / 13 / 14）

CREATE SCHEMA IF NOT EXISTS bonree;
GRANT USAGE ON SCHEMA bonree TO bonree;
GRANT USAGE ON SCHEMA public TO bonree;

GRANT pg_monitor TO bonree;
GRANT SELECT ON pg_stat_database TO bonree;

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

3.2.3 PostgreSQL 9.6

PostgreSQL 9.6 无 pg_monitor 角色，无法读取完整会话与 SQL 统计，需用 SECURITY DEFINER （函数创建者的权限执行内部 SQL）：

CREATE SCHEMA IF NOT EXISTS bonree;
GRANT USAGE ON SCHEMA bonree TO bonree;
GRANT USAGE ON SCHEMA public TO bonree;

GRANT SELECT ON pg_stat_database TO bonree;
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 读取完整 pg_stat_activity / pg_stat_statements
CREATE OR REPLACE FUNCTION bonree.pg_stat_activity()
RETURNS SETOF pg_stat_activity AS
$$ SELECT * FROM pg_catalog.pg_stat_activity; $$
LANGUAGE sql SECURITY DEFINER;

CREATE OR REPLACE FUNCTION bonree.pg_stat_statements()
RETURNS SETOF pg_stat_statements AS
$$ SELECT * FROM pg_stat_statements; $$
LANGUAGE sql SECURITY DEFINER;

权限 / 角色	作用
`INHERIT`（PG 15+）	允许角色继承 `pg_monitor` 等成员角色的权限， PG 15 默认 `NOINHERIT`，不开启会导致授权无效
`pg_monitor`（PG 10+）	读 `pg_stat_*`、锁视图、活动会话等系统统计
`SELECT ON pg_stat_database`	数据库级累计指标（提交/回滚、块读写等）
`CREATE EXTENSION pg_stat_statements`	启用语句级性能统计视图，DBM 语句指标
`USAGE ON SCHEMA bonree`	允许用户进入这个bonree schema

3.3 DBM 执行计划采集：创建`bonree.explain_statement` 函数

PostgreSQL 没有 MySQL 那样的内置 EXPLAIN 存储过程，需在每个监控库创建 SECURITY DEFINER 函数。

CREATE OR REPLACE FUNCTION bonree.explain_statement(
   l_query TEXT,
   OUT explain JSON
)
RETURNS SETOF JSON AS
$$
DECLARE
   curs REFCURSOR;
   plan JSON;
BEGIN
   SET TRANSACTION READ ONLY;
   OPEN curs FOR EXECUTE pg_catalog.concat('EXPLAIN (FORMAT JSON) ', l_query);
   FETCH curs INTO plan;
   CLOSE curs;
   RETURN QUERY SELECT plan;
END;
$$
LANGUAGE 'plpgsql'
RETURNS NULL ON NULL INPUT
SECURITY DEFINER;

GRANT USAGE ON SCHEMA bonree TO bonree;
GRANT EXECUTE ON FUNCTION bonree.explain_statement(TEXT) TO bonree;

SECURITY DEFINER说明 ：函数以定义者（通常为 superuser）身份执行 EXPLAIN，调用方 bonree 只需 EXECUTE 即可拿到执行计划，无需直接授权业务表。

3.3.1 可选：列级统计 `bonree.column_statistics`

若需开启 collect_column_statistics，在每个监控库额外创建：

CREATE OR REPLACE FUNCTION bonree.column_statistics()
RETURNS TABLE (
    schemaname name, tablename name, attname name,
    n_distinct real, avg_width integer, null_frac real,
    inherited boolean, correlation real, most_common_freqs real[]
) AS
$$ SELECT schemaname, tablename, attname, n_distinct, avg_width, null_frac,
          inherited, correlation, most_common_freqs
     FROM pg_catalog.pg_stats
    WHERE schemaname NOT IN ('pg_catalog', 'information_schema'); $$
LANGUAGE sql
SECURITY DEFINER
SET search_path = pg_catalog, pg_temp;

GRANT EXECUTE ON FUNCTION bonree.column_statistics() TO bonree;

Agent 侧配置开启：

instances:
  - dbm: true
    ...
    collect_column_statistics:
      enabled: true

3.4 `postgresql.conf` 配置（DBM 采集需要）

在数据库配置 postgresql.conf 中设置以下参数，修改后需重启数据库生效

# 必需：preload pg_stat_statements 扩展
shared_preload_libraries = 'pg_stat_statements'

# 必需：避免长 SQL 在 pg_stat_activity 中被截断（默认 1024）
track_activity_query_size = 4096

# 可选：为执行计划与 pg_stat_statements 提供 I/O 计时
# track_io_timing = on

# 可选：跟踪存储过程/函数内的语句
# pg_stat_statements.track = all

# 可选：增大 pg_stat_statements 归一化 SQL 缓存上限（默认 5000；高并发、SQL 种类多时可调大）
# pg_stat_statements.max = 10000

# 可选：设为 off 则只跟踪 SELECT / UPDATE / DELETE，不跟踪 PREPARE、EXPLAIN 等 utility 命令
# pg_stat_statements.track_utility = off

3.5 自检脚本

检查数据库权限： PostgreSQL 10+

export PGPASSWORD='<UNIQUEPASSWORD>'

psql -h <HOST> -p 5432 -U bonree -d postgres -A \
  -c "SELECT * FROM pg_stat_database LIMIT 1;" \
  && echo "pg_stat_database - OK" \
  || echo "pg_stat_database - FAIL"

psql -h <HOST> -p 5432 -U bonree -d postgres -A \
  -c "SELECT * FROM pg_stat_activity LIMIT 1;" \
  && echo "pg_stat_activity - OK" \
  || echo "pg_stat_activity - FAIL"

psql -h <HOST> -p 5432 -U bonree -d postgres -A \
  -c "SELECT * FROM pg_stat_statements LIMIT 1;" \
  && echo "pg_stat_statements - OK" \
  || echo "pg_stat_statements - FAIL"

psql -h <HOST> -p 5432 -U bonree -d postgres -A \
  -c "SELECT bonree.explain_statement('SELECT 1');" \
  && echo "explain_statement - OK" \
  || echo "explain_statement - FAIL"

PostgreSQL 9.6 将 pg_stat_activity / pg_stat_statements 检查改为：

psql ... -c "SELECT * FROM bonree.pg_stat_activity() LIMIT 1;"
psql ... -c "SELECT * FROM bonree.pg_stat_statements() LIMIT 1;"

期望输出：

四条检查均返回 OK。
SHOW shared_preload_libraries; 含 pg_stat_statements。
SHOW track_activity_query_size; ≥ 4096。

4. Agent 端配置：`postgres.d/conf.yaml`

4.1 最小配置

OS	路径
Linux	`${APM_HOME}/integration/conf/integration.d/postgres.d/conf.yaml`

instances:
  - host: 127.0.0.1         # 连接数据库的主机 IP 或域名；
    port: 5432              # 连接端口，PostgreSQL 默认为 5432
    username: bonree        # 探针访问数据库的用户名，需与数据库端配置一致
    password: '<PASSWORD>'  # 用户密码；含特殊字符时建议加引号
    dbm: false              # true：开启数据库性能监控，false：关闭，默认 false
    # tags:
    #   - cluster:cluster_name        # 上报数据时携带的自定义集群标签
  # 可配置多个实例，例如：
  # - host: 10.1.1.1
  #   port: 5432
  #   username: bonree
  #   password: '<PASSWORD>'
  #   dbname: myapp           # 可选配置，默认postgres
  #   dbm: true
  #   tags:
  #     - cluster:prod-pg-cluster

4.2 开启 DBM 与 Schema 采集

instances:
  - host: 127.0.0.1
    port: 5432
    username: bonree
    password: '<PASSWORD>'
    dbm: true                         # 开启 DBM 采集
    # tags:
    #   - cluster:cluster_name

    collect_schemas:
      enabled: true                   # 大库慎开；会采集库/表/列/索引元数据，默认 false

4.3 配置生效与验证

配置热生效，修改后如未生效，可重启 SmartAgent（执行bash命令：systemctl restart bonree-agent）。

常见场景

新接入 PostgreSQL 并开启 Query 分析

启用 pg_stat_statements、完成版本对应的用户授权，并在 Agent 实例中设置 dbm: true，再使用自检脚本确认数据可采集。

需要采集执行计划或 Schema 元数据

在每个目标数据库创建 bonree.explain_statement；需要列级统计时再创建 bonree.column_statistics 并开启 collect_column_statistics。

需要将 Query 关联到应用服务或调用链

在 ONE 平台创建数据库端到端关联规则。高频 Prepared Statement 场景应先评估 ApplicationName 更新和额外网络往返的影响。

5. 服务、调用链关联

应用服务（比如java服务）访问受监控的数据库时，可以在Bonree ONE平台开启不同传播模式，开启/关闭注入SQL注释达到服务或调用链的关联/取消关联。

注：当前关联仅支持受java探针监控的java服务，后续会支持其他探针监控的服务

5.1 配置步骤

进入Bonree ONE平台首页->部署配置->规则配置->数据采集->数据库->创建（创建端到端关联规则）->选择服务范围->选择数据库类型->选择传播模式（即关联模式，默认是关闭，可选关闭、Full、Service三种模式）

5.2 传播模式说明

关闭模式：代表不注入任何注释，数据库功能无法追溯到上游服务以及调用链。
Service模式：代表仅在SQL注释中注入服务级信息，提供基础的关联分析能力，不支持关联调用链。
Full模式：代表注入完整服务和Trace信息，数据库功能可以追溯到上游服务以及调用链等相关信息。

5.3 注意事项

关联前提：并非所有语句都能关联。仅当 SQL 注释成功写入数据库性能表后，才能采集到关联信息（例如长耗时、阻塞类语句）。
性能影响：SQL 注释本身对网络传输、解析与 CPU 开销通常较小；但 Full 模式可能影响执行计划缓存（如缓存不命中、硬解析），请谨慎开启。
Prepared Statement 注入：仅对 PostgreSQL 生效。开启后，每次 PreparedStatement 执行前都会通过连接级 ApplicationName 携带 Trace 信息。该操作可能产生额外的 session 属性更新和网络往返，在高频 SQL 场景下增加执行延迟，建议评估性能后开启。
注释位置：用于复杂环境的特殊兼容；默认在 SQL 之前注入注释。

快速上手​

1. 支持范围​

数据库支持版本：​

支持系统架构：​

探针支持版本：​

2. 部署​

3. PostgreSQL 端配置：用户与权限​

3.1 创建 bonree 用户​

3.2 基础授权​

3.2.1 PostgreSQL 15+（15 / 16 / 17 / 18）​

3.2.2 PostgreSQL （10 / 11 / 12 / 13 / 14）​

3.2.3 PostgreSQL 9.6​

3.3 DBM 执行计划采集：创建bonree.explain_statement 函数​

3.3.1 可选：列级统计 bonree.column_statistics​

3.4 postgresql.conf 配置（DBM 采集需要）​

3.5 自检脚本​

4. Agent 端配置：postgres.d/conf.yaml​

4.1 最小配置​

4.2 开启 DBM 与 Schema 采集​

4.3 配置生效与验证​

常见场景​

5. 服务、调用链关联​

5.1 配置步骤​

5.2 传播模式说明​

5.3 注意事项​