cron + heartbeat）の問題を切り分けるためのものです。
確認コマンドの順番
cron が動かない
cron statusが有効状態を示し、将来のnextWakeAtMsが表示される。- ジョブが有効で、妥当なスケジュールとタイムゾーンを持っている。
cron runsにokまたは明示的なスキップ理由が表示される。
cron: scheduler disabled; jobs will not run automatically→ 設定または環境変数で cron が無効になっている。cron: timer tick failed→ スケジューラーの tick がクラッシュしているため、周辺のスタックトレースやログを確認する。- 実行結果に
reason: not-dueが出る →--forceなしで手動実行しており、まだ実行時刻になっていない。
cron は動いたが配信されない
- 実行ステータスが
okである。 - 分離ジョブ向けの配信モードとターゲットが設定されている。
- チャンネルプローブで対象チャンネルが接続済みと確認できる。
- 実行は成功したが配信モードが
none→ 外部メッセージは送られないのが正常です。 - 配信ターゲットが欠落または不正（
channel/to） → 内部処理は成功しても、外向きの配信はスキップされることがあります。 - チャンネル認証エラー（
unauthorized、missing_scope、Forbidden） → チャンネルの認証情報または権限不足で配信が止まっています。
heartbeat が抑制またはスキップされる
- heartbeat が 0 以外の間隔で有効になっている。
- 最後の heartbeat 結果が
ranである、またはスキップ理由を説明できる。
heartbeat skippedとreason=quiet-hoursが出る →activeHoursの時間外です。requests-in-flight→ メインレーンがビジーのため、heartbeat が延期されています。empty-heartbeat-file→HEARTBEAT.mdに実行可能な内容がなく、タグ付き cron イベントもキューにないため、定期 heartbeat がスキップされています。alerts-disabled→ 表示設定により外向きの heartbeat メッセージが抑制されています。
タイムゾーンと activeHours の落とし穴
Config path not found: agents.defaults.userTimezoneは、そのキーが未設定であることを意味します。heartbeat はホストのタイムゾーン（activeHours.timezoneが設定されていればそちら）へフォールバックします。--tzなしの cron は、ゲートウェイホストのタイムゾーンを使います。- heartbeat の
activeHoursは、設定されたタイムゾーン解決（user、local、または明示的な IANA tz）を使います。 - タイムゾーンを含まない ISO タイムスタンプは、cron の
atスケジュールでは UTC として扱われます。
- ホストのタイムゾーン変更後に、ジョブが意図しない時刻で実行される。
activeHours.timezoneが誤っているため、日中なのに heartbeat が常にスキップされる。