第10回: HorizonでQueue監視 — 「ジョブが溢れている」に気づくのは障害から何分後ですか？

(Updated: )
1 min read

章: 第4章: 非同期処理とイベント駆動

Queueのワーカーが死んでジョブが溢れている状態で、ユーザーから「メールが来ない」と見つかるまで数分かかることがあります。Laravel Horizonは、Queueの状態をリアルタイムで見るダッシュボードを提供し、そうした盲点を排除します。

失敗ジョブ数・待機時間・スループットを常に把握できるようになれば、ボトルネックを早期発見して運用の安定性が大きく上がります。

なぜHorizonが重要なのか

素のLaravel Queueの監視には次の限界があります。

  • php artisan queue:failed だけでは待機時間の増加に気づかない
  • キューごとのスループットが分からない
  • ワーカー数の調整根拠が手感で決まる

チェックポイント: Horizonは待機底から数だけでなく、処理時間・再試行回数・遅延時間などをダッシュボードから一括して確認できます。

Horizonで見るべき主要メトリクス

メトリクス 記込みの変化 考えられる原因
待機中ジョブ数 急増 ワーカー足りない
失敗数 増加 API/DB障害、コードエラー
待機時間（lag） 増加 負荷集中またはワーカー停止
処理時間（throughput） 低下 コードや外部コールの遅延

実装例


# インストール
composer require laravel/horizon
php artisan horizon:install
php artisan migrate

# 起動
php artisan horizon

# 監視画面
# /horizon にアクセスして、処理数・失敗ジョブ・待機時間を確認

config/horizon.php でキューにワーカーを割り当てる

負荷が高いキューにワーカーを多く割り当てることで、安定性とスループットを両立できます。常時監視を習慣化するだけで10分以内の異常検知率が大幅に向上します。

まとめ & 次のステップ

  • Horizonを導入するだけでQueueの内部状態が全て可視化される
  • 待機時間（lag）の増加を監視することで、ワーカー足りない構成を早期発見できる
  • config/horizon.php でキュー別にワーカー数を制御し、負荷に応じたリソース配分が可能
  • 本番ではsupervisorでHorizonプロセスを常駐化し、デプロイ時にはhorizon:terminateでグレースフルに再起動する

次回は 第11回: テスト戦略（Feature/Pest） で、仕様変更に強いテスト群を設計する方法を学びます。最初は少し難しく見えても、順番に確認すればちゃんと身についていきます。

今日の記事のポイント

Horizonを使うとQueue処理の状態を可視化し、ボトルネックを早く見つけられます。

この記事が大事な理由

失敗ジョブや待機時間を常に把握できるため、運用の安定性が上がるからです。

ここは「どの場面で使うのか」を結びつけると理解しやすくなります。実際のコードを動かしながら、少しずつ慣れていきましょう。

よくあるつまずき

まずは開発環境でダッシュボードを見ながら、どのキューに負荷があるか確認していきましょう。

「HorizonでQueue監視」でつまずくときは、知識不足というより「確認の順番」が曖昧なことが多いです。最初に観点を固定すると、理解が一気に進みやすくなります。

整理しやすい観点は次の3つです。

  • 失敗前提で設計する: 再試行・タイムアウト・通知を最初から定義する
  • 監視指標を固定する: 失敗件数だけでなく遅延時間と再試行回数も見る
  • ローカルと本番の差を把握する: ワーカー数や負荷条件を変えて挙動を比較する

小さく検証するときは、次の順番で進めると詰まりにくくなります。

1. 「HorizonでQueue監視」の設定を最小構成で動かし、正常系を確認する

2. 意図的に失敗を発生させ、再試行と通知が動くか確認する

3. 運用時の確認項目を3つ書き出してチームで共有する

「HorizonでQueue監視」は、成功時より失敗時の挙動を先に固めると安定運用しやすくなります。

実際のコードのサンプル

まずは最小構成で動きを確認していきましょう。


# インストール
composer require laravel/horizon
php artisan horizon:install
php artisan migrate

# 起動
php artisan horizon

# 監視画面
# /horizon にアクセスして、処理数・失敗ジョブ・待機時間を確認

この記事で身についたこと

Horizonを使うとQueue処理の状態を可視化し、ボトルネックを早く見つけられました。

今日のまとめ

HorizonでQueue監視は、実務でLaravelを扱ううえで心強い土台になります。焦らず、手を動かしながら自分のペースで育てていきましょう。

「HorizonでQueue監視」を学ぶときは、実装前に「何を楽にしたいのか」「どこで失敗しやすいか」「確認結果をどう残すか」を先に言葉にしておくと理解が安定します。短いメモでも、次回の見直し時に判断材料として大きく効いてきます。

「HorizonでQueue監視」で理解を深めるコツは、結果だけでなく途中の判断理由を残しておくことです。たとえば「この設定を選んだ理由」「別案を採用しなかった理由」「次に確認する項目」を短くメモしておくと、翌日に見直したときの再現性が高まります。実務ではこの記録がレビューや引き継ぎにもそのまま活用できます。

「HorizonでQueue監視」を実務で使うときは、設定値だけでなく運用時の確認観点までセットで決めておくと判断が安定します。特に「変更前に確認する項目」「変更後に監視する項目」「問題が起きたときの戻し方」を先に整理しておくと、手戻りを減らしやすくなります。

学習メモ

  • サンプルをそのまま実行したあと、値や条件を1つだけ変えて結果の違いを見ていきましょう。
  • 「HorizonでQueue監視」について、今日の気づきを1行で残しておくと次回の理解がかなり速くなります。
  • 実務に置き換えるならどの機能に使えるかを1つ書き出しておくと、学びが定着しやすくなります。

Related Articles