2児のパパ系Webエンジニア
の開発日記
A Dad-of-Two Engineer's Development Diary

Laravel 13.40で遅いキュージョブと定期タスクを検知!whenJobRunsLongerThanの単位の罠も

Laravel 13.40で遅いキュージョブと定期タスクを検知!whenJobRunsLongerThanの単位の罠も

🙌 結論から

Laravel 13.40.0(11月3日リリース)で、キューのジョブと定期タスクが「思ったより長くかかった」ときに呼ばれるフックが入りました👀

Queue::whenJobRunsLongerThan() と Schedule::whenTaskRunsLongerThan() の2つです。

クエリには前から DB::whenQueryingForLongerThan() があったのに、ジョブとスケジュールには同じものがなかったんですよね🤔

夜間バッチが先月より30分延びていた、みたいな変化に、エラーが出る前に気づけるのがうれしいところです(^^)

ただ、フレームワークのソースを読んでみると、数字で渡したときの単位がキューはミリ秒、スケジュールは秒で、そろっていません。

さらに、タイムアウトで止まったジョブや runInBackground() のタスクはこの仕組みでは拾えないので、そこは今までどおりの監視が必要です(・_・;)

しきい値は CarbonInterval で書く、通知は同じジョブ名で間引く。 この2つだけ押さえておけば、サービスプロバイダに数行足すだけで使えます✨

💡 13.40で入った2つのメソッド

どちらも、Laravel 13.x のブランチに10月末にマージされたPRです。

キュー側が #62141、スケジュール側が #62233 で、13.40.0 のリリースノートに並んでいます。

キュー側はこんな書き方です。

use Carbon\CarbonInterval;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Queue;

// AppServiceProvider::boot() の中
Queue::whenJobRunsLongerThan(CarbonInterval::seconds(90), function ($job, $duration) {
    Log::warning("{$job->resolveName()} が {$duration}ms かかりました");
});

コールバックには、ジョブと「かかった時間」が渡ってきます!

中身を見ると、JobAttempted イベントのリスナーを登録しているだけでした。

ワーカーがジョブを1回試し終わったタイミングでイベントが飛ぶので、例外で失敗した回も対象になります💡

PRの説明でも「Queue::after() だと失敗したジョブは拾えない」と書かれていて、ここは自前でリスナーを書くより楽なポイントですね😊

スケジュール側も形はそっくりです。

use Carbon\CarbonInterval;
use Illuminate\Console\Scheduling\Event;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Schedule;

Schedule::whenTaskRunsLongerThan(CarbonInterval::minutes(45), function (Event $task, float $runtime) {
    Log::warning("定期タスク [{$task->getSummaryForDisplay()}] が {$runtime}秒 かかりました");
});

こちらは ScheduledTaskFinished と ScheduledTaskFailed の両方を聞いているので、失敗したタスクでも長さを見てくれます。

ちなみに、ドキュメント追加のPR(laravel/docs #11453)は閉じられていて、私が見た時点では公式ドキュメントに使い方が載っていませんでした(・_・;)

なので今回は、リリースノートとフレームワークのソースを読んで書いています。

🤔 数字で渡すと単位が違うのでハマる

ここが今回いちばん伝えたいところです!

しきい値には CarbonInterval・日時・数字のどれでも渡せるんですが、数字の扱いが2つのメソッドで違います。

メソッド数字で渡したときコールバックの時間
Queue::whenJobRunsLongerThan()ミリ秒として比較$duration(ミリ秒)
Schedule::whenTaskRunsLongerThan()秒として比較$runtime(秒)

キュー側は CarbonInterval を totalMilliseconds に変換し、JobAttempted の duration(ミリ秒)と比べています。

スケジュール側は totalSeconds に変換して、ScheduledTaskFinished の runtime(秒)と比べる作りです。

つまり、スケジュールと同じ感覚で Queue::whenJobRunsLongerThan(90, ...) と書くと、90秒ではなく90ミリ秒になってしまいます😭

ほぼ全部のジョブが「遅い」扱いになって、ログがあふれるパターンですね…

逆に、キューの感覚でスケジュールに 60000 と書くと、16時間以上かからないと呼ばれません( .. )

どちらも CarbonInterval::seconds() や minutes() で書けば、単位を気にしなくて済みます。

チームで書き方をそろえておくのが、いちばん手堅いと思います👍

👀 この仕組みでは気づけないケース

便利な一方で、「終わったあとに長さを測る」仕組みなので、拾えないケースもあります。

ソースを読んで分かったのは次の3つです👀

  • タイムアウトで止まったジョブ: 公式ドキュメントでは、#[Timeout] や --timeout を超えるとワーカーのプロセスごと終了すると説明されています。JobAttempted を出す前にプロセスが終わるので、ここには届かないと考えたほうが安全です
  • runInBackground() のタスク: schedule:run から見るとバックグラウンドに渡した時点で「終わった」扱いになり、runtime はほぼ0秒になります。本当に終わったときに出る ScheduledBackgroundTaskFinished には実行時間が入っていません
  • まだ実行中のもの: 終わってから判定するので、今まさに固まっているジョブは呼ばれません

1つ目は、ジョブの timeout を retry_after より短くする、#[FailOnTimeout] で失敗扱いにする、といった今までの設定で守る部分です。

2つ目が意外と盲点で、重いタスクほど runInBackground() を付けているので、一番見たいタスクが対象外になりがちなんですよね(´・ω・`)

バックグラウンドのタスクは、コマンドの中で開始と終了の時刻をログに出すか、withoutOverlapping() と組み合わせて重なりを防ぐ形が現実的だと思います。

ちなみに、HTTPリクエストやソケットの待ちはジョブのタイムアウトで止まらないことがある、と公式ドキュメントにも書かれています。

外部APIを呼ぶジョブは、Guzzle側の接続・応答のタイムアウトも決めておくと安心です🫡

🔧 私ならこう登録する

そのまま1行で登録すると、遅いジョブが100件流れたときに100回通知が飛んできます😭

なので私が入れるなら、しきい値を config に逃がして、同じジョブ名の通知は30分に1回にする形にします。

// config/monitoring.php
return [
    'slow_job_seconds' => (int) env('SLOW_JOB_SECONDS', 120),
    'slow_task_minutes' => (int) env('SLOW_TASK_MINUTES', 30),
];
// app/Providers/AppServiceProvider.php の boot()
use Carbon\CarbonInterval;
use Illuminate\Console\Scheduling\Event;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Queue;
use Illuminate\Support\Facades\Schedule;

Queue::whenJobRunsLongerThan(
    CarbonInterval::seconds(config('monitoring.slow_job_seconds')),
    function ($job, float $duration) {
        $name = $job->resolveName();

        // 同じジョブは30分に1回だけ通知する
        if (Cache::add("slow-job:{$name}", true, now()->addMinutes(30))) {
            Log::channel('slack')->warning('遅いジョブ', [
                'job' => $name,
                'queue' => $job->getQueue(),
                'seconds' => round($duration / 1000, 1),
            ]);
        }
    }
);

Schedule::whenTaskRunsLongerThan(
    CarbonInterval::minutes(config('monitoring.slow_task_minutes')),
    function (Event $task, float $runtime) {
        Log::channel('slack')->warning('遅い定期タスク', [
            'task' => $task->getSummaryForDisplay(),
            'minutes' => round($runtime / 60, 1),
        ]);
    }
);

ポイントは3つです。

  • 秒に直してから通知する: キュー側の $duration はミリ秒なので、Slackに出すときに / 1000 しておくと読み間違えません
  • Cache::add() で間引く: キーがなければ入れて true、あれば false なので、「最初の1回だけ通知」がこれだけで書けます
  • しきい値は環境ごとに変える: ステージングはデータが少ないので、本番と同じ値だとまず鳴りません。.env で下げて、一度鳴るのを確認してから本番に入れるのがおすすめです

Log::channel('slack') は config/logging.php に slack チャンネルがある前提です。

なければ普段の Log::warning() で十分で、ログ基盤側でアラートを組めばOKです(。•̀ᴗ-)✧

ちなみに、Queue::whenJobRunsLongerThan() はリスナーを登録するだけなので、Horizon を使っていてもいなくても動きます✨

ワーカーのプロセスで呼ばれるので、通知の処理が重いとジョブのスループットに響く点だけは気をつけたいところです!

🔗 関連記事と使い分け

パパ系Webエンジニア〜愛用ガジェット一覧 🛍️

この記事を書いている作業環境のガジェットを楽天ROOMにまとめています ✨ 在宅エンジニアのデスク作りの参考にどうぞ 🙌

🙌 まとめ

Laravel 13.40の2つのフックは、「遅くなってきた」をエラーになる前に知らせてくれる、小さいけど便利な追加でした。

正直、Horizon の画面をたまに眺めるくらいしかしていなかったので、サービスプロバイダに数行足すだけで見張り役が増えるのはかなり楽・・!

ただ、数字で書くと単位がキューはミリ秒・スケジュールは秒でそろっていないので、CarbonInterval で書くのが安全です。

タイムアウトで落ちたジョブと runInBackground() のタスクは拾えないので、そこは今までの設定と組み合わせて使うのがいいと思います🫡

みんなは夜間バッチの遅れ、どうやって気づいてますか?

※ バージョン番号・メソッドの挙動は今後も変わる可能性があります。最新情報は Laravel公式のリリースノート をご確認ください👀

参考になったらシェアしてもらえるとうれしいです🙌

Xでポスト Threads はてブ LINE