pg_stat_backtrace

概览

GitHub v1.0.0; C PGXS extension using ptrace(PTRACE_SEIZE) and libunwind; Linux only; runtime may need kernel.yama.ptrace_scope=0

版本

构建

您可以使用 pig build 命令构建 pg_stat_backtrace 扩展的 DEB 包：

pig build pkg pg_stat_backtrace         # 构建 DEB 包

安装

您可以直接安装 pg_stat_backtrace 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

• 安装
• pig
• dnf
• apt

pig install pg_stat_backtrace;          # 当前活跃 PG 版本安装

pig ext install -y pg_stat_backtrace -v 18  # PG 18
pig ext install -y pg_stat_backtrace -v 17  # PG 17
pig ext install -y pg_stat_backtrace -v 16  # PG 16
pig ext install -y pg_stat_backtrace -v 15  # PG 15
pig ext install -y pg_stat_backtrace -v 14  # PG 14

dnf install -y pg_stat_backtrace_18       # PG 18
dnf install -y pg_stat_backtrace_17       # PG 17
dnf install -y pg_stat_backtrace_16       # PG 16
dnf install -y pg_stat_backtrace_15       # PG 15
dnf install -y pg_stat_backtrace_14       # PG 14

apt install -y postgresql-18-pg-stat-backtrace   # PG 18
apt install -y postgresql-17-pg-stat-backtrace   # PG 17
apt install -y postgresql-16-pg-stat-backtrace   # PG 16
apt install -y postgresql-15-pg-stat-backtrace   # PG 15
apt install -y postgresql-14-pg-stat-backtrace   # PG 14

创建扩展：

CREATE EXTENSION pg_stat_backtrace;

用法

来源：pg_stat_backtrace upstream README、upstream changelog、本地源码归档 pg_stat_backtrace-1.0.0.tar.gz。

pg_stat_backtrace 用于捕获或记录同一 Linux 主机上 PostgreSQL 后端进程或辅助进程的 C 层调用栈。它使用 ptrace(PTRACE_SEIZE) 和 libunwind；不需要 shared_preload_libraries，也不会向目标进程发送 SIGSTOP。

CREATE EXTENSION pg_stat_backtrace;

捕获调用栈

先从 PostgreSQL 视图中找到目标进程，再调用 pg_get_backtrace(pid)：

SELECT pid, backend_type, state, wait_event, query
FROM pg_stat_activity
WHERE backend_type = 'autovacuum worker';

SELECT pg_get_backtrace(123456);

返回文本采用类似 pstack(1) 的格式：

#0  0x00007f5e6c1a4d9e in __epoll_wait+0x4e
#1  0x000055f1a8c2a213 in WaitEventSetWaitBlock+0x83
#2  0x000055f1a8c2a04e in WaitEventSetWait+0xfe

写入服务器日志

如果希望结果进入常规 PostgreSQL 日志管道，可以使用 pg_log_backtrace(pid)：

SELECT pg_log_backtrace(123456);

SELECT pid, pg_log_backtrace(pid)
FROM pg_stat_activity
WHERE backend_type = 'walsender';

该函数成功时返回 true。

权限

默认情况下，两个函数都会从 PUBLIC 撤销执行权限。只应把访问权授予可信的监控角色：

GRANT EXECUTE ON FUNCTION pg_get_backtrace(int) TO observability;
GRANT EXECUTE ON FUNCTION pg_log_backtrace(int) TO observability;

C 代码仍会执行目标检查：

• 超级用户可以定位该实例中的任意 PostgreSQL 进程，包括 walwriter、checkpointer、walsender、autovacuum worker、startup、archiver 等辅助进程。
• 非超级用户只能定位由其成员角色拥有的普通后端进程。
• 辅助进程没有角色所有权，因此非超级用户总会被拒绝。
• 非超级用户不能定位超级用户拥有的后端，即使存在角色成员关系也不行。

输入与错误行为

两个函数都是 VOLATILE STRICT PARALLEL RESTRICTED。

SELECT pg_get_backtrace(NULL::int);  -- NULL, no ptrace attempt
SELECT pg_log_backtrace(NULL::int);  -- NULL, no ptrace attempt
SELECT pg_get_backtrace(0);          -- WARNING, then NULL
SELECT pg_log_backtrace(-1);         -- WARNING, then false

自我定位会被拒绝，因为 Linux 进程不能 ptrace 自己：

SELECT pg_get_backtrace(pg_backend_pid());

运行注意事项

• 版本 1.0.0 支持 PostgreSQL 14-18。上游 1.0.0 同时声明兼容 PostgreSQL 19。
• 该扩展仅支持 Linux，构建和运行时都依赖 libunwind / libunwind-ptrace。
• 在启用了 Yama ptrace 限制的主机上，后端之间互相捕获调用栈可能需要设置 kernel.yama.ptrace_scope = 0。
• 展开调用栈期间，目标进程会被短暂暂停。不要在繁忙主库上对 walwriter、checkpointer 或同步复制 walsender 等关键进程进行紧密循环调用。
• Linux 对每个目标进程只允许一个 tracer。多个会话同时定位同一个 PID 时可能因 EPERM 失败；等待正在进行的调用结束后重试。