Laravel Queuesの retry_after と backoff の違い

はじめに

Laravelのジョブのリトライをする時に、どれくらいの間隔を空けて再度ジョブを実行するかを設定することは多いかと思います。
ドキュメントを見ると retry_after と backoff というジョブを再実行するための処理が2つあるようで、どう使い分けたら良いのかよく分からず調べました。

retry_after とは

retry_after はジョブのエラー・実行に関わらず retry_after に設定した秒数を超えてもジョブが終了していない場合に、ジョブをキューの後ろに何秒後に再度積み直すかの設定となります。

大事なことは、ここでのエラーとはLaravelに記録されない低レイヤーでのエラーとなります。

エラー	説明
🧨 プロセスがクラッシュ	Laravelのワーカープロセスが異常終了（例：Fatal Error, OOM）
🕸 ネットワーク切断	Redis や SQS との接続が切れ、完了通知できなかった
🕓 タイムアウト（SupervisorやDocker）	Laravelがジョブを完了する前にプロセスがkillされる
💻 OSレベルの強制終了	ホストの再起動や強制シャットダウン

これはLaravelでのエラー (throw $e やコード内でのエラーではありません)

この設定は

config/queue.php に書いてあります。

config/queue.php

        'redis' => [
            'driver' => 'redis',
            'connection' => env('REDIS_QUEUE_CONNECTION', 'default'),
            'queue' => env('REDIS_QUEUE', 'default'),
            'retry_after' => (int) env('REDIS_QUEUE_RETRY_AFTER', 90),  // <- これ
            'block_for' => null,
            'after_commit' => false,
        ],

backoff とは

backoffとは、ジョブの実行中（handle() 内で）にLaravel内でエラーが起きた時に、キューの後ろに何秒後に積み直すかという設定になります。

以下では明示的に throw で例外を投げていますが、throw以外でもコードによるエラーが発生した場合もbackoffの設定時間後に再度キューに積み直されます。

public function handle(): void
{
    try {
        // 何かしらの処理
    } catch($e) {
        throw $e;
    }
}

デフォルトでは失敗したジョブは 即座に キューの後ろに積み直される設定になっています。
backoff を設定する場合は以下のようにします。

public $backoff = 3; // プロパティとして定義

// or

public function backoff(): int  // 関数として定義（動的に決定したい場合など）
{
    return 3;
}

まとめ

上記の理解ですが、間違っていたらご助言をいただけますと幸いです。