Laravel 13.40 thêm hai callback để phát hiện công việc chạy lâu, nhưng có một chỗ rất dễ cấu hình sai: queue đo theo mili-giây, còn scheduler đo theo giây. Nếu cùng truyền số 1000, job sẽ cảnh báo sau khoảng một giây, trong khi scheduled task phải chạy hơn 16 phút mới chạm ngưỡng.
Đây là cơ chế quan sát sau khi framework nhận event duration, không phải một timeout mới. Bài này đối chiếu mã nguồn bản 13.40.0, dựng fixture trên PHP 8.4.24/Windows và chạy ma trận ngay dưới, bằng và trên ngưỡng. Kết quả từ môi trường kiểm tra được ghi trung tính; nó không đại diện cho tải thật hay SLO của nghiane.com.
Mục lục [Hiển thị]
Cùng tên “runs longer than”, khác đơn vị
Laravel Framework 13.40.0 được phát hành ngày 03/11/2026 và chứa cả Queue::whenJobRunsLongerThan lẫn Schedule::whenTaskRunsLongerThan. Hai API trông gần như đối xứng, nhưng event phía queue ghi duration bằng mili-giây; event của scheduled task ghi runtime bằng giây.
| API | Event được nghe | Đơn vị khi truyền số | Điều kiện gọi callback |
|---|---|---|---|
Queue::whenJobRunsLongerThan | JobAttempted | Mili-giây | duration > threshold |
Schedule::whenTaskRunsLongerThan | ScheduledTaskFinished, ScheduledTaskFailed | Giây | runtime > threshold |
Với DateTimeInterface, phía queue lấy số giây còn lại rồi nhân 1.000, còn scheduler giữ đơn vị giây. Với CarbonInterval, hai bên lần lượt dùng totalMilliseconds và totalSeconds. Cách an toàn nhất là đặt tên biến có hậu tố đơn vị, chẳng hạn $queueWarningMs và $scheduleWarningSeconds, thay vì dùng một biến $threshold chung.
Đăng ký callback ở đâu?
Có thể đăng ký hai callback trong boot() của một service provider. Queue worker là tiến trình sống lâu, nên thay đổi callback sau deploy chỉ có hiệu lực khi worker được restart. Tài liệu queue Laravel cũng nhắc rõ worker không tự nạp lại code đã thay đổi.
<?php
namespace App\Providers;
use Illuminate\Console\Scheduling\Event as ScheduledEvent;
use Illuminate\Contracts\Queue\Job;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Queue;
use Illuminate\Support\Facades\Schedule;
use Illuminate\Support\ServiceProvider;
class AppServiceProvider extends ServiceProvider
{
public function boot(): void
{
$queueWarningMs = 1_500;
$scheduleWarningSeconds = 60;
Queue::whenJobRunsLongerThan(
$queueWarningMs,
function (Job $job, float $durationMs): void {
Log::warning('Queue job ran longer than expected', [
'job' => $job->resolveName(),
'connection' => $job->getConnectionName(),
'duration_ms' => round($durationMs, 2),
]);
}
);
Schedule::whenTaskRunsLongerThan(
$scheduleWarningSeconds,
function (ScheduledEvent $task, float $runtimeSeconds): void {
Log::warning('Scheduled task ran longer than expected', [
'task' => $task->getSummaryForDisplay(),
'runtime_seconds' => round($runtimeSeconds, 2),
]);
}
);
}
}
Log chỉ nên giữ tên job, connection, tên task và duration cần thiết. Không dump payload, command có token, tham số khách hàng hoặc toàn bộ exception context vào kênh alert. Nếu hệ thống có nhiều worker, callback sẽ chạy trong từng process nhận event; phần gửi Slack, email hay webhook cần chống spam và có rate limit riêng.
Ma trận 999, 1000 và 1001 nói gì?
Fixture cài riêng Laravel 13.39.0 và 13.40.0 từ Composer. Reflection xác nhận cả hai method chưa tồn tại ở 13.39 và xuất hiện ở 13.40. Trên bản mới, threshold số 1000 được kiểm tra với duration 999, 1000, 1001 và null. Scheduler được chạy cùng ma trận cho cả event thành công và thất bại.

Kết quả quan trọng nhất là phép so sánh dùng dấu >, không phải >=. Giá trị đúng bằng ngưỡng không gọi callback. Queue attempt thất bại vẫn gọi handler khi duration vượt ngưỡng; scheduled task thất bại cũng vậy nếu event có runtime. Riêng ScheduledTaskFailed với runtime null bị bỏ qua.
Một integration nhỏ với sync queue cho job ngủ 25 ms và threshold 1 ms đã phát callback đúng một lần; duration quan sát trong lượt chạy là 38,97 ms. Con số này chỉ chứng minh đường event hoạt động trên fixture, không phải benchmark framework: autoload, Windows scheduler và độ nóng của process đều ảnh hưởng kết quả.
Task fail vẫn cảnh báo, nhưng callback không “cứu” task
Thay đổi scheduler trong PR #62233 đăng ký chung listener cho ScheduledTaskFinished và ScheduledTaskFailed. Điều đó hữu ích khi một lệnh lỗi sau khi chạy lâu: alert duration vẫn có thể xuất hiện thay vì chỉ nhìn exit code.
Phía queue cũng không lọc theo JobAttempted::successful(). PR #62141 chỉ yêu cầu duration khác null và lớn hơn threshold. Vì vậy, một attempt vừa chậm vừa lỗi có thể chạm cả listener duration lẫn cơ chế failed-job hoặc exception hiện có. Nếu hai nơi cùng gửi thông báo, nên thêm correlation ID và quy tắc gộp để một sự cố không bắn hai cảnh báo giống nhau.
Callback duration chạy sau event attempt/task; nó không can thiệp vào code đang thực thi. Đừng đặt logic “hủy job nếu duration lớn” vào đây rồi kỳ vọng worker quay ngược thời gian. Tác dụng đúng là ghi metric, thêm breadcrumb, gửi tín hiệu hoặc mở một quy trình điều tra.
Alert không thay timeout, retry hay lock

Bốn nhóm điều khiển giải quyết bốn câu hỏi khác nhau. Callback mới trả lời “việc này vừa chạy lâu hơn mức quan sát chưa?”. $timeout trên job hoặc --timeout của worker trả lời “worker được phép chạy attempt này bao lâu?”. tries, retryUntil, retry_after điều khiển lần thử tiếp theo. Còn withoutOverlapping và onOneServer xử lý trùng lịch hoặc tranh chấp scheduler.
Nếu đang cấu hình scheduler nhiều máy, bài Laravel 13.35 chạy toàn bộ scheduler trên một server đi sâu vào lock và leader. Đó là lớp khác với duration alert. Tương tự, giới hạn memory cho queue worker quyết định lúc recycle process, không quyết định một job riêng lẻ có bị xem là chậm hay không.
Một bẫy vận hành khác là đặt timeout worker dài hơn retry_after. Job cũ có thể vẫn chạy trong khi queue cho phép lấy lại job, dẫn tới hai attempt chồng nhau. Callback duration không sửa được cấu hình đó; hãy giữ timeout ngắn hơn retry_after theo tài liệu queue, rồi dùng alert như tín hiệu sớm trước khi chạm timeout.
Chọn threshold từ budget, không đoán mò
Không có một con số chung đúng cho mọi app. Scheduled command backup, đồng bộ feed và gửi báo cáo có budget rất khác nhau; queue xử lý email cũng khác job render PDF. Có thể bắt đầu từ giới hạn vận hành thật rồi tách hai tầng:
- Warning: đủ sớm để còn thời gian điều tra trước timeout hoặc cửa sổ cron kế tiếp.
- Critical: sát runtime limit, nguy cơ chồng lịch, hết thời gian hosting hoặc vi phạm SLO đã được đội ngũ xác định.
- Cooldown: gộp theo tên job/task và khoảng thời gian để tránh một batch lớn gửi hàng trăm thông báo.
- Context tối thiểu: connection, queue, tên job/task, duration, release/version và correlation ID; không log payload nhạy cảm.
Trước khi chọn ngưỡng, hãy thu metric trong một khoảng đủ đại diện rồi so với budget. Bài này không có percentile production và không bịa p95/p99. Nếu hiện chỉ có log rời rạc, đặt một warning bảo thủ, theo dõi false positive và điều chỉnh có ghi nhận thay vì coi con số đầu tiên là chuẩn vĩnh viễn.
Nâng lên 13.40 thế nào cho an toàn?
Trước hết, khóa dependency và chạy regression của ứng dụng. Checklist trong bài kiểm tra đường nâng cấp Laravel vẫn áp dụng: xem constraint Composer, đọc diff lockfile, chạy test, kiểm tra queue/scheduler trên staging và chuẩn bị rollback. Sau deploy, restart queue worker để callback mới được đăng ký.
Nên bật alert qua config gate thay vì hard-code mọi môi trường. Staging có thể dùng ngưỡng thấp để xác nhận pipeline metric; production dùng ngưỡng dựa trên budget thật. Kiểm tra cả ba biên dưới, bằng và trên ngưỡng, vì equality không trigger. Với scheduler, thêm một case command thất bại có runtime và một control runtime null; với queue, kiểm tra attempt thành công lẫn exception.
Sau khi bật production, cần xác nhận ba điểm vận hành nữa. Worker cũ phải được restart và đang chạy đúng release; cron phải gọi scheduler từ cùng codebase vừa deploy; kênh cảnh báo phải nhận metric nhưng không lộ payload. Nếu deploy theo rolling release, nên ghi version vào context để biết callback đến từ process cũ hay mới. Một lần test chủ động bằng job/task ngắn, không đụng dữ liệu khách hàng, sẽ đáng tin hơn việc chờ sự cố thật rồi mới phát hiện listener chưa được nạp.
Laravel 13.40 đáng nâng khi ứng dụng đã có queue hoặc scheduled task nhưng chưa có tín hiệu duration thống nhất. Giá trị lớn nhất không nằm ở hai dòng callback, mà ở việc nhìn thấy job/task chậm trước khi người dùng báo lỗi. Chỉ cần nhớ ranh giới: queue dùng mili-giây, scheduler dùng giây, và cả hai callback chỉ quan sát — timeout, retry và lock vẫn phải cấu hình ở đúng lớp của chúng.