用 backtrace_functions 抓 PostgreSQL 内部函数的 C 调用栈

预计阅读时间：10 分钟

PostgreSQL 报出一个内部错误——ERROR: cache lookup failed for relation 12345——日志里只有这一行，没有上下文调用链，没有线索告诉你是哪条路径触发了这个异常。排查这类问题往往要靠猜，或者翻源码逐行推理。

从 PostgreSQL 13 起，有一个低调的 GUC 参数能直接在日志里打出 C 级别的栈回溯：backtrace_functions。指定函数名，PostgreSQL 在执行到该函数时自动把完整调用栈写进日志。Christophe Pettus 在他的分享里专门讲解了这个参数的用法——它不是日常调优工具，而是关键时刻的"断点日志"。

参数机制：按函数名触发栈回溯

backtrace_functions 是一个字符串类型的 GUC，接受逗号分隔的 C 函数名列表。当 PostgreSQL 执行到列表中的任意一个函数，它会在日志中输出该函数的完整 C 调用栈，格式类似：

2024-03-15 10:22:33 UTC LOG:  backtrace:
    postgres: SearchSysCache1+0x45
    postgres: GetSysCacheOid+0x1a
    postgres: get_rel_relkind+0x2c
    postgres: relation_open+0x18
    postgres: ExecOpenScanRelation+0x3f
    ...

每一行是二进制中的符号名加偏移量，直接对应 PostgreSQL 源码中的 C 函数。拿到这个栈，你就能从 src/backend/ 目录下逐级追踪调用路径，定位到底是哪个上层逻辑触发了异常函数。

关键限制：这个参数只在 PostgreSQL 编译时启用了 backtrace 支持的前提下才生效。大多数主流发行版（Debian、RHEL 的官方包）默认已启用；如果你从源码自行编译，需要确认 glibc 或 libexecinfo 可用，且 configure 时没有禁用相关选项。

常见调试场景与函数选择

不是所有函数都值得追踪。backtrace_functions 的设计意图是针对那些"只在异常情况下才被调用"的内部函数——比如错误报告、缓存查找失败、断言触发等。以下是几个实用组合：

缓存查找类错误——SearchSysCache1、SearchSysCache2、SearchSysCache3、SearchSysCache4 是系统目录缓存查找的入口。当日志出现 cache lookup failed 时，把它们加入列表，下次触发就能看到是哪条 SQL 执行路径走到了缺失的 catalog 行。

断言失败——ExceptionalCondition 是 PG 所有 Assert() 宏失败时的统一入口。断言崩溃通常只留一个 core dump，加上这个函数的回溯，日志里就有了完整调用链，不必依赖 core 文件分析。

通用错误入口——errstart 是 elog() / ereport() 的底层启动函数。如果你想追踪所有 ERROR 级别消息的来源，可以把它加进去。但注意：这会产生大量日志输出，因为每条 ERROR 都会触发回溯，适合定向排查而非长期开启。

实操：从报错到栈回溯

下面用一个完整流程演示如何用 backtrace_functions 定位 cache lookup failed 的根因。

第一步：确认当前 PostgreSQL 版本和 backtrace 支持

# 检查版本（需要 >= 13）
psql -c "SELECT version();"

# 检查 backtrace_functions 参数是否可见
psql -c "SHOW backtrace_functions;"

如果 SHOW 命令返回空字符串（默认值），说明参数存在且可用。如果报错说参数不存在，说明你的版本低于 13 或编译时未包含 backtrace 支持。

第二步：设置要追踪的函数

# 在会话级别设置——只影响当前连接，不污染全局日志
psql -c "SET backtrace_functions = 'SearchSysCache1,SearchSysCache2,SearchSysCache3,SearchSysCache4';"

也可以在 postgresql.conf 中全局设置，但建议只在排查期间临时开启：

# postgresql.conf — 临时调试用，排查完毕后务必清空
backtrace_functions = 'SearchSysCache1,SearchSysCache2,SearchSysCache3,SearchSysCache4'

修改后需要 reload：

pg_ctl reload -D /var/lib/postgresql/data

第三步：复现问题并查看日志

触发原来报错的 SQL，然后在 PostgreSQL 日志中搜索 backtrace 关键词：

# 查看最近的栈回溯输出
grep -A 20 "backtrace:" /var/log/postgresql/postgresql-16-main.log | tail -40

输出示例：

LOG:  backtrace:
    postgres: SearchSysCache1+0x45
    postgres: GetSysCacheOid+0x1a
    postgres: get_rel_relkind+0x2c
    postgres: relation_open+0x18
    postgres: ExecOpenScanRelation+0x3f
    postgres: ExecInitIndexScan+0x112
    postgres: ExecInitNode+0x5a
    postgres: InitPlan+0x2e1
    postgres: standard_ProcessUtility+0x4c8

从这个栈可以清晰看到：一条 CREATE INDEX 或类似 DDL 命令（standard_ProcessUtility）在初始化索引扫描节点（ExecInitIndexScan）时打开关系（relation_open），查询 relkind（get_rel_relkind），最终在系统缓存查找（SearchSysCache1）时失败。根因指向 relation 对应的 pg_class 行缺失——可能是并发 DROP TABLE 导致的竞态。

第四步：排查完毕后清空参数

# 会话级别：断开连接即恢复默认
# 全局级别：清空配置并 reload
psql -c "ALTER SYSTEM RESET backtrace_functions;"
pg_ctl reload -D /var/lib/postgresql/data

长期开启 backtrace_functions 会拖慢所有命中指定函数的调用路径——每次执行都额外打一次栈回溯，对高频函数（如 SearchSysCache*）影响尤其明显。排查结束必须关掉。

符号解析：从偏移量到源码行号

日志里的 SearchSysCache1+0x45 是二进制偏移，要映射到源码具体行号，需要用 addr2line：

# 找到 postgres 二进制路径
which postgres
# 通常在 /usr/lib/postgresql/16/bin/postgresql 或类似位置

# 解析偏移量到源码行号
addr2line -e /usr/lib/postgresql/16/bin/postgres -f -p 0x45

注意：addr2line 接受的是绝对地址，而日志输出的是函数内偏移。你需要先从二进制中获取函数的起始地址，再加上偏移量：

# 获取函数起始地址
nm /usr/lib/postgresql/16/bin/postgres | grep SearchSysCache1

# 假设输出: 00000000004a3c20 T SearchSysCache1
# 加上偏移 0x45 → 绝对地址 0x4a3c65
addr2line -e /usr/lib/postgresql/16/bin/postgres -f -p 0x4a3c65

输出类似：

SearchSysCache1 at /usr/src/postgresql-16/src/backend/utils/cache/syscache.c:142

直接定位到源码行，排查效率大幅提升。

使用边界与注意事项

关注点	说明
性能开销	每次命中函数都打栈回溯，高频函数会显著拖慢系统。只在排查窗口开启。
日志膨胀	`errstart` 等通用入口会为每条 ERROR 产生 10-20 行栈输出，磁盘占用需留意。
编译依赖	需要平台支持 backtrace（glibc 的 `backtrace()` 函数或 libexecinfo）。部分嵌入式/最小化构建可能缺失。
符号信息	生产环境若剥离了符号（strip），栈回溯只剩地址，需配合 `addr2line` 和未剥离的二进制做离线解析。保留一份未 strip 的 postgres 二进制是值得的。
版本要求	PostgreSQL 13+ 才有此参数。12 及更早版本无法使用。

排查清单

遇到难以定位的内部错误时，按以下步骤操作：

确认 PG 版本 ≥ 13，SHOW backtrace_functions 可用。
根据错误类型选择目标函数：cache lookup failed → SearchSysCache*；断言 → ExceptionalCondition；通用 ERROR → errstart。
在会话级别 SET backtrace_functions，或临时写入 postgresql.conf 并 reload。
复现触发条件，从日志中提取 backtrace: 段。
用 addr2line 将偏移映射到源码行号（需保留未 strip 的二进制）。
根据调用链定位根因，修复或规避问题。
立即清空参数并 reload——不要让调试配置留在生产环境。

backtrace_functions 是 PostgreSQL 给运维和开发者的一个"日志断点"：不需要改代码、不需要重启、不需要 attach debugger，一条配置就能让内部函数自己交代调用链。代价是性能开销，所以它不是常驻工具，而是关键时刻打开、用完即关的排查利器。