ブログに戻る

Healthchecks.io で cron ジョブを監視:失敗や未実行をスマホにプッシュ通知

Healthchecks.io で cron ジョブを監視:失敗や未実行をスマホにプッシュ通知

cron ジョブは 2 通りの形で壊れます。1 つは実行されて失敗するケースです。pg_dump がデータベースに接続できない、ディスクが満杯になった、などです。もう 1 つは、そもそも実行されなくなるケースです。crontab の行が消えた、サーバーを作り直したときに登録し忘れた、cron デーモンが停止している、などです。前者はどこかにエラーが残ります。後者は何も残しません。そして、昨夜のバックアップが必要になった日に初めて気づくことになります。

ジョブが「失敗した」と報告してくるのを待つ通知の仕組みでは、そもそも開始されなかったジョブからの連絡は届きません。それを捉えるには逆の構成が必要です。ジョブは終了のたびに報告し、報告が届かなかったときに別の仕組みが警告を出します。

このガイドでは、オープンソースの cron 監視ツールである Healthchecks.io でこの仕組みを作り、そのアラートを Pocket Alert でスマホに届けます。失敗は目立つ通知で、復旧は控えめな通知で届きます。以下の内容はすべて、セルフホスト版 Healthchecks v5.0.3 の Docker イメージで検証しており、クラウド版でも同じように動作します。

必要なもの

  • healthchecks.io のアカウント(無料の Hobbyist プランで 20 個のジョブを監視できます)、または healthchecks/healthchecks Docker イメージで立てた自前のインスタンス
  • iPhone または Android の Pocket Alert アプリと、API キー。始めるだけなら無料プランで十分です。
  • cron ジョブを実行するマシンの curl

デッドマンスイッチ

Healthchecks ではこの仕組みをハートビート監視と呼びます。デッドマンスイッチの一種です。ジョブごとに チェック を作成し、ユニークな Ping URL を発行します。ジョブは終了時にその URL へリクエストを送ります。次のリクエストが時間内に届かないと、チェックは down になり、通知が送られます。

「時間内」かどうかは 2 つの設定で決まります。

  • Period(周期):Ping の期待頻度です。毎時、毎日などを指定します。
  • Grace time(猶予時間):期待時刻を過ぎてから、Healthchecks が down と判断するまでの待ち時間です。ジョブが通常かかる時間より長めに設定してください。

cron ジョブの場合は、スケジュールの種類として Cron を選び、crontab の式とサーバーのタイムゾーンを入力します。こうすると、Healthchecks は一定間隔だけでなく、一日の中の正しい時刻に Ping が届くことを期待するようになります。式の意味は cron 式エディタで確認できます。

検証では、スケジュール */2 * * * *、猶予時間 1 分のチェックが 16:09:13 に Ping を受けました。16:10 には Ping がなく、チェックは 16:11:00 にちょうど猶予時間分だけ経ってから down になりました。

Ping URL にはいくつかの種類があります。

リクエスト意味
https://hc-ping.com/<uuid>成功。ジョブが完了しました。
https://hc-ping.com/<uuid>/startジョブを開始しました。Healthchecks は猶予時間内に成功の通知を期待するようになり、実行時間も記録します。
https://hc-ping.com/<uuid>/failジョブが失敗しました。チェックはすぐに down になります。
https://hc-ping.com/<uuid>/<0-255>終了ステータス。0 は成功、それ以外は失敗として扱われます。

セルフホスト版では、ベースとなる URL は自分のドメインに /ping/ を付けたものになります。例:https://hc.example.com/ping/<uuid>。

cron ジョブに組み込む

チェックを作成し、Ping URL をコピーして、crontab の行を変更します。Debian 13 の cron デーモンで検証しました。

PING=https://hc-ping.com/your-check-uuid
15 3 * * * curl -fsS -m 10 --retry 5 -o /dev/null $PING/start; /usr/local/bin/backup.sh; curl -fsS -m 10 --retry 5 -o /dev/null $PING/$?

PING= は crontab の変数で、シェルがコマンド内で展開します。この行は 3 つのことをしています。

  • /start を送ります。そのため、ハングしたジョブは猶予時間が過ぎると down になります。検証では、後続の通知がない /start のみが送られたチェックが、ちょうど猶予時間分だけ経ってから down になりました。
  • ジョブを実行します。
  • ジョブの終了ステータスである $? を送ります。正常終了なら /0、失敗なら /2 などスクリプトが返した値が送られ、チェックはすぐに down になります。

curl のオプションは、Ping 自体が問題を起こさないようにするためのものです。

  • -m 10:各リクエストを 10 秒で打ち切ります。止まった /start がジョブを待たせないようにします。
  • --retry 5:タイムアウトや HTTP 408、429、500、502、503、504 の応答を、間隔を徐々に延ばしながら再試行します。パケットが 1 つ落ちただけで通知が鳴ることはありません。
  • -fsS:HTTP エラーで curl を失敗させ、問題がない限り出力を抑えます。cron が進捗バーをメールで送ってくることを防ぎます。
  • -o /dev/null:レスポンス本文を捨てます。本文は OK だけです。

ジョブが pg_dump | gzip > dump.gz のようなパイプラインの場合、その終了ステータスは gzip ではなく pg_dump のものになります。bash で set -o pipefail を指定したスクリプトに入れてください。そうしないと、ダンプが失敗しても成功として報告されてしまいます。

runitor に任せる

runitor は、コマンドをラップして Ping を処理する小さな Go 製バイナリです。実行前に /start、実行後に終了ステータスを送り、コマンドの出力の最後の 10,000 バイトを Ping に添付します。

curl -fsSL -o /usr/local/bin/runitor https://github.com/bdd/runitor/releases/download/v1.4.1-build.6/runitor-v1.4.1-build.6-linux-amd64
chmod +x /usr/local/bin/runitor

crontab の行は短くなります。

15 3 * * * CHECK_UUID=your-check-uuid /usr/local/bin/runitor -- /usr/local/bin/backup.sh

セルフホスト版の場合は、HC_API_URL=https://hc.example.com/ping を追加します。runitor v1.4.1 を cron でこの形で動かしたところ、失敗したバックアップはステータス 2 でチェックを down にし、そのエラー出力がアラートに含まれて届きました。

Pocket Alert に通知を送る

Healthchecks は汎用の Webhook 連携を通じて Pocket Alert と接続します。Integrations を開き、Webhook を見つけて Add Integration をクリックします。フォームには「チェックが down になったときに実行」と「チェックが up になったときに実行」の 2 つのセクションがあり、それぞれに URL、メソッド、本文、ヘッダーを設定します。この分け方により、「down」は目立つ通知、「up」は控えめな通知にできます。

どちらのセクションでもプレースホルダーを使えます。$NAME、$NAME_JSON、$STATUS、$NOW、$CODE、$SLUG、$TAGS、$EXITSTATUS、$BODY、$BODY_JSON、$JSON などがあります。JSON 本文では違いに注意してください。$NAME はそのまま貼り付けられるため、Nightly "db" backup のようなチェック名があると JSON が壊れます。一方 $NAME_JSON は引用符を含めた完全な JSON 文字列です。$BODY と $BODY_JSON も同じ関係です。

方法 1:API に直接送る

down のセクションでは、メソッドに POST、URL に https://api.pocketalert.app/v1/messages を選びます。リクエストヘッダーは 1 行に 1 つずつ書きます。

Content-Type: application/json
Token: YOUR_API_KEY

リクエスト本文:

{
  "title": $NAME_JSON,
  "message": "DOWN since $NOW. Exit status of the last ping: $EXITSTATUS",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/$CODE/details/"}]
}

up のセクションは、メソッド、URL、ヘッダーは同じで、本文をより控えめにします。

{
  "title": $NAME_JSON,
  "message": "Back up at $NOW",
  "level": "low"
}

Save Integration をクリックします。新しい連携はプロジェクト内の既存のすべてのチェックに紐づきます。以下は、検証用のチェックが失敗したときに Healthchecks が送ってきた内容です。

{
  "title": "Nightly \"db\" backup",
  "message": "DOWN since 2026-10-31T16:15:01+00:00. Exit status of the last ping: 2",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/a4b72803-3a50-4b81-b33f-88dd2200ffc2/details/"}]
}

この本文についての補足です。

  • high は時間に敏感な通知です。 集中モードや予約されたサマリーを突破して届きます。有料プランでは critical に変更すると、止まったバックアップジョブが、サイレントスイッチやおやすみモードを越えて通知します。無料プランでは critical も受け付けられ、high として届きます。
  • 復旧には low を使います。 「Back up」はフィードに音なしで入ります。知っておきたいけれど、午前 3 時に起こされるほどではない内容に向いています。
  • $EXITSTATUS で失敗と未実行を区別できます。 アラートの直前にあった最後の Ping の終了ステータスです。2 ならジョブが実行され、2 を返したことを意味します。0 で down になった場合は、最後の実行は成功したのに次の実行が来なかったことを意味します。-1 は最後の Ping に終了ステータスがなかったことを意味します。単純な成功 URL、/fail、/start のいずれかです。
  • ボタン は Healthchecks でチェックを開きます。セルフホスト版では、URL に自分のドメインを入れてください。アクションボタンは有料機能です。無料プランではボタンは削除されますが、メッセージ本体は通常どおり届きます。

方法 2:テンプレート付きの Pocket Alert Webhook

2 つ目の方法は、小さな JSON を Pocket Alert の Webhook に送り、Pocket Alert 側で通知を整形する方式です。利点は、ジョブの出力を含められることです。

Pocket Alert のコンソールで Webhooks を開き、Healthchecks という名前で作成して、メッセージテンプレートを設定します。

%name% is %status% since %time%
%log%

Default priority は未選択のままにしてください。優先度はペイロード側で指定するためです。Webhook URL をコピーします。https://p4a.me/wh/abc123xyz のような形式です。この URL は秘密情報なので、パスワードと同じように扱ってください。

Healthchecks で、この URL を使った Webhook 連携を作成します。両方のセクションで POST、ヘッダーは Content-Type: application/json を指定し、本文には次のものを使います。down 用:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "high"}

up 用:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "low"}

$BODY_JSON は最後の Ping の本文で、runitor がジョブの出力を入れる場所です。検証で runitor のラップされたバックアップが失敗したとき、プッシュ通知にはこう表示されました。

Webhook Healthchecks
DB backup (runitor) is down since 2026-10-31T16:15:02+00:00
dumping appdb
pg_dump: error: connection to server on socket failed: No such file or directory

[runitor] exit status 2

Pocket Alert は受信ペイロードのトップレベルの level フィールドを読み取るため、high と low は方法 1 と同じように機能します。runitor を使わない場合、$BODY_JSON は空文字列になり、2 行目は空白になります。API ではこれはできません。$BODY_JSON は完全な JSON 文字列なので、message 全体にしかなりえず、Ping に本文がない場合はメッセージが空になり、API が拒否します。

ほかにも 2 つの違いがあります。プッシュ通知のタイトルは常に Webhook <name> になるため、チェック名はメッセージ側に入れる必要があります。また、Webhook のボタンはコンソールのフォームではなく、Webhooks API の actions フィールドで設定します。

テストする

Healthchecks の Integrations ページでは、各連携に Test! ボタンがあります。TEST という名前のチェックについて「down」通知を送り、それが high のプッシュ通知として届きます。その後、終了コード 1 で終わるジョブを実行して、実際のアラートが届くか確認してください。

Healthchecks を使わない場合:失敗時にプッシュするラッパー

別のサービスを増やしたくない場合、短いラッパーで最も一般的なケース、つまりエラー終了するジョブには対応できます。/usr/local/bin/cron-alert として保存します。

#!/bin/sh
# Usage: cron-alert <job name> <command> [args...]
name="$1"
shift

log=$(mktemp)
"$@" >"$log" 2>&1
status=$?

if [ "$status" -ne 0 ]; then
  curl -fsS -m 10 --retry 3 --retry-max-time 30 -o /dev/null \
    -H "Token: $POCKETALERT_API_KEY" \
    --form-string "title=Cron failed: $name on $(hostname)" \
    --form-string "message=Exit status $status. $(tail -c 2000 "$log")" \
    --form-string "level=high" \
    "${POCKETALERT_API_URL:-https://api.pocketalert.app/v1/messages}"
fi

cat "$log"
rm -f "$log"
exit "$status"

crontab には次のように書きます。

POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh

ここでの意図的な選択は次のとおりです。

  • JSON ではなく --form-string を使います。 API はマルチパートのフォームデータを受け付けます。--form-string は出力を引用符や改行を含めてそのまま送るため、jq やエスケープは不要です。普通の -F だと、@ や < で始まる値をファイルとして扱ってしまいます。
  • tail -c 2000 で出力の末尾を残します。エラーは通常そこにあるからです。
  • --retry-max-time 30 は重要です。1 日のメッセージ上限を超えると、API は 429 と、UTC 午前 0 時までの秒数を示す Retry-After を返します。curl の --retry はこれを尊重します。検証では、このオプションがないと、curl は Retry-After: 30000 で待ち続け、こちらが強制終了するまで止まりませんでした。このオプションを付けると、curl は 1 回試行しただけで諦めます。
  • ラッパーは終了ステータスを保持し、出力を表示します。 そのため、cron のログや MAILTO は従来どおり動きます。

shellcheck は通ります。Debian 13 の cron で実行した際には、失敗したバックアップが「Cron failed: nightly backup on」にホスト名を続けたタイトルで届き、本文には pg_dump のエラーが含まれていました。

このラッパーにできないことも明確にしておきます。ラッパーは、cron がそれを実行したときにしか動きません。crontab の行が消えたり、デーモンが停止したり、マシンの電源が切れていたりすると、何も送信されません。これは、この記事の冒頭で述べた無言の失敗そのものです。永遠にハングするジョブも気づかれません。こうしたケースには、マシンの外側でハートビートを待ち続ける仕組みが必要です。それが Healthchecks の役割です。curl の呼び出しを置き換えたい場合は、Pocket Alert CLI を使うこともできます。

正直な制限

  • 通知するには Healthchecks が稼働している必要があります。 クラウド版ならそれは提供側の仕事です。cron ジョブと同じマシンにセルフホストすると、マシンが落ちたときに監視も一緒に止まります。別の場所で動かしてください。
  • Healthchecks の本文テンプレートは 1,000 文字に制限されています。 上記の本文であれば十分ですが、長い手書きのメッセージには足りません。
  • 長い出力はプッシュ通知で切り詰められます。 プッシュ通知には、メッセージの先頭およそ 3 KB が含まれます。全文はアプリのメッセージ履歴にあります。
  • アラートは 1 件につき 1 通です。 数分ごとに down と up を繰り返すジョブは、そのたびにプッシュ通知を送ります。無料プランの 1 日 50 件では、すぐに上限に達します。ジョブを修正するか、猶予時間を延ばしてください。

通知が届かないとき

  • まず Test! ボタンを使います。 テストは届くのに実際のアラートが届かない場合は、そのチェックのページで、連携がそのチェックに対して有効になっているか確認してください。
  • Healthchecks の Integrations ページを確認します。 失敗している連携には、そこに Failed と表示されます。カーソルを合わせると、Received status code 401 のような最後のエラーが見られます。401 は Token ヘッダーが間違っていることを意味します。400 は通常、本文が有効な JSON ではないことを意味します。$NAME_JSON を使っているか、"$NAME" のように引用符で囲んでいないか確認してください。
  • 新しいチェックは、最初の Ping を受けるまでアラートを出しません。 それまでは「down」ではなく「new」の状態です。
  • cron チェックのタイムゾーンを確認します。 常に 1 時間早い、または遅いと表示される場合は、サーバーのタイムゾーンとチェックに設定したタイムゾーンが一致していません。
  • フィードを確認します。 low のプッシュ通知は音が鳴らないため、復旧通知が届いていないように見えることがあります。

FAQ

API 経由と Webhook 経由のどちらを使うべきですか?

API 経由では、チェック名がプッシュ通知のタイトルに入り、Pocket Alert 側で何も作成する必要はありません。Webhook 経由ではジョブの出力を含められるため、runitor を使う場合は Webhook を選んでください。

「down」の通知だけを受け取れますか?

はい。上記のように「up」には控えめな low の本文を使うか、「up」の URL を空欄にしておきます。そうすると、復旧時には Healthchecks は何も送信しません。

systemd タイマーの場合はどうすればいいですか?

考え方は同じです。Healthchecks には OnCalendar のスケジュール種別があり、タイマーと同じ式を指定できます。/start から ExecStartPre を送るか、ExecStart のコマンドを runitor でラップしてください。

cron アラートについて詳しく読むには?

cron ジョブのアラートページでは、ジョブ自体からプッシュ通知を送る方法を解説しています。バックアップのアラートページではバックアップツールを扱い、Proxmox ガイドではハイパーバイザー上のバックアップを扱っています。

無料アカウントを作成して、Healthchecks に Webhook 連携を 1 つ追加してください。そして、静かに実行されなくなったジョブが、あなたを起こす役目を担うようにしましょう。

この記事をシェア