Coolify 队列监控实践：Laravel Horizon 指标快照（horizon:snapshot）与快照保留期配置

Coolify 队列监控实践Laravel Horizon 指标快照horizon:snapshot与快照保留期配置【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolifyCoolify 基于 Laravel Horizon 管理其全部后台任务部署、备份、通知等的队列工作进程。然而即使php artisan horizon正常启动Horizon 控制台的 Metrics 面板也可能长时间一片空白——原因是指标曲线完全由horizon:snapshot生成的快照数据驱动而快照本身必须显式注册到 Laravel 任务调度器中才会周期性产生。本文以 Coolify 仓库中.claude/skills/configuring-horizon/references/metrics.md参考文档为主线结合 config/horizon.php 与 app/Console/Kernel.php 的真实实现讲清 Horizon 指标为什么是空的、快照该如何注册以及快照保留期参数到底代表什么这三个核心问题。读完本文你可以直接定位并修复 Horizon 指标面板空白、快照调度缺失、保留期配置误解这三类典型问题。指标面板为空的根因horizon命令不产生快照数据参考文档给出的第一个关键结论是运行horizonartisan 命令并不会自动填充指标数据。Horizon 控制台的指标图Jobs/Queues 处理速率、失败率等曲线并不是实时从队列读取的而是从快照snapshot数据构建出来的。快照由独立的horizon:snapshot命令生成且必须通过 Laravel 调度器每 5 分钟执行一次指标曲线才会有持续的数据点// 快照必须注册到调度器而不是手动执行 $schedule-command(horizon:snapshot)-everyFiveMinutes();也就是说php artisan horizon只负责启动 supervisor 进程消费队列它不触碰快照存储。如果你只在启动 Horizon 后打开/horizon页面Metrics 图表自然没有任何数据点。这也是参考文档中 Metrics dashboard stays blank untilhorizon:snapshotis scheduled 这一条目的完整含义快照调度是指标可视化的前置依赖而非可选增强。Coolify 中的真实调度注册在 Coolify 仓库中快照的调度注册位于 app/Console/Kernel.php且按开发/生产环境采用了不同频率// app/Console/Kernel.php if (isDev()) { // Instance Jobs $this-scheduleInstance-command(horizon:snapshot)-everyMinute(); ... } else { // Instance Jobs $this-scheduleInstance-command(horizon:snapshot)-everyFiveMinutes(); ... }可以看到开发环境isDev()horizon:snapshot每分钟执行一次便于本地快速看到指标曲线变化生产环境每 5 分钟执行一次这是参考文档中推荐的标准节奏must be scheduled to run every 5 minutes via Laravels scheduler。而调度器本身的运行由容器内的 s6-overlay 服务承载docker/production/etc/s6-overlay/s6-rc.d/scheduler-worker/run 与 docker/development/etc/s6-overlay/s6-rc.d/scheduler-worker/run 均执行php artisan schedule:work。从源码结构看这意味着horizon:snapshot并非独立 cron而是随schedule:work常驻进程按上表频率触发——排查生产环境快照缺失时应当先确认 scheduler-worker 服务是否存活而不是只盯着 horizon 进程。用调度器注册快照而不是手动执行参考文档的第二条告诫是手动执行一次快照只能让面板短暂有数据无法维持更新。手动php artisan horizon:snapshot一次 → 只写入一个时间点的快照面板短暂出现一个数据点调度器周期性执行 → 指标曲线随时间连续生长且与保留策略见下一节配合形成滚动窗口。参考文档同时提醒调度器注册语法在 Laravel 10 与 Laravel 11 之间存在差异。这一点在 Coolify 中可以直接确认composer.json 中声明了laravel/framework: ^12.65.0与laravel/horizon: ^5.48.2即项目运行于 Laravel 12 之上因此 app/Console/Kernel.php 使用的是 Laravel 11 风格// Laravel 11Coolify 当前实际写法 $this-scheduleInstance-command(horizon:snapshot)-everyFiveMinutes();而 Laravel 10 及以下项目的等价写法是传统的调度器闭包// Laravel 10 及以下 protected function schedule(Schedule $schedule): void { $schedule-command(horizon:snapshot)-everyFiveMinutes(); }两者的语义一致每 5 分钟触发一次horizon:snapshot差异在于调度器的注册入口与文件组织方式。如果你的代码库从旧版 Laravel 升级而来应检查schedule定义位置是否已迁移这正是参考文档要求先搜索horizon metrics snapshot确认语法的原因——用错版本语法会导致调度静默失效指标面板依旧空白。metrics.trim_snapshots是快照条数不是时间单位参考文档指出的第三个易错点极具误导性风险config/horizon.php中metrics.trim_snapshots的job与queue值表示保留多少条快照而不是分钟或小时数。Coolify 仓库中的实际配置config/horizon.php如下// config/horizon.php metrics [ trim_snapshots [ job 24, queue 24, ], ],其上方注释也明确写道该值与horizon:snapshot的调度周期结合使用共同决定指标保留时长This will get used in combination with Horizonshorizon:snapshotschedule to define how long to retain metrics。按参考文档的算法参数值快照频率等效保留时长trim_snapshots.job24每 5 分钟 1 次24 × 5 min 2 小时trim_snapshots.queue24每 5 分钟 1 次24 × 5 min 2 小时即默认配置下Job 与 Queue 的指标曲线只展示最近 2 小时的历史。需要更长历史时应增大这两个数值代价是Redis 内存占用上升——每个快照都会以字符串形式写入 Horizon 前缀下的 Redis 键空间。这里有一个必须区分的易混淆配置同一文件中的trim段config/horizon.php里的recent、pending、completed、recent_failed、failed、monitored才是分钟数// config/horizon.php —— 注意这里的值单位是分钟 trim [ recent 60, // 分钟 pending 60, // 分钟 completed 60, // 分钟 recent_failed 10080, // 1 周分钟 failed 10080, monitored 10080, ],trim控制的是任务条目recent/pending/completed/failed 列表的持久化时长metrics.trim_snapshots控制的是指标快照条数——两者单位不同、用途不同混用会导致对指标为什么只显示 2 小时产生错误判断。前提条件与排查清单结合参考文档与仓库实现Horizon 指标要正常工作需满足以下前提均可在仓库中验证队列驱动必须是 Redis。config/queue.php 中default env(QUEUE_CONNECTION, redis)默认即 Redis 连接config/horizon.php 中 Horizon 自身元数据存储也使用defaultRedis 连接。参考文档所属的技能指南SKILL.md亦明确Horizon 仅支持 Redis 队列驱动database、SQS 均不受支持。horizon:snapshot必须存在于调度器中且调度器进程schedule:work在运行。Coolify 中对应 app/Console/Kernel.php开发每分钟与 app/Console/Kernel.php生产每 5 分钟。保留窗口 快照条数 × 快照间隔。默认 24 条 × 5 分钟 2 小时调大metrics.trim_snapshots.job/queue可延长曲线历史需权衡 Redis 内存。快照写入是滚动覆盖的旧快照超出保留条数即被修剪因此面板空白与曲线只有近期数据是两种不同现象前者通常缺调度后者是保留策略生效。小结围绕 metrics.md 参考文档的三个要点可以在 Coolify 仓库中找到完整落点指标面板空白源于horizon:snapshot未入调度器对照 app/Console/Kernel.php 的真实注册方式快照必须靠周期性调度而非手动单次执行且注册语法需匹配 Laravel 版本Coolify 为 Laravel 12采用 11 写法metrics.trim_snapshots的job/queue默认各 24 条是快照条数与 5 分钟快照间隔相乘得到约 2 小时的曲线保留窗口与以分钟为单位的trim段不可混淆。掌握这三点后任何 Horizon 指标相关的空白面板、数据断档、窗口偏短问题都可以按调度是否存在 → 调度器是否存活 → 保留条数是否合理的顺序快速定位。【免费下载链接】coolifyAn open-source, self-hostable PaaS alternative to Vercel, Heroku Netlify that lets you easily deploy static sites, databases, full-stack applications and 280 one-click services on your own servers.项目地址: https://gitcode.com/GitHub_Trending/co/coolify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考