PHP Throwable getTraceAsString 线上记录异常链：保留调用栈与隐藏敏感参数

线上接口只留下一句“请求失败”时，真正难查的不是异常有没有发生，而是调用链和请求上下文没有留下来。PHP 里的 Throwable 可以统一接住 Error 与 Exception，再用 getTraceAsString() 保存可读调用栈；但原始参数可能含有令牌、密码或手机号，不能不加筛选地写入日志。

推荐把异常消息、文件行号和字符串调用栈作为基础证据，再从 getTrace() 生成经过字段过滤的结构化上下文，最后交给 error_log() 输出；不要把完整异常对象或未经处理的参数直接落盘。

先划清 Throwable 日志要留下什么

一个可复查的异常记录，至少需要异常类型、消息、发生文件、行号和调用链。Throwable 接口提供了这些入口：getMessage() 说明发生了什么，getFile() 与 getLine() 定位源代码，getTraceAsString() 则把调用栈压成一段文本。

这段文本的优点是直接、稳定，适合先写进普通错误日志；它的缺点也很明确：不方便按函数名或参数检索，更不能替代脱敏后的业务上下文。日志处理可以先把人读的证据保留下来，再把允许检索的字段单独放进数组。

从 catch 到 error_log 的最小安全链路

下面的处理器刻意只取稳定的元数据。getTraceAsString() 用来保留调用顺序，getTrace() 则只在需要结构化检索时使用；示例里的 redactTrace() 是本地应用函数，职责是复制并过滤数组，不把原始参数原样写出。

 $frame) {
        if (!isset($frame['args'])) {
            continue;
        }

        $trace[$index]['args'] = array_map(
            static function ($value, $key) use ($hidden) {
                return in_array(strtolower((string) $key), $hidden, true)
                    ? '[redacted]'
                    : $value;
            },
            $frame['args'],
            array_keys($frame['args'])
        );
    }

    return $trace;
}

try {
    handleOrder();
} catch (Throwable $e) {
    $record = [
        'type' => $e::class,
        'message' => $e->getMessage(),
        'file' => $e->getFile(),
        'line' => $e->getLine(),
        'trace' => $e->getTraceAsString(),
        'frames' => redactTrace($e->getTrace()),
    ];

    error_log(json_encode($record, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES));
}

这里的调用链是 catch 捕获 Throwable，调用 getTraceAsString() 和 getTrace()，最后由 error_log 输出。真正的安全边界在 redactTrace()：它先检查 args 是否存在，再按键名替换敏感值。没有参数的栈帧不会被强行补出一个空结构。

为什么不能只保存 getTraceAsString

字符串调用栈适合排查“从哪里走到这里”，但对聚合统计并不友好。例如同一个异常可能来自多个控制器入口，文本日志需要二次解析才能按函数筛选。getTrace() 返回数组后，可以把允许检索的 function、class、file 和脱敏后的 args 变成 JSON 字段。

两种表示应该并存，而不是二选一：getTraceAsString() 负责快速阅读，getTrace() 负责程序化查询，json_encode() 负责把过滤后的结构交给 error_log()。如果日志平台已经会拆 JSON，就不要再把同一份数组拼成一段难以检索的长字符串。

参数是否会出现在调用栈里

官方手册说明，getTrace() 没有像 debug_backtrace() 那样的参数选项；调用参数是否被捕获，与异常发生前的 zend.exception_ignore_args 设置有关。也就是说，不能在 catch 之后才临时决定“不要记录参数”——如果运行环境已经捕获，应用仍要主动过滤；如果没有捕获，就不能假设数组里一定存在 args。

生产环境建议把“日志能否定位问题”和“日志是否暴露秘密”拆成两个验收项。第一项检查异常类型、文件、行号和函数路径；第二项用包含 password、token、authorization 的测试请求确认日志里只出现 [redacted]，而不是原值。

error_log 的落点不要想当然

error_log() 的默认类型是交给 PHP 系统日志机制，实际落点受 error_log 配置和运行环境影响，也可以显式指定文件。应用代码不应该假设容器、FPM 和 CLI 会把日志写到同一个地方；部署验收时要从实际启动方式检查采集路径、文件权限和轮转策略。

另外，不建议在生产响应中直接返回 getTraceAsString()。调用栈包含服务器路径、类名和业务结构，适合内部日志，不适合原样展示给客户端。对外只返回关联编号，内部日志用同一个编号串起异常详情。

常见问题

Throwable 和 Exception 都能调用 getTraceAsString 吗？

可以。Throwable 是统一异常接口，Exception 和 Error 都提供对应实现；在 catch 中使用 Throwable 能覆盖两类可抛出对象。

getTraceAsString 会返回数组吗？

不会，它返回字符串。需要按函数、文件或参数筛选时使用 getTrace()，再对数组做过滤和 JSON 编码。

过滤参数后还要记录调用栈吗？

要。参数过滤解决敏感数据暴露问题，调用栈解决定位问题，两者处理的是不同风险。保留字符串调用栈通常比只保留一组函数名更利于人工复盘。

能不能把异常完整对象传给 error_log？

不建议。应明确抽取类型、消息、文件、行号和过滤后的 trace；完整对象的序列化行为不稳定，也容易把不该进入日志的上下文带进去。

把异常日志验收做成固定清单

先用一条可控异常确认 catch 能拿到 Throwable，再检查 getTraceAsString() 是否包含预期调用顺序；需要结构化检索时核对 getTrace() 和 json_encode() 的结果。最后用模拟令牌和密码跑一次日志检查，确认 error_log() 的实际落点只出现脱敏值。这样既保留了排错证据，也不会把线上日志变成秘密数据的备份。