前阵子在把一个电商接口服务从传统PHP迁移到Webman框架时日志这块让我难受了好一阵。Webman框架本身性能很香常驻内存、高并发、协程风格都很顺手但默认的日志方案在请求量上来之后完全不够用夜里告警报了一条数据库连接超时我对着日志看了半天既不知道是哪个用户触发的也分不清是error还是info更糟糕的是日志全部堆在一个文件里终端里还啥都看不到。这篇文章就是我在Webman项目里基于Monolog日志组件做深度优化的完整记录核心围绕三件事用请求ID实现精准定位、按日志级别做分级存储、让控制台输出彩色日志。适合刚接触Webman的开发者也适合已经上线但还在被日志问题折磨的团队。1. WebmanMonolog的默认状态为什么非改不可1.1 默认配置到底长什么样Webman官方对日志这块其实给了一个比较省心的方案组件层面默认带了日志能力开箱即用。你安装完框架后在配置目录里能看到类似这样的内容return [ default file, channels [ file [ type file, level debug, path runtime_path() . /logs/app.log, ], ], ];这套配置对纯个人项目或内部小工具来说够用了。它做的事情很简单所有日志统一追加到runtime/logs/app.log什么级别都往这一个文件里写格式化也是框架默认的那套。真正让我决定动手改造的是一次凌晨收到告警后的排查经历。告警内容是一条ERROR级别的日志Connection timed out after 5000ms。看起来是数据库连接超时但问题是这条日志是哪个请求触发的是用户在下单接口碰到了还是后台任务里碰到的查了一圈日志里只有时间、级别、消息内容连请求路径都没有更不用说能定位到具体某个用户、某次操作了。这个场景应该不少人都遇到过——日志系统如果只能告诉你出了什么事而不能告诉你这件事发生在哪条链路上、是谁触发的那就只完成了一半工作。1.2 三个核心痛点不可定位、不分级、不可读结合那个晚上的经历我总结出默认方案在真实业务里的三个致命短板痛点现象直接后果不可定位日志没有请求ID、没有用户上下文、没有接口标识多并发请求的日志交错在一起出了问题没法还原现场不分级debug、info、error全写进同一个文件甚至同一行排查时要在海量日志里捞异常误判率高不可读业务日志只落盘终端控制台看不到开发联调时只能反复tail文件效率极低本质上是可观测性不够。传统PHP脚本一次请求一个进程日志天然是孤立的但Webman是常驻内存框架一台机器上几百上千个请求并发跑在同一个Worker进程里如果没有结构化地给日志打上标记日志基本等于废纸。所以我的目标就很明确了日志要能串成链路、要按级别分开沉淀、开发环境要能在终端里一眼看懂。这就是标题里精准定位分级存储控制台彩色输出三件事的由来。下面我从配置地基开始一步一步拆解。2. 日志目录与通道设计先把地基打对2.1 目录规划的两种布局按级别分 vs 按业务分动手写配置之前先想清楚日志文件放在哪、怎么放。我见过很多项目把所有日志堆在一个runtime/logs/下时间一长一个文件几个GBgrep一次卡半分钟这肯定是不可维护的。目录规划上大致有两种思路按级别分目录runtime/logs/debug/、runtime/logs/info/、runtime/logs/error/。好处是级别清晰查问题直接进对应目录坏处是如果业务要按模块查询还得跨目录再捞一次。按业务分目录runtime/logs/order/、runtime/logs/payment/、runtime/logs/user/。好处是业务域内日志完整排查某条业务链路很方便坏处是单个目录里依然info和error混在一起。我实际用的是折中方案按日期分第一层目录日期目录下按级别分文件名。也就是这样runtime/logs/ 2024-11-20/ debug.log info.log warning.log error.log critical.log这样做的理由很直接日常排查时我最先知道的通常是出问题的大概时间先按日期定位到当天目录再按级别打开对应文件路径非常短。如果将来需要按业务维度查完全可以在Monolog的channel层面再拆一层不影响现有结构。2.2 通道与处理器的协作逻辑Monolog的核心模型是一个Logger下面挂多个Handler每条日志事件会依次流经这些HandlerHandler决定自己要不要处理处理时再交给Formatter排版。我用一个生活化的类比帮你理解Logger像一座水塔Handler是不同口径的出水管Formatter是出水管末端的定型模具。水日志事件到了有的管道负责把水引入debug池有的引入error池模具决定水落下来是一根直线还是散开成花。而Processor像是加在管道上的投料器每次水流过时自动加一点微量元素——比如请求ID、用户ID、模块名。这种Logger Handler Formatter Processor的协作机制是Monolog最值钱的地方。它让我可以在不改业务代码的前提下只调整配置就改变日志的去向和形态。比如临时想所有日志同时往屏幕打一份加一个StreamHandler(php://stdout)就行业务代码一行不动。2.3 配置文件示例从通道到格式化器的完整装配我的项目里用一个独立的config/monolog.php来管理所有日志配置。为了不跟业务代码强耦合我封装了一个Support\Logger门面类来读取这份配置。配置文件的核心结构大概是?php use Monolog\Level; return [ default [ handlers [ stdout [ handler \Monolog\Handler\StreamHandler::class, args [php://stdout, Level::Debug], formatter [ class \Monolog\Formatter\LineFormatter::class, args [ [%datetime%] [%extra.request_id%] %channel%.%level_name%: %message% %context% %extra%\n, Y-m-d H:i:s.u, ], ], ], ], processors [ \Monolog\Processor\IntrospectionProcessor::class, \App\Support\RequestIdProcessor::class, ], ], ];里面对当前阶段最重要的其实是两件事一是所有日志统一带request_id字段二是日期时间精确到微秒。微秒这个细节看起来不起眼但在常驻内存高并发下同一秒内的日志百八十条很常见没有微秒就很难看出先后顺序。配置写完之后Support\Logger根据这份配置创建Monolog实例然后通过一个全局函数\Support\Log::debug(msg, $context)或Log::error(...)来输出日志。后续所有优化都在这套结构上面叠加。3. 精准定位用请求ID把散落的日志串成一条链路3.1 请求ID如何生成与传递日志精准定位的第一步是让每次请求都有唯一身份标识也就是request_id。我的做法是在Webman的中间件里生成而不是在每个Controller里手动调用。中间件实现大致如下?php declare(strict_types1); namespace App\Middleware; use Webman\Http\Request; use Webman\Http\Response; use App\Support\MdcContext; class RequestIdMiddleware { public function process(Request $request, callable $next): Response { $requestId bin2hex(random_bytes(8)); // 16位十六进制足够用 MdcContext::set(request_id, $requestId); try { return $next($request); } finally { MdcContext::clear(); } } }这里有一个Webman和Workerman生态下特别容易踩的坑进程是常驻的静态变量的生命周期不是一次请求而是一个Worker进程的整个生命周期。如果不在请求结束前把上下文清掉下一个请求进入同一个进程时会读到上一个请求的request_id日志串号排查问题等于火上浇油。所以中间件里必须用try/finally结构保证clear()一定执行。MdcContext是我参照Java生态里MDCMapped Diagnostic Context的思路写的一个极简静态容器本质就是静态数组的读写加清理。为什么需要这样一个东西因为在代码的任何地方包括模型方法、队列消费逻辑、定时任务里我都想拿到当前请求的ID总不能每个类都手动传递参数。有了MdcContext一个静态读取就搞定。3.2 把请求ID写进每一条日志光生成request_id还不够Monolog默认不会自动把它输出到日志行里。这里要用到Processor机制。我写了一个RequestIdProcessor在每次生成日志记录时自动读取MdcContext并注入到日志的extra字段?php namespace App\Support; use Monolog\LogRecord; class RequestIdProcessor { public function __invoke(LogRecord $record): LogRecord { $requestId MdcContext::get(request_id, -); $record-extra[request_id] $requestId; return $record; } }然后LineFormatter的格式字符串里加上[%extra.request_id%]这样每条日志都会变成这样[2024-11-20 14:23:11.284612] [3a9f6c2e8b41d5f1] app.INFO: 订单创建成功日志里的request_id就像快递单号。一旦某个请求出了问题把异常日志里的request_id拿出来全链路grep一遍这个请求从进中间件到写数据库、调外部接口、返回响应的所有日志都能串起来。我在项目里实测下来线上问题定位时间从按小时计缩短到分钟级这是整个改造里性价比最高的一步。3.3 异常场景的上下文快照request_id解决的是这条日志属于哪次请求但还不足以还原完整的异常现场。我还希望异常日志里能看到请求的URL、方法、用户ID、客户端IP、请求参数脱敏后、以及具体的异常堆栈。Monolog对异常处理有一个很好的设计只要context里传了exception对象并且LineFormatter的第五个参数includeStacktraces设为true格式化器就会自动把异常堆栈信息追加到日志里。我的写法是try { $result $orderService-create($input); } catch (\Throwable $e) { Log::error(订单创建失败, [ exception $e, module order, uid $request-uid ?? 0, uri $request-path(), method $request-method(), input $this-safeInput($request-all()), ]); }safeInput()里我会主动过滤掉密码、token、支付密钥等敏感字段。日志一旦泄露给排查人员之外的渠道明文敏感字段就是安全事故。所以凡是准备写进日志的请求参数都必须过一遍脱敏逻辑。这一套组合拳打下来精准定位才算真正闭环request_id定位到具体请求上下文快照还原出请求现场异常堆栈给出问题根源。三点串起来排查效率比默认方案高一个数量级。4. 分级存储按级别分文件配合按天切割与保留策略4.1 分级存储的三种落地方式日志级别的划分Monolog里从Debug到Emergency一共8个级别。分级存储的目标很简单debug和info这类噪音多的日志归到低级别文件error和critical这种需要关注的归到高级别文件。落地方式我整理过三种按复杂度递增排列。方式一一个Handler硬编码路径。代码里直接判断级别然后写不同文件。缺点是把级别逻辑写死在代码里想调整级别边界得改代码再上线不推荐。方式二用FilterHandler做级别过滤。这是Monolog官方生态里的标准做法也是我最终采用的方案。核心思路每个文件对应一个Handler再用FilterHandler给每个Handler划定它只接收哪个级别区间的水。我贴一个精简版配置?php use Monolog\Logger; use Monolog\Level; use Monolog\Handler\StreamHandler; use Monolog\Handler\FilterHandler; use Monolog\Formatter\LineFormatter; $dir runtime_path() . /logs/ . date(Y-m-d); $formatter new LineFormatter( [%datetime%] [%extra.request_id%] %channel%.%level_name%: %message% %context% %extra%\n, Y-m-d H:i:s.u, false, // allowInlineLineBreaks true, // ignoreEmptyContextAndExtra true // includeStacktraces ); $infoHandler new FilterHandler( new StreamHandler($dir . /info.log, Level::Debug), [[Level::Debug, Level::Info]] // 只接收 Debug 到 Info ); $infoHandler-setFormatter($formatter); $errorHandler new FilterHandler( new StreamHandler($dir . /error.log, Level::Error), [[Level::Error, Level::Emergency]] // 只接收 Error 及以上 ); $errorHandler-setFormatter($formatter); $logger new Logger(app); $logger-pushHandler($infoHandler); $logger-pushHandler($errorHandler);FilterHandler的第二个参数是一组级别区间的集合我写[[Level::Info, Level::Info]]就表示只接收Info这一个级别写[[Level::Debug, Level::Info], [Level::Warning, Level::Emergency]]就表示接收Debug~Info以及Warning以上两个大段。这套机制灵活度很高后面想调整哪个文件收哪些级别改一行配置即可。方式三基于channel做业务隔离。适合大型项目给不同业务模块创建不同Logger实例再各自挂Handler。比如Log::channel(order)-error(...)和Log::channel(payment)-error(...)分别写入各自目录。考虑到当前项目的规模我暂时没有做这种拆分但如果你跑的是复杂的微服务或多业务线系统建议在设计阶段就预留channel维度。4.2 按天切割与文件保留策略分级解决了文件混乱问题但单个文件还是会无限膨胀。所以我还挂上了RotatingFileHandler来做按天切割。它是Monolog内置的文件轮转Handler不需要额外装包。用法上跟StreamHandler接近只是文件路径不要写具体的日期文件它自己会在写入时自动按天生成带日期的文件名。配合maxFiles参数它会在写入新一天日志时自动清理超过保留数量的旧文件。我实际用的配置结构长这样$handler new RotatingFileHandler( runtime_path() . /logs/info.log, // 实际生成 info-2024-11-20.log 30, // 最多保留30个文件 Level::Info );为什么保留30天这个数字不是拍脑袋。一是业务上要求日志保留一个月内可查二是磁盘容量有限按每天平均几十MB的体量30天大约1到2GB在可控范围内。如果你有合规或审计要求可以把critical级别的保留期拉长到半年一年级别低的缩短到7天。保留策略本质上是查询需求、磁盘容量、合规要求三者的平衡。4.3 写入性能与锁定问题Webman常驻内存下多个Worker进程会同时往同一个日志文件写入这里有个绕不开的问题并发写同一文件时的日志交错和文件锁竞争。Monolog的StreamHandler构造函数有一个$useLocking参数默认是true。它会在写入前调用PHP的flock加文件锁保证两条日志不会互相穿插。代价是加锁本身有点开销但在常规量级下完全可忽略。我在压测中看到开启锁之后单Worker写入日志的性能下降在5%以内几乎无感所以不要为了省这点性能去关掉文件锁。一旦关掉高并发下日志行可能变成 2024-11-20... 2024-11-20... 订单创建成功...转换失败 这种你拼都拼不完整的鬼样子。BufferHandler是另一个性能优化选项它可以把多条日志攒到一个内存缓冲里攒够一定数量或进程结束前一次性批量写入能显著减少磁盘IO次数。但我没有在生产环境用原因很实际buffer没刷出来的时候进程突然崩溃或被杀最后几条关键日志就丢了。日志系统首要价值是可靠性能优化反而要放在第二位。如果你确实需要给日志减负建议只在低价值的debug级别上做buffererror以上永远即时写入。5. 控制台彩色输出开发模式下的日志可视化5.1 为什么终端里只有启动信息没有业务日志这是很多Webman新手特别困惑的一点php start.php start启动后在终端里只看到Workerman的启动面板和连接事件业务里明明打了Log::info(xxx)终端却一个字都不显示。原因不复杂默认Logger的Handler写的是文件StreamHandler指向磁盘路径没有往标准输出php://stdout挂Handler。终端只接收进程的stdout输出业务日志压根没走这条路自然看不到。解决思路也简单在开发模式下手动给Logger多加一个输出到php://stdout的Handler。但加上容易直接打印出来的又是白底黑字的一行行堆叠看久了眼睛疼级别区分全靠人肉。所以就有了彩色输出这一步。5.2 LineFormatter内嵌ANSI颜色最简单粗暴的方式终端彩色日志的本质就是在输出字符串里混入ANSI转义码。比如\033[32m表示绿色文本\033[0m表示重置颜色。Monolog的LineFormatter本身不帮你上色但它允许你在格式字符串里直接写转义码。最简单的方式是在格式字符串里对不同字段做固定着色。比如让时间戳显示绿色、request_id显示青色、消息体用默认白色$consoleFormatter new LineFormatter( \033[32m[%datetime%]\033[0m \033[36m[%extra.request_id%]\033[0m %channel%.%level_name%: %message%\n, H:i:s.u ); $stdoutHandler new StreamHandler(php://stdout, Level::Debug); $stdoutHandler-setFormatter($consoleFormatter);这样日志在终端里会变成[14:23:11.284612] [3a9f6c2e8b41d5f1] app.INFO: 订单创建成功字段颜色固定之后扫视日志时很容易找到时间线和请求线。但还不够——不同级别之间没有任何区分error和info看起来一样眼睛还是得靠读而不是靠扫来发现问题。5.3 按日志级别动态配色的进阶写法要真正做到按级别变色我给stdout这条链路额外挂了一个Processor。Processor根据当前日志的level动态往extra里注入一个颜色起始码同时在格式字符串末尾放一个颜色重置码?php namespace App\Support; use Monolog\Level; use Monolog\LogRecord; class ConsoleColorProcessor { private const LEVEL_COLORS [ DEBUG \033[36m, // 青色 INFO \033[32m, // 绿色 NOTICE \033[34m, // 蓝色 WARNING \033[33m, // 黄色 ERROR \033[31m, // 红色 CRITICAL \033[31m, // 红色 ALERT \033[35m, // 洋红 EMERGENCY \033[35m, // 洋红 ]; public function __invoke(LogRecord $record): LogRecord { $levelName $record-level-getName(); $record-extra[level_color] self::LEVEL_COLORS[$levelName] ?? \033[0m; $record-extra[color_reset] \033[0m; return $record; } }然后stdout的格式字符串写成这样$format %extra.level_color%[%datetime%] [%extra.request_id%] %channel%.%level_name%: %message%\033[0m\n;效果就是INFO整行绿色、WARNING整行黄色、ERROR整行红色。终端一拉下来哪里出问题一目了然。这个进阶写法的价值在于它没有破坏日志内容的结构纯粹是多加了渲染用的extra字段只影响控制台那条链路的展示。这里要提醒一下ANSI转义码不是所有终端都认。老版本的Windows CMD和部分Windows终端对ANSI支持很差会显示一坨乱码字符。好在现在主流的开发终端macOS Terminal、iTerm2、Windows Terminal、VS Code终端都支持ANSI基本不用太担心。如果是纯生产Linux服务器连ssh工具都直接支持更没问题。另外stdout这个Handler只应该出现在开发环境。我用环境变量控制判断如果是dev环境才push进Logger生产环境绝不开。不然生产上请求量大起来日志全往stdout刷既拖慢进程又不好归档。6. 上线验证与踩坑记录这些坑我替你们踩过了6.1 验证清单逐项确认改造真的生效配置写完之后别急着直接上生产。我列了一个验证清单按顺序执行一遍才放心验证项操作预期结果请求ID生成连续curl两次不同接口两次日志的request_id不同且同一请求内所有日志的request_id一致同请求链路在中间件、控制器、模型里各打一条日志三条日志request_id相同按时间顺序排列微秒字段递增级别文件隔离分别打debug、info、warning、error日志debug/info只出现在info.logerror及以上只出现在error.log按天切割修改系统日期测试环境或直接看次日文件新一天生成新文件超过保留数的旧文件被自动清理控制台彩色dev模式启动并触发error日志终端中error红色、warning黄色、info绿色敏感字段脱敏传入带password参数的请求并打日志日志中password被过滤或打星号这个清单我建议固化到项目的发布检查流程里。日志系统一旦出问题往往不是马上暴露而是等到排障那天才发现卧槽这日志怎么没记下来那时候代价就大了。6.2 踩坑记录buffer未刷出、级别区间配错、ANSI乱码这次改造过程中有几个坑每一个都浪费了我不少时间值得单独记一笔。坑一FilterHandler的区间参数写错日志全丢。最初我把FilterHandler第二个参数写成[Level::Debug, Level::Info]结果日志一条都没写进去。查了源码才发现它的构造签名要求第二个参数是多个区间的数组比如[[Level::Debug, Level::Info]]否则会被当成一个无效区间。这个细节坑了很多Monolog新手报错还不明显只是静默丢弃日志。遇到日志不落盘的问题第一反应就应该去检查FilterHandler的区间格式。坑二LineFormatter的ignoreEmptyContextAndExtra参数引发隐性混淆。我把这个参数设为true之后格式串里%extra.request_id%在extra没有该字段时不再输出[]而是安静地变成空。好处是日志干净坏处是如果Processor没生效你会拿到一条没有request_id的日志而完全不报错。所以验证的第一步必须是有意识地检查每条日志是否真的带了request_id而不是看一眼格式漂亮就完事。坑三Windows老终端ANSI乱码。我一开始在Windows上用老版本CMD调试看到日志里一串奇怪的ESC[32m字符以为是代码写错了查了老半天才确认是终端兼容问题。解决方案不是改代码而是换用支持ANSI的Windows Terminal或者直接到WSL里跑。如果你的团队里有用老Windows环境的同学记得在项目文档里注明终端要求。6.3 可以继续深挖的方向这套改造做完之后日志的日常体验已经好了很多但还有几个方向我认为值得继续探索。一个是结合Webman的定时任务或队列场景做链路打通。现在的request_id只覆盖了HTTP请求链路队列消费、异步任务、定时脚本里还需要单独生成链路ID再把上下游的ID串起来。思路是类似的在任务上下文里也放一个MdcContext。另一个是日志的JSON化。目前用的是LineFormatter纯文本格式方便人读。但如果你接了日志采集系统比如需要把日志投递到Elasticsearch这类检索平台可以换用JsonFormatter让每条日志变成一个JSON对象检索字段的时候会轻松很多。我在这个项目里暂时没有上因为日志量还没到需要集中检索的程度。还有一个小建议定期抽查日志而不只是出了事才看。我后来养成了一个习惯每天早上花几分钟翻一下昨天的warning和error级日志。很多看起来不起眼的warning比如外部接口响应变慢、某个参数格式异常其实是更大问题的前期信号。日志优化不是一次性工程它是帮你看清系统运行状态的长期伙伴。我个人最后再分享一个实操中的体会配置日志时不要贪多贪全。刚开始你可以把所有级别、所有上下文都往日志里塞但用上一段时间后会发现真正排障时高频用到的字段就那么几个。与其把日志做成一个臃肿的杂物箱不如保持够用、干净、可读的原则。每次加新字段前先问问自己这条信息真到出问题那天我会用它来做什么判断如果答不上来就别加。 
长河君 · 2026/10/10 7:51:40 · 阅读 1.2k Webman框架日志优化实践：请求ID定位、分级存储与彩色输出
前阵子在把一个电商接口服务从传统PHP迁移到Webman框架时日志这块让我难受了好一阵。Webman框架本身性能很香常驻内存、高并发、协程风格都很顺手但默认的日志方案在请求量上来之后完全不够用夜里告警报了一条数据库连接超时我对着日志看了半天既不知道是哪个用户触发的也分不清是error还是info更糟糕的是日志全部堆在一个文件里终端里还啥都看不到。这篇文章就是我在Webman项目里基于Monolog日志组件做深度优化的完整记录核心围绕三件事用请求ID实现精准定位、按日志级别做分级存储、让控制台输出彩色日志。适合刚接触Webman的开发者也适合已经上线但还在被日志问题折磨的团队。1. WebmanMonolog的默认状态为什么非改不可1.1 默认配置到底长什么样Webman官方对日志这块其实给了一个比较省心的方案组件层面默认带了日志能力开箱即用。你安装完框架后在配置目录里能看到类似这样的内容return [ default file, channels [ file [ type file, level debug, path runtime_path() . /logs/app.log, ], ], ];这套配置对纯个人项目或内部小工具来说够用了。它做的事情很简单所有日志统一追加到runtime/logs/app.log什么级别都往这一个文件里写格式化也是框架默认的那套。真正让我决定动手改造的是一次凌晨收到告警后的排查经历。告警内容是一条ERROR级别的日志Connection timed out after 5000ms。看起来是数据库连接超时但问题是这条日志是哪个请求触发的是用户在下单接口碰到了还是后台任务里碰到的查了一圈日志里只有时间、级别、消息内容连请求路径都没有更不用说能定位到具体某个用户、某次操作了。这个场景应该不少人都遇到过——日志系统如果只能告诉你出了什么事而不能告诉你这件事发生在哪条链路上、是谁触发的那就只完成了一半工作。1.2 三个核心痛点不可定位、不分级、不可读结合那个晚上的经历我总结出默认方案在真实业务里的三个致命短板痛点现象直接后果不可定位日志没有请求ID、没有用户上下文、没有接口标识多并发请求的日志交错在一起出了问题没法还原现场不分级debug、info、error全写进同一个文件甚至同一行排查时要在海量日志里捞异常误判率高不可读业务日志只落盘终端控制台看不到开发联调时只能反复tail文件效率极低本质上是可观测性不够。传统PHP脚本一次请求一个进程日志天然是孤立的但Webman是常驻内存框架一台机器上几百上千个请求并发跑在同一个Worker进程里如果没有结构化地给日志打上标记日志基本等于废纸。所以我的目标就很明确了日志要能串成链路、要按级别分开沉淀、开发环境要能在终端里一眼看懂。这就是标题里精准定位分级存储控制台彩色输出三件事的由来。下面我从配置地基开始一步一步拆解。2. 日志目录与通道设计先把地基打对2.1 目录规划的两种布局按级别分 vs 按业务分动手写配置之前先想清楚日志文件放在哪、怎么放。我见过很多项目把所有日志堆在一个runtime/logs/下时间一长一个文件几个GBgrep一次卡半分钟这肯定是不可维护的。目录规划上大致有两种思路按级别分目录runtime/logs/debug/、runtime/logs/info/、runtime/logs/error/。好处是级别清晰查问题直接进对应目录坏处是如果业务要按模块查询还得跨目录再捞一次。按业务分目录runtime/logs/order/、runtime/logs/payment/、runtime/logs/user/。好处是业务域内日志完整排查某条业务链路很方便坏处是单个目录里依然info和error混在一起。我实际用的是折中方案按日期分第一层目录日期目录下按级别分文件名。也就是这样runtime/logs/ 2024-11-20/ debug.log info.log warning.log error.log critical.log这样做的理由很直接日常排查时我最先知道的通常是出问题的大概时间先按日期定位到当天目录再按级别打开对应文件路径非常短。如果将来需要按业务维度查完全可以在Monolog的channel层面再拆一层不影响现有结构。2.2 通道与处理器的协作逻辑Monolog的核心模型是一个Logger下面挂多个Handler每条日志事件会依次流经这些HandlerHandler决定自己要不要处理处理时再交给Formatter排版。我用一个生活化的类比帮你理解Logger像一座水塔Handler是不同口径的出水管Formatter是出水管末端的定型模具。水日志事件到了有的管道负责把水引入debug池有的引入error池模具决定水落下来是一根直线还是散开成花。而Processor像是加在管道上的投料器每次水流过时自动加一点微量元素——比如请求ID、用户ID、模块名。这种Logger Handler Formatter Processor的协作机制是Monolog最值钱的地方。它让我可以在不改业务代码的前提下只调整配置就改变日志的去向和形态。比如临时想所有日志同时往屏幕打一份加一个StreamHandler(php://stdout)就行业务代码一行不动。2.3 配置文件示例从通道到格式化器的完整装配我的项目里用一个独立的config/monolog.php来管理所有日志配置。为了不跟业务代码强耦合我封装了一个Support\Logger门面类来读取这份配置。配置文件的核心结构大概是?php use Monolog\Level; return [ default [ handlers [ stdout [ handler \Monolog\Handler\StreamHandler::class, args [php://stdout, Level::Debug], formatter [ class \Monolog\Formatter\LineFormatter::class, args [ [%datetime%] [%extra.request_id%] %channel%.%level_name%: %message% %context% %extra%\n, Y-m-d H:i:s.u, ], ], ], ], processors [ \Monolog\Processor\IntrospectionProcessor::class, \App\Support\RequestIdProcessor::class, ], ], ];里面对当前阶段最重要的其实是两件事一是所有日志统一带request_id字段二是日期时间精确到微秒。微秒这个细节看起来不起眼但在常驻内存高并发下同一秒内的日志百八十条很常见没有微秒就很难看出先后顺序。配置写完之后Support\Logger根据这份配置创建Monolog实例然后通过一个全局函数\Support\Log::debug(msg, $context)或Log::error(...)来输出日志。后续所有优化都在这套结构上面叠加。3. 精准定位用请求ID把散落的日志串成一条链路3.1 请求ID如何生成与传递日志精准定位的第一步是让每次请求都有唯一身份标识也就是request_id。我的做法是在Webman的中间件里生成而不是在每个Controller里手动调用。中间件实现大致如下?php declare(strict_types1); namespace App\Middleware; use Webman\Http\Request; use Webman\Http\Response; use App\Support\MdcContext; class RequestIdMiddleware { public function process(Request $request, callable $next): Response { $requestId bin2hex(random_bytes(8)); // 16位十六进制足够用 MdcContext::set(request_id, $requestId); try { return $next($request); } finally { MdcContext::clear(); } } }这里有一个Webman和Workerman生态下特别容易踩的坑进程是常驻的静态变量的生命周期不是一次请求而是一个Worker进程的整个生命周期。如果不在请求结束前把上下文清掉下一个请求进入同一个进程时会读到上一个请求的request_id日志串号排查问题等于火上浇油。所以中间件里必须用try/finally结构保证clear()一定执行。MdcContext是我参照Java生态里MDCMapped Diagnostic Context的思路写的一个极简静态容器本质就是静态数组的读写加清理。为什么需要这样一个东西因为在代码的任何地方包括模型方法、队列消费逻辑、定时任务里我都想拿到当前请求的ID总不能每个类都手动传递参数。有了MdcContext一个静态读取就搞定。3.2 把请求ID写进每一条日志光生成request_id还不够Monolog默认不会自动把它输出到日志行里。这里要用到Processor机制。我写了一个RequestIdProcessor在每次生成日志记录时自动读取MdcContext并注入到日志的extra字段?php namespace App\Support; use Monolog\LogRecord; class RequestIdProcessor { public function __invoke(LogRecord $record): LogRecord { $requestId MdcContext::get(request_id, -); $record-extra[request_id] $requestId; return $record; } }然后LineFormatter的格式字符串里加上[%extra.request_id%]这样每条日志都会变成这样[2024-11-20 14:23:11.284612] [3a9f6c2e8b41d5f1] app.INFO: 订单创建成功日志里的request_id就像快递单号。一旦某个请求出了问题把异常日志里的request_id拿出来全链路grep一遍这个请求从进中间件到写数据库、调外部接口、返回响应的所有日志都能串起来。我在项目里实测下来线上问题定位时间从按小时计缩短到分钟级这是整个改造里性价比最高的一步。3.3 异常场景的上下文快照request_id解决的是这条日志属于哪次请求但还不足以还原完整的异常现场。我还希望异常日志里能看到请求的URL、方法、用户ID、客户端IP、请求参数脱敏后、以及具体的异常堆栈。Monolog对异常处理有一个很好的设计只要context里传了exception对象并且LineFormatter的第五个参数includeStacktraces设为true格式化器就会自动把异常堆栈信息追加到日志里。我的写法是try { $result $orderService-create($input); } catch (\Throwable $e) { Log::error(订单创建失败, [ exception $e, module order, uid $request-uid ?? 0, uri $request-path(), method $request-method(), input $this-safeInput($request-all()), ]); }safeInput()里我会主动过滤掉密码、token、支付密钥等敏感字段。日志一旦泄露给排查人员之外的渠道明文敏感字段就是安全事故。所以凡是准备写进日志的请求参数都必须过一遍脱敏逻辑。这一套组合拳打下来精准定位才算真正闭环request_id定位到具体请求上下文快照还原出请求现场异常堆栈给出问题根源。三点串起来排查效率比默认方案高一个数量级。4. 分级存储按级别分文件配合按天切割与保留策略4.1 分级存储的三种落地方式日志级别的划分Monolog里从Debug到Emergency一共8个级别。分级存储的目标很简单debug和info这类噪音多的日志归到低级别文件error和critical这种需要关注的归到高级别文件。落地方式我整理过三种按复杂度递增排列。方式一一个Handler硬编码路径。代码里直接判断级别然后写不同文件。缺点是把级别逻辑写死在代码里想调整级别边界得改代码再上线不推荐。方式二用FilterHandler做级别过滤。这是Monolog官方生态里的标准做法也是我最终采用的方案。核心思路每个文件对应一个Handler再用FilterHandler给每个Handler划定它只接收哪个级别区间的水。我贴一个精简版配置?php use Monolog\Logger; use Monolog\Level; use Monolog\Handler\StreamHandler; use Monolog\Handler\FilterHandler; use Monolog\Formatter\LineFormatter; $dir runtime_path() . /logs/ . date(Y-m-d); $formatter new LineFormatter( [%datetime%] [%extra.request_id%] %channel%.%level_name%: %message% %context% %extra%\n, Y-m-d H:i:s.u, false, // allowInlineLineBreaks true, // ignoreEmptyContextAndExtra true // includeStacktraces ); $infoHandler new FilterHandler( new StreamHandler($dir . /info.log, Level::Debug), [[Level::Debug, Level::Info]] // 只接收 Debug 到 Info ); $infoHandler-setFormatter($formatter); $errorHandler new FilterHandler( new StreamHandler($dir . /error.log, Level::Error), [[Level::Error, Level::Emergency]] // 只接收 Error 及以上 ); $errorHandler-setFormatter($formatter); $logger new Logger(app); $logger-pushHandler($infoHandler); $logger-pushHandler($errorHandler);FilterHandler的第二个参数是一组级别区间的集合我写[[Level::Info, Level::Info]]就表示只接收Info这一个级别写[[Level::Debug, Level::Info], [Level::Warning, Level::Emergency]]就表示接收Debug~Info以及Warning以上两个大段。这套机制灵活度很高后面想调整哪个文件收哪些级别改一行配置即可。方式三基于channel做业务隔离。适合大型项目给不同业务模块创建不同Logger实例再各自挂Handler。比如Log::channel(order)-error(...)和Log::channel(payment)-error(...)分别写入各自目录。考虑到当前项目的规模我暂时没有做这种拆分但如果你跑的是复杂的微服务或多业务线系统建议在设计阶段就预留channel维度。4.2 按天切割与文件保留策略分级解决了文件混乱问题但单个文件还是会无限膨胀。所以我还挂上了RotatingFileHandler来做按天切割。它是Monolog内置的文件轮转Handler不需要额外装包。用法上跟StreamHandler接近只是文件路径不要写具体的日期文件它自己会在写入时自动按天生成带日期的文件名。配合maxFiles参数它会在写入新一天日志时自动清理超过保留数量的旧文件。我实际用的配置结构长这样$handler new RotatingFileHandler( runtime_path() . /logs/info.log, // 实际生成 info-2024-11-20.log 30, // 最多保留30个文件 Level::Info );为什么保留30天这个数字不是拍脑袋。一是业务上要求日志保留一个月内可查二是磁盘容量有限按每天平均几十MB的体量30天大约1到2GB在可控范围内。如果你有合规或审计要求可以把critical级别的保留期拉长到半年一年级别低的缩短到7天。保留策略本质上是查询需求、磁盘容量、合规要求三者的平衡。4.3 写入性能与锁定问题Webman常驻内存下多个Worker进程会同时往同一个日志文件写入这里有个绕不开的问题并发写同一文件时的日志交错和文件锁竞争。Monolog的StreamHandler构造函数有一个$useLocking参数默认是true。它会在写入前调用PHP的flock加文件锁保证两条日志不会互相穿插。代价是加锁本身有点开销但在常规量级下完全可忽略。我在压测中看到开启锁之后单Worker写入日志的性能下降在5%以内几乎无感所以不要为了省这点性能去关掉文件锁。一旦关掉高并发下日志行可能变成 2024-11-20... 2024-11-20... 订单创建成功...转换失败 这种你拼都拼不完整的鬼样子。BufferHandler是另一个性能优化选项它可以把多条日志攒到一个内存缓冲里攒够一定数量或进程结束前一次性批量写入能显著减少磁盘IO次数。但我没有在生产环境用原因很实际buffer没刷出来的时候进程突然崩溃或被杀最后几条关键日志就丢了。日志系统首要价值是可靠性能优化反而要放在第二位。如果你确实需要给日志减负建议只在低价值的debug级别上做buffererror以上永远即时写入。5. 控制台彩色输出开发模式下的日志可视化5.1 为什么终端里只有启动信息没有业务日志这是很多Webman新手特别困惑的一点php start.php start启动后在终端里只看到Workerman的启动面板和连接事件业务里明明打了Log::info(xxx)终端却一个字都不显示。原因不复杂默认Logger的Handler写的是文件StreamHandler指向磁盘路径没有往标准输出php://stdout挂Handler。终端只接收进程的stdout输出业务日志压根没走这条路自然看不到。解决思路也简单在开发模式下手动给Logger多加一个输出到php://stdout的Handler。但加上容易直接打印出来的又是白底黑字的一行行堆叠看久了眼睛疼级别区分全靠人肉。所以就有了彩色输出这一步。5.2 LineFormatter内嵌ANSI颜色最简单粗暴的方式终端彩色日志的本质就是在输出字符串里混入ANSI转义码。比如\033[32m表示绿色文本\033[0m表示重置颜色。Monolog的LineFormatter本身不帮你上色但它允许你在格式字符串里直接写转义码。最简单的方式是在格式字符串里对不同字段做固定着色。比如让时间戳显示绿色、request_id显示青色、消息体用默认白色$consoleFormatter new LineFormatter( \033[32m[%datetime%]\033[0m \033[36m[%extra.request_id%]\033[0m %channel%.%level_name%: %message%\n, H:i:s.u ); $stdoutHandler new StreamHandler(php://stdout, Level::Debug); $stdoutHandler-setFormatter($consoleFormatter);这样日志在终端里会变成[14:23:11.284612] [3a9f6c2e8b41d5f1] app.INFO: 订单创建成功字段颜色固定之后扫视日志时很容易找到时间线和请求线。但还不够——不同级别之间没有任何区分error和info看起来一样眼睛还是得靠读而不是靠扫来发现问题。5.3 按日志级别动态配色的进阶写法要真正做到按级别变色我给stdout这条链路额外挂了一个Processor。Processor根据当前日志的level动态往extra里注入一个颜色起始码同时在格式字符串末尾放一个颜色重置码?php namespace App\Support; use Monolog\Level; use Monolog\LogRecord; class ConsoleColorProcessor { private const LEVEL_COLORS [ DEBUG \033[36m, // 青色 INFO \033[32m, // 绿色 NOTICE \033[34m, // 蓝色 WARNING \033[33m, // 黄色 ERROR \033[31m, // 红色 CRITICAL \033[31m, // 红色 ALERT \033[35m, // 洋红 EMERGENCY \033[35m, // 洋红 ]; public function __invoke(LogRecord $record): LogRecord { $levelName $record-level-getName(); $record-extra[level_color] self::LEVEL_COLORS[$levelName] ?? \033[0m; $record-extra[color_reset] \033[0m; return $record; } }然后stdout的格式字符串写成这样$format %extra.level_color%[%datetime%] [%extra.request_id%] %channel%.%level_name%: %message%\033[0m\n;效果就是INFO整行绿色、WARNING整行黄色、ERROR整行红色。终端一拉下来哪里出问题一目了然。这个进阶写法的价值在于它没有破坏日志内容的结构纯粹是多加了渲染用的extra字段只影响控制台那条链路的展示。这里要提醒一下ANSI转义码不是所有终端都认。老版本的Windows CMD和部分Windows终端对ANSI支持很差会显示一坨乱码字符。好在现在主流的开发终端macOS Terminal、iTerm2、Windows Terminal、VS Code终端都支持ANSI基本不用太担心。如果是纯生产Linux服务器连ssh工具都直接支持更没问题。另外stdout这个Handler只应该出现在开发环境。我用环境变量控制判断如果是dev环境才push进Logger生产环境绝不开。不然生产上请求量大起来日志全往stdout刷既拖慢进程又不好归档。6. 上线验证与踩坑记录这些坑我替你们踩过了6.1 验证清单逐项确认改造真的生效配置写完之后别急着直接上生产。我列了一个验证清单按顺序执行一遍才放心验证项操作预期结果请求ID生成连续curl两次不同接口两次日志的request_id不同且同一请求内所有日志的request_id一致同请求链路在中间件、控制器、模型里各打一条日志三条日志request_id相同按时间顺序排列微秒字段递增级别文件隔离分别打debug、info、warning、error日志debug/info只出现在info.logerror及以上只出现在error.log按天切割修改系统日期测试环境或直接看次日文件新一天生成新文件超过保留数的旧文件被自动清理控制台彩色dev模式启动并触发error日志终端中error红色、warning黄色、info绿色敏感字段脱敏传入带password参数的请求并打日志日志中password被过滤或打星号这个清单我建议固化到项目的发布检查流程里。日志系统一旦出问题往往不是马上暴露而是等到排障那天才发现卧槽这日志怎么没记下来那时候代价就大了。6.2 踩坑记录buffer未刷出、级别区间配错、ANSI乱码这次改造过程中有几个坑每一个都浪费了我不少时间值得单独记一笔。坑一FilterHandler的区间参数写错日志全丢。最初我把FilterHandler第二个参数写成[Level::Debug, Level::Info]结果日志一条都没写进去。查了源码才发现它的构造签名要求第二个参数是多个区间的数组比如[[Level::Debug, Level::Info]]否则会被当成一个无效区间。这个细节坑了很多Monolog新手报错还不明显只是静默丢弃日志。遇到日志不落盘的问题第一反应就应该去检查FilterHandler的区间格式。坑二LineFormatter的ignoreEmptyContextAndExtra参数引发隐性混淆。我把这个参数设为true之后格式串里%extra.request_id%在extra没有该字段时不再输出[]而是安静地变成空。好处是日志干净坏处是如果Processor没生效你会拿到一条没有request_id的日志而完全不报错。所以验证的第一步必须是有意识地检查每条日志是否真的带了request_id而不是看一眼格式漂亮就完事。坑三Windows老终端ANSI乱码。我一开始在Windows上用老版本CMD调试看到日志里一串奇怪的ESC[32m字符以为是代码写错了查了老半天才确认是终端兼容问题。解决方案不是改代码而是换用支持ANSI的Windows Terminal或者直接到WSL里跑。如果你的团队里有用老Windows环境的同学记得在项目文档里注明终端要求。6.3 可以继续深挖的方向这套改造做完之后日志的日常体验已经好了很多但还有几个方向我认为值得继续探索。一个是结合Webman的定时任务或队列场景做链路打通。现在的request_id只覆盖了HTTP请求链路队列消费、异步任务、定时脚本里还需要单独生成链路ID再把上下游的ID串起来。思路是类似的在任务上下文里也放一个MdcContext。另一个是日志的JSON化。目前用的是LineFormatter纯文本格式方便人读。但如果你接了日志采集系统比如需要把日志投递到Elasticsearch这类检索平台可以换用JsonFormatter让每条日志变成一个JSON对象检索字段的时候会轻松很多。我在这个项目里暂时没有上因为日志量还没到需要集中检索的程度。还有一个小建议定期抽查日志而不只是出了事才看。我后来养成了一个习惯每天早上花几分钟翻一下昨天的warning和error级日志。很多看起来不起眼的warning比如外部接口响应变慢、某个参数格式异常其实是更大问题的前期信号。日志优化不是一次性工程它是帮你看清系统运行状态的长期伙伴。我个人最后再分享一个实操中的体会配置日志时不要贪多贪全。刚开始你可以把所有级别、所有上下文都往日志里塞但用上一段时间后会发现真正排障时高频用到的字段就那么几个。与其把日志做成一个臃肿的杂物箱不如保持够用、干净、可读的原则。每次加新字段前先问问自己这条信息真到出问题那天我会用它来做什么判断如果答不上来就别加。