Laravel并发任务日志记录方法

在 Laravel 并发任务场景下，日志极易因多 worker 混写、上下文丢失、事务干扰、时钟不同步等问题而失效，导致问题排查举步维艰；本文直击痛点，提出一套完整解决方案：通过动态 worker 日志通道隔离日志流、在队列任务中显式透传 request_id/trace_id 实现全链路追踪、绕过数据库事务异步落库保障日志不丢失、结合 Telescope JobWatcher 补充结构化执行元数据，并强调服务器时间校准这一常被忽视却至关重要的基础环节——让每一行日志都能精准归属、可追溯、可信赖。

并发任务日志需隔离通道、注入请求/追踪ID、绕过事务写入、异步落库、启用Telescope JobWatcher并校准服务器时间。

并发任务的日志必须能区分每个任务实例、避免上下文污染、且不能因任务失败而丢失——直接用 Log::info() 会混掉 worker ID、请求 ID 和真实执行时间，查问题时根本对不上号。

用 Log::stack() + 自定义 channel 隔离并发日志流

默认的 stack 通道会把所有日志打到一起，多个队列 worker 同时写入时，时间戳相近但内容错乱。必须为每个并发任务分配独立日志通道，或至少强制注入隔离标识。

• 在 config/logging.php 中定义一个带占位符的 worker 通道：'worker' => ['driver' => 'daily', 'path' => storage_path('logs/worker_'.env('WORKER_ID', 'default').'.log')]
• 启动队列 worker 时传入唯一 ID：php artisan queue:work --queue=high --name=worker-01，并在 .env 中设 WORKER_ID=worker-01
• 代码中显式调用：Log::channel('worker')->info('任务开始', ['job_id' => $job->id, 'attempts' => $job->attempts()])
• 不推荐用 Log::useContext() 动态塞 worker ID —— 它是全局静态栈，多协程/多线程下极易被覆盖

在 job handle() 中手动注入 request_id 和 trace_id

队列任务脱离 HTTP 生命周期，request()->header('X-Request-ID') 拿不到；但若任务由 API 触发，必须把原始请求上下文带进来，否则无法关联前端行为。

• 投递任务时显式传参：ProcessOrder::dispatch($order)->onQueue('high')->withChain([new NotifyUser($user)])->delay(now()->addSeconds(5))，同时在构造函数里存 $this->requestId = request()?->header('X-Request-ID') ?? Str::uuid()
• 在 handle() 开头立即记录：Log::channel('worker')->debug('任务执行上下文', ['request_id' => $this->requestId, 'trace_id' => $this->traceId ?? Str::uuid(), 'job_id' => $this->job->getJobId()])
• 别依赖 Log::setContext() 全局设置 —— 它在队列中不跨进程生效，且会被后续 job 覆盖
• 如果用了 OpenTelemetry 或 Sentry，确保 trace_id 从父 span 透传，而不是每次 newStr::uuid()

避免在事务内同步写日志导致死锁或丢失

并发任务常操作数据库，若在 DB::transaction() 内直接调用 Log::info()，日志写入可能被事务回滚卷走，或与主库连接争抢锁。

• 日志写入必须绕过当前事务：用 DB::connection('log_mysql')->table('job_logs')->insert([...])，并确保该连接配置 'sticky' => false 和独立连接池
• 更稳妥做法是推到队列异步落库：LogToDatabase::dispatch(['level' => 'info', 'message' => '库存扣减完成', 'context' => $context])->onConnection('redis')
• 绝对不要在 catch 块里只写 Log::error() 就完事——要加 report($exception) 确保进异常处理器，否则 Sentry / Telescope 可能收不到
• 如果用 storage/logs/ 文件日志，注意多个 worker 写同一文件时，Linux 的 flock() 会阻塞，改用 daily 驱动 + 按 worker 分文件更稳

用 Telescope 的 Watchers\JobWatcher 补充结构化追踪

原生日志只记文本，查并发问题时缺执行耗时、重试次数、失败堆栈位置等关键维度。Telescope 的 JobWatcher 能自动捕获这些，但默认不开启。

• 确认 config/telescope.php 中 'watchers' 包含：Watchers\JobWatcher::class => env('TELESCOPE_JOB_WATCHER', true)
• 它会记录 job_id、connection、queue、failed_at、exception（含完整 trace），且支持按 status 和 queue 过滤
• 注意：Telescope 默认只存最近 24 小时数据，高频任务需调大 'prune' => 72（小时）或导出归档
• 它不替代业务日志，而是和 Log::channel('worker') 日志互补：前者看“是否成功”，后者看“为什么成功/失败”

最易被忽略的是：并发任务的 created_at 和 finished_at 时间戳来自不同进程时钟，NTP 偏移超 100ms 就会导致日志时序错乱——上线前务必校准所有 worker 服务器时间。

今天关于《Laravel并发任务日志记录方法》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！