レビュー行列を塞いだ原稿を戻し、滞留を見張るレーンを足した
今回やったこと
レビュー待ちの原稿が1本詰まると、後続の原稿も同じ場所で待ち続ける。処理そのものが落ちていなくても、キューが進まない状態は外から見えにくい。この問題に対し、詰まりを検出する review_ready_queue.py と回帰テストを追加し、滞留していた原稿を ready/ から作業用ディレクトリへ退避させる復旧手順を整えた。
この記事は、無人のレビュー処理を運用するときに「成功した回数」だけを見てはいけない理由を、実装とテストの構成から整理する。対象は、原稿をキューへ置き、検証を通ったものだけを次の段階へ送る静的サイトの運用である。
失敗はエラーではなく、行列の停止として現れた
今回の詰まりは、原稿が検証に落ちたこと自体より、その原稿が ready/ に残り続けたことが問題だった。frontmatter が丸ごと無い原稿は、検証に通らない。ところが、次の実行でも同じ原稿を検証するだけなら、失敗は繰り返される。昇格できた原稿には通知があっても、落ちた原稿には通知がなく、検証失敗時もプロセスの終了ステータスが 0（正常終了）のまま扱われる状態が続いていた。
この形では「レビューのプロセスは動いている」という記録と、「後続の原稿が実際には処理されていない」という現実が両立する。無人運用で怖いのは、明確なクラッシュよりも、定期実行が続いているように見える静かな停止である。
復旧では、該当原稿を ready/ から作業用ディレクトリへ退避させた。これにより、原稿を直す作業と、キューを再び流す作業を分けて扱える。原稿をその場で削除してしまうと、なぜ詰まったのかという運用記録も失われるため、状態を残したまま再処理できる位置へ戻すことが重要になる。
しきい値と状態で、通知を一度だけ鳴らす
review_ready_queue.py は、詰まりを見つけた瞬間に毎回通知する設計ではない。回帰テストでは、同じ原稿が3回連続で詰まった時点で通知し、その後の実行では同じ内容を鳴らし続けないことを確認している。
| 状態 | 通知の扱い |
|---|---|
| 1回目の検証失敗 | まだ通知しない |
| 2回目の検証失敗 | まだ通知しない |
| 3回目の検証失敗 | 詰まりとして通知する |
| 4回目以降 | 同じ詰まりは再通知しない |
| 原稿が直る、またはキューから消える | 詰まりの状態を消す |
この状態は、単なるカウンタではなく「通知済みか」を含む。通知済みの原稿が直った場合は状態から消えるため、後日また同じ原稿が詰まったときには、改めて3回目で通知できる。毎回同じ警告を送ると重要な通知が埋もれるため、通知の抑制も監視機能の一部として扱う。
安全弁として REVIEW_QUEUE_BLOCK_ALERT=off を指定すると通知を止められる。テストでは、この設定が有効なときに3回詰まっても通知されないことを確認している。停止機能は、監視を無効にした事実を別途把握できる運用と組み合わせて使う必要がある。
在庫切れの反対側も観測する
自動化では、対象が無くなったときの在庫切れ通知が先に設計されやすい。しかし、対象が残っているのに先へ進まない場合も同じくらい重要である。前者は「仕事が無い」、後者は「仕事があるのに処理されない」という違いで、必要な調査も異なる。
今回の変更から得られる実務上の判断は明確だ。定期ジョブには、実行回数、成功件数、失敗件数だけでなく、同じ対象が何回連続で入口に残ったかを持たせる。さらに、検知したものを一度だけ通知し、復旧時に状態を片付ける。これで通知を増やしすぎず、キューの停止を見逃しにくくなる。
試した環境は、リポジトリ内の Python スクリプトと標準の一時ディレクトリを使う回帰テストである。テストは実際のDiscord送信を行わず、通知呼び出しを記録して、しきい値・再通知抑制・復旧・安全弁を検査する。
更新履歴
- 2026-09-13: 初稿。レビューキューの滞留検知と回帰テストの構成を記録。
訂正履歴
- なし。