error_log() 和 var_dump() 不够用，因它们缺乏时间戳、层级、上下文ID及JSON结构，导致调试时无法过滤、关联或追踪请求链路；结构化日志以固定字段JSON格式输出，支持PhpStorm自动高亮、折叠、按trace_id聚合。
为什么 error_log() 和 var_dump() 不够用
结构化日志不是“更高级的打印”，而是把调试信息变成可过滤、可关联、可时序追踪的数据。当你在 PhpStorm 中单步调试一个异步回调或 Laravel 的事件监听器时，var_dump() 输出混在 HTTP 响应里、被缓冲截断、没有上下文 ID，根本无法确认哪次请求触发了哪段逻辑。而 error_log() 默认不带时间戳、无层级、不可分级，tail -f 看着像解码电报。
结构化日志的核心价值在于：每条日志是一行 JSON，字段固定（如 level、message、context、trace_id），PhpStorm 的 Event Log 或终端插件能自动高亮错误、折叠堆栈、按 trace_id 聚合整条链路。
用 monolog/monolog 写出 PhpStorm 可识别的结构化日志
Monolog 是 PHP 事实标准，但默认输出是格式化文本，不是 JSON。必须显式配置 JsonFormatter，且关键点在于：关闭 HTML 实体转义，否则 PhpStorm 解析 JSON 时会失败。
- 安装：
composer require monolog/monolog - 初始化时指定
JsonFormatter::BATCH_MODE_JSON模式，避免换行符干扰：
$handler = new StreamHandler('php://stderr');
$handler->setFormatter(new JsonFormatter(JsonFormatter::BATCH_MODE_JSON));
$logger = new Logger('app');
$logger->pushHandler($handler);
这样输出就是纯 JSON 行，例如：{"message":"User loaded","context":{"id":123,"role":"admin"},"level":200,"level_name":"INFO","channel":"app","datetime":"2024-06-12T10:22:33.123456+00:00","extra":{}}
立即学习“PHP免费学习笔记（深入）”；
PhpStorm 的 Terminal 或 Run Console 会自动识别这种格式，并允许点击 context.id 跳转到对应变量定义（需开启 Settings > Editor > General > Console > Enable language injection）。
在 PhpStorm 中实时过滤和关联结构化日志
光有 JSON 不够，得让 IDE “看懂”它。关键是启用 Log Viewer 插件（内置，无需安装），并配置正确的日志路径和解析规则。
- 打开
View > Tool Windows > Log Viewer - 点击
+添加日志文件，路径填storage/logs/laravel.log（Laravel）或你自定义的php://stderr重定向目标 - 右键日志行 →
Configure Log Format→ 选择JSON，并确保Timestamp field设为datetime - 之后就能用
filter:level=ERROR或filter:context.trace_id="abc123"实时筛选
注意：如果日志中含嵌套对象（如 context.user.name），PhpStorm 默认不展开。需在 Log Viewer 设置中勾选 Expand nested JSON objects，否则搜索 context.user 会无结果。
避免 trace_id 泄露和日志膨胀的实操边界
结构化日志容易陷入两个极端：要么所有请求都打满 debug 级别，拖垮性能；要么只在生产环境开 warning，调试时又抓瞎。折中方案是分环境 + 按需注入。
- 开发环境：用
RequestIDProcessor自动注入trace_id，但仅对DEBUG和INFO级别生效 - 敏感字段（如
password、token）必须在写入前从context中 unset，Monolog 不做脱敏 - 不要在循环内调用
$logger->info()，JSON 序列化有开销；改用$logger->debug('Loop iteration {i}', ['i' => $i])，Monolog 延迟渲染
最常被忽略的是：本地开发时用 php://stderr 输出 JSON，但没在 PhpStorm 的 Run Configuration 中设置 Redirect input/output to console，导致日志根本不出现在 IDE 控制台 —— 它悄悄流进系统 syslog 了。
