PostgreSQL auto_explain

一、概述

  auto_explain 插件可以实现在数据库日志中自动记录慢 SQL 执行计划。PostgreSQL 编译安装时使用了 make world & make install-world 命令，则所有内置插件（包括 auto_explain）会默认被安装到数据库中，可直接调用。在 PostgreSQL 中执行 LOAD 'auto_explain'; 若无报错则表明插件已存在。PostgreSQL 主流稳定版本 9.x 及以上均已支持。

二、使用

2.1 session_preload_libraries 调用（用户级别）

--调用
ALTER ROLE u1 SET session_preload_libraries = 'auto_explain';
ALTER ROLE u1 SET auto_explain.log_min_duration = '3s';

--u1 用户新连入数据库的会话，执行超3s的sql将在数据库日志中打印执行计划
2025-05-27 14:01:10.821 CST [3335] LOG:  duration: 4004.207 ms  plan:
        Query Text: SELECT pg_sleep(4);
        Result  (cost=0.00..0.01 rows=1 width=4)

--取消调用
ALTER ROLE u1 set session_preload_libraries = default;
ALTER ROLE u1 set session_preload_libraries = default;

2.2 LOAD 调用（会话级别）

--调用
LOAD 'auto_explain';
set auto_explain.log_min_duration = '3s';

--当前会话，执行超3s的sql将在数据库日志中打印执行计划
2025-05-27 14:15:03.547 CST [3581] LOG:  duration: 4004.732 ms  plan:
        Query Text: SELECT pg_sleep(4);
        Result  (cost=0.00..0.01 rows=1 width=4)

--取消调用
临时调用，退出当前会话即可。

2.3 shared_preload_libraries 调用（全局级别）

--调用(若未配置环境变量$PGDATA替换为postgresql.conf所在实际路径)
cat >> $PGDATA/postgresql.conf << 'eof'
shared_preload_libraries = 'auto_explain'
auto_explain.log_min_duration = '3s'
eof

psql postgres postgres -c 'checkpoint'
pg_ctl restart

--新连入数据库的会话，执行超3s的sql将在数据库日志中打印执行计划
2025-05-27 14:25:30.559 CST [3884] LOG:  duration: 5005.176 ms  plan:
        Query Text: SELECT pg_sleep(5);
        Result  (cost=0.00..0.01 rows=1 width=4)

--取消调用
sed -i '/^shared_preload_libraries = '\''auto_explain'\''/d' $PGDATA/postgresql.conf
sed -i '/^auto_explain.log_min_duration = '\''3s'\''/d' $PGDATA/postgresql.conf

psql postgres postgres -c 'checkpoint'
pg_ctl restart

三、对比

方式	生效范围	是否需要重启	灵活性	适用场景	主要缺点
shared_preload_libraries	全局	是	低	长期全局监控	需重启，可能资源浪费
LOAD	当前会话	否	高	临时调试	手动操作，无法自动化
session_preload_libraries	新会话	否	中	按会话/用户自动启用	仅对新会话生效，参数限制

生产环境长期监控：优先使用 shared_preload_libraries，全局配置过滤条件（如 log_min_duration）减少日志量。
临时诊断：使用 LOAD 命令，灵活且不影响其他会话。
特定用户/应用分析：使用 session_preload_libraries，通过连接参数或角色配置实现按需加载。

四、其他参数介绍

  详情参考官网：https://www.postgresql.org/docs/current/auto-explain.html

• auto_explain.log_min_duration (整数)：控制执行计划日志记录的最小语句执行时间（单位：毫秒）。设为 0 时记录所有执行计划。默认值 -1 表示禁用日志记录。例如：设置为 250 时，所有执行时间 ≥250 毫秒的语句将被记录。仅超级用户可修改此参数。

• auto_explain.log_parameter_max_length (整数)：控制查询参数值的日志记录方式。默认值 -1 表示完整记录参数值。0 禁用参数值记录。大于 0 时，将参数值截断为指定字节数。仅超级用户可修改此参数。

• auto_explain.log_analyze (布尔值)：启用后，记录执行计划时输出 EXPLAIN ANALYZE 而非普通 EXPLAIN 结果。默认值：off。仅超级用户可修改此参数。

• auto_explain.log_buffers (布尔值)：控制是否在日志中输出缓冲区使用统计信息（等效于 EXPLAIN 的 BUFFERS 选项）。仅在 auto_explain.log_analyze 启用时生效。默认值：off。仅超级用户可修改此参数。

• auto_explain.log_wal (布尔值)：控制是否在日志中输出 WAL 使用统计信息（等效于 EXPLAIN 的 WAL 选项）。仅在 auto_explain.log_analyze 启用时生效。默认值：off。仅超级用户可修改此参数。

• auto_explain.log_timing (布尔值)：控制是否在日志中输出每个节点的定时信息（等效于 EXPLAIN 的 TIMING 选项）。禁用后可减少系统时钟读取开销，适用于仅需实际行数而非精确时间的场景。仅在 auto_explain.log_analyze 启用时生效。默认值：on。仅超级用户可修改此参数。

• auto_explain.log_triggers (布尔值)：控制是否在日志中包含触发器执行统计信息。仅在 auto_explain.log_analyze 启用时生效。默认值：off。仅超级用户可修改此参数。

• auto_explain.log_verbose (布尔值)：控制是否在日志中输出详细执行计划信息（等效于 EXPLAIN 的 VERBOSE 选项）。默认值：off。仅超级用户可修改此参数。

• auto_explain.log_settings (布尔值)：控制是否在日志中输出影响查询规划的修改后配置选项信息（仅显示与内置默认值不同的选项）。默认值：off。仅超级用户可修改此参数。

• auto_explain.log_format (枚举)：指定 EXPLAIN 输出格式。可选值为 text、xml、json 和 yaml，默认为 text。仅超级用户可修改此参数。

• auto_explain.log_level (枚举)：设置自动解释查询计划的日志级别。有效值为 DEBUG5、DEBUG4、DEBUG3、DEBUG2、DEBUG1、INFO、NOTICE、WARNING 和 LOG，默认为 LOG。仅超级用户可修改此参数。

• auto_explain.log_nested_statements (布尔值)：控制是否记录嵌套语句（函数内部执行的语句）。设为 off 时仅记录顶层查询计划。默认值：off。仅超级用户可修改此参数。

• auto_explain.sample_rate (实数)：设置每个会话中仅解释部分语句的比例。默认值 1 表示解释所有查询。嵌套语句要么全解释，要么全不解释。仅超级用户可修改此参数。