「数字が変わらない」— 定期出力が止まった時に最初に疑う場所を間違えない

定期実行しているレポートやダッシュボードの数字が更新されなくなった。 ログを見てもエラーが1行も出ていない。スクリプトを手で動かすと普通に成功する。

この組み合わせに出会ったら、スクリプトのバグを探すのをやめる。 ほぼ確実に「そもそも起動していない」。

---

1. なぜ時間を溶かすのか

人は「出力がおかしい＝出力を作る処理がおかしい」と考える。だから実装を読み始める。 しかしトリガーが外れていた場合、処理は一度も走っていない。 走っていないものにバグは無いので、読んでも何も見つからない。

さらに悪いことに、この故障は気づくのが遅れる。 多くの実装は「前回の結果をキャッシュして、更新に失敗したら前回値を出す」設計になっている。 すると画面にはそれらしい数字が出続ける。誰も壊れていると思わない。

実例: ある定期レポートが6日間、古い集計値を「現在値」の顔で表示し続けた。 実際の値は表示の約1.27倍まで乖離していた。表示が空白やエラーになっていれば即日気づけたはずだった。

---

2. 診断順序（これを逆にやらない）

① トリガーが登録されているか

最初に見るのはここ。実装ではない。

• hook / cron / スケジューラ / CI のスケジュール定義に、その処理が今も載っているか
• 設定ファイルを他の自動処理が書き換えて、エントリごと消えていないか

設定ファイルは「自動整形」「自動マージ」「別PCからの同期」で黙って行が消えることがある。 消えても誰も通知してくれない。

② 手動実行が通るか

通るなら実装は無実。①か③の問題。 通らないなら、ここで初めて例外が読める。

③ 起動痕跡と突き合わせる

実装が「起動した証拠」を残しているなら、それを読む。

見るもの	読み方
ロックファイルの更新時刻	新しい → 起動はしている / 古い → 起動していない
state ファイルの lastRun	ここが止まった日 = 最後に完走した日
エラーログのサイズ	空は「正常」ではない。「起動していない」かもしれない

最重要: エラーログが空なのを「エラーが無い＝正常」と読まない。 「起動していない」と「起動して成功した」は、どちらもエラーログを空にする。 この2つを区別できるのは起動痕跡だけ。

---

3. 二度と沈黙させないための実装パターン

原因を直すだけでは足りない。次に壊れた時に気づける形にする。

(a) キャッシュを出すなら鮮度を必ず名乗らせる

古い値を今の値の顔で出すのが最大の実害。許容時間を超えたら先頭に1行付ける。

const MAX_AGE_MS = 6 * 60 * 60 * 1000;

function readCache(file) {
  let fd;
  try {
    fd = fs.openSync(file, 'r');
    const updatedAt = fs.fstatSync(fd).mtimeMs;
    const body = fs.readFileSync(fd, 'utf8');
    if (Date.now() - updatedAt < MAX_AGE_MS) return body;
    return `⚠️ この数値は ${fmt(updatedAt)} 時点のキャッシュです（更新に失敗しています）\n${body}`;
  } catch {
    return null;
  } finally {
    if (fd !== undefined) fs.closeSync(fd);
  }
}

実測で効く。導入後、最初の起動でいきなり10日分の滞留を拾った。

(b) 裏で走らせる子プロセスの出力を捨てない

stdio: 'ignore' は例外を闇に葬る。最低限 stderr はファイルに向ける。

const errFd = fs.openSync(ERROR_LOG, 'a');
const child = spawn(process.execPath, args, {
  detached: true,
  stdio: ['ignore', 'ignore', errFd],
});
child.once('error', (e) => { logError(e); releaseLock(); });
child.unref();

(c) 後始末を beforeExit に頼らない

beforeExit は異常終了では発火しない。 ロック解除とキャッシュ保存を beforeExit に置くと、落ちた時にロックが残り、 以後ずっと「前の実行が動作中」と誤認して起動をスキップし続ける。沈黙が永続化する。

try {
  await collect();
  cache.save();          // 成功した時だけ保存する
} catch (e) {
  logError(e);
  process.exitCode = 1;
} finally {
  releaseLock();         // 成否に関わらず必ず解放
}

(d) 非同期の完了を待ってから保存する

// NG: 投稿の完了前にプロセスが終わり得る。保存も解放もされない
fetch(url, opts).then(...).finally(() => save());

// OK
await fetch(url, opts);
save();

これが沈黙の典型的な発生源。「たまに更新される / たまにされない」の正体はほぼこれ。

(e) ロックに最大寿命を持たせる

プロセスが強制終了されると finally すら走らない。 ロックは「作成から N 分経っていたら無視して奪う」設計にしておく。

---

4. チェックリスト

定期出力を作ったら、最後にこれを確認する。

• トリガー登録が消えた時に気づける手段があるか
• キャッシュを返す経路に鮮度警告があるか
• 子プロセスの stderr が残るか
• ロック解除が finally にあるか
• ロックに最大寿命があるか
• 非同期処理を await してから保存しているか
• 「エラーログが空」を正常と判定していないか

---

5. まとめ

• 出力が更新されない時の調査順は ①トリガー登録 → ②手動実行 → ③実装。逆にやると溶ける。
• 空のエラーログは無罪の証明ではない。起動痕跡と必ず突き合わせる。
• キャッシュは自分が古いことを名乗る。黙って古い値を出すのが一番の害。
• beforeExit と stdio:'ignore' は沈黙製造機。finally と stderr 保存に置き換える。