Monitoring cron job dengan Healthchecks.io: push notification ke HP saat job gagal atau tidak berjalan

Sebuah cron job bisa rusak dengan dua cara. Ia bisa berjalan lalu gagal: pg_dump tidak dapat terhubung ke database, atau disk penuh. Atau ia sama sekali tidak berjalan: baris crontab terhapus, server dibangun ulang tanpa baris itu, atau daemon cron sudah mati. Jenis pertama meninggalkan error di suatu tempat. Jenis kedua tidak meninggalkan apa-apa, dan Anda baru tahu pada hari Anda membutuhkan backup semalam.
Alert yang menunggu job berkata "saya gagal" tidak akan pernah mendengar dari job yang tidak pernah dimulai. Untuk menangkap kasus itu, Anda butuh pengaturan kebalikannya: job melapor setiap kali selesai, dan sesuatu yang lain membunyikan alarm ketika laporan itu tidak datang.
Panduan ini membangunnya dengan Healthchecks.io, monitor cron open-source, dan mengirim alert-nya ke HP Anda lewat Pocket Alert. Kegagalan datang dengan keras, pemulihan datang dengan tenang. Semua yang ada di bawah diuji dengan Docker image self-hosted Healthchecks v5.0.3, dan berfungsi sama di layanan hosted.
Yang Anda butuhkan
- Akun Healthchecks di healthchecks.io (paket Hobbyist gratis memantau 20 job), atau instance Anda sendiri dari Docker image
healthchecks/healthchecks. - Aplikasi Pocket Alert di HP iPhone atau Android Anda dan kunci API dari API Keys. Paket Gratis sudah cukup untuk memulai.
curldi mesin yang menjalankan cron job.
Dead man's switch
Healthchecks menyebut ini heartbeat monitoring, sejenis dead man's switch. Setiap job mendapat check dengan ping URL unik yang diminta job saat ia selesai. Jika permintaan berikutnya tidak datang tepat waktu, check berubah menjadi down dan alert dikirim.
Dua pengaturan menentukan "tepat waktu":
- Period adalah seberapa sering Anda mengharapkan ping: setiap jam, setiap hari.
- Grace time adalah berapa lama Healthchecks menunggu melewati waktu yang diharapkan sebelum menyatakan down. Atur lebih lama dari durasi job biasanya, ditambah sedikit cadangan.
Untuk cron job, pilih tipe jadwal Cron dan tempel ekspresi dari crontab Anda, beserta zona waktu server. Healthchecks kemudian mengharapkan ping pada jam yang tepat, bukan sekadar pada interval yang tepat. Editor ekspresi cron menjelaskan arti sebuah ekspresi.
Dalam pengujian kami, sebuah check dengan jadwal */2 * * * * dan grace time satu menit di-ping pada pukul 16:09:13. Tidak ada yang mem-ping pada pukul 16:10, dan check menjadi down pada pukul 16:11:00, tepat satu grace period kemudian.
Ping URL memiliki beberapa varian:
| Permintaan | Arti |
|---|---|
https://hc-ping.com/<uuid> | Berhasil. Job selesai. |
https://hc-ping.com/<uuid>/start | Job dimulai. Healthchecks kini mengharapkan keberhasilan dalam grace time dan mencatat durasi eksekusi. |
https://hc-ping.com/<uuid>/fail | Job gagal. Check langsung menjadi down. |
https://hc-ping.com/<uuid>/<0-255> | Status keluar. 0 dihitung sebagai berhasil, selain itu sebagai gagal. |
Pada instance self-hosted, basisnya adalah domain Anda ditambah /ping/, misalnya https://hc.example.com/ping/<uuid>.
Pasang ke cron job
Buat check, salin ping URL-nya, lalu ubah baris crontab. Kami menjalankannya di bawah daemon cron pada Debian 13:
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= adalah variabel crontab, yang diekspansi shell di dalam perintah. Baris ini melakukan tiga hal:
- Mengirim
/start, sehingga job yang macet menjadi down setelah grace time habis. Dalam pengujian kami,/starttanpa tindak lanjut membuat check down tepat satu grace period kemudian. - Menjalankan job.
- Mengirim
$?, status keluar job. Eksekusi bersih mengirim/0, eksekusi gagal mengirim/2atau apa pun yang dikembalikan skrip, dan check langsung menjadi down.
Flag curl mencegah ping itu sendiri menimbulkan masalah:
-m 10membatasi setiap permintaan hingga 10 detik./startyang macet tidak boleh menahan job.--retry 5mengulang timeout dan respons 408, 429, 500, 502, 503 dan 504, dengan jeda yang makin lama. Satu paket yang hilang tidak seharusnya membunyikan alarm.-fsSmembuat curl gagal pada error HTTP dan tetap diam kecuali ada yang salah, sehingga cron tidak mengirimi Anda progress bar curl lewat email.-o /dev/nullmembuang body respons, yang hanya berisiOK.
Jika job berupa pipeline seperti pg_dump | gzip > dump.gz, status keluarnya adalah status gzip, bukan pg_dump. Pindahkan ke skrip dengan set -o pipefail di bash, agar dump yang gagal tidak melaporkan keberhasilan.
Atau biarkan runitor yang mengerjakannya
runitor adalah binary Go kecil yang membungkus sebuah perintah dan menangani ping: /start sebelum, status keluar sesudah, dan 10.000 byte terakhir dari output perintah dilampirkan ke 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
Baris crontab menjadi lebih pendek:
15 3 * * * CHECK_UUID=your-check-uuid /usr/local/bin/runitor -- /usr/local/bin/backup.sh
Untuk instance self-hosted, tambahkan HC_API_URL=https://hc.example.com/ping. Kami menjalankan runitor v1.4.1 dengan cara ini di bawah cron: backup yang gagal membuat check down dengan status keluar 2, dan output error-nya muncul di alert.
Kirim alert ke Pocket Alert
Healthchecks terhubung ke Pocket Alert melalui integrasi Webhook generiknya. Buka Integrations, cari Webhook, lalu klik Add Integration. Formulirnya memiliki dua bagian, "Execute when a check goes down" dan "Execute when a check goes up", masing-masing dengan URL, method, body, dan header sendiri. Pemisahan itu membuat "down" terdengar keras dan "up" tenang.
Kedua bagian menerima placeholder: $NAME, $NAME_JSON, $STATUS, $NOW, $CODE, $SLUG, $TAGS, $EXITSTATUS, $BODY, $BODY_JSON, $JSON dan beberapa lainnya. Untuk body JSON, perhatikan perbedaannya: $NAME ditempel mentah, sehingga check bernama Nightly "db" backup merusak JSON, sedangkan $NAME_JSON adalah string JSON lengkap, termasuk tanda kutipnya. Hal yang sama berlaku untuk $BODY dan $BODY_JSON.
Opsi 1: langsung ke API
Di bagian down, pilih POST dan URL https://api.pocketalert.app/v1/messages. Header permintaan, satu per baris:
Content-Type: application/json
Token: YOUR_API_KEY
Body permintaan:
{
"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/"}]
}
Di bagian up, method, URL, dan header yang sama, dengan body yang lebih tenang:
{
"title": $NAME_JSON,
"message": "Back up at $NOW",
"level": "low"
}
Klik Save Integration. Integrasi baru dilampirkan ke semua check yang ada di proyek. Inilah yang dikirim Healthchecks ketika check pengujian kami gagal:
{
"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/"}]
}
Beberapa catatan tentang body ini:
highbersifat mendesak. Ia menembus Fokus dan ringkasan terjadwal. Pada paket berbayar, ubah menjadicriticaldan job backup yang mati akan membangunkan Anda melewati mode senyap dan Jangan Ganggu. Pada paket Gratis,criticalditerima dan dikirim sebagaihigh.lowuntuk pemulihan. "Back up" masuk ke feed tanpa suara. Anda ingin tahu, tetapi tidak pada jam 3 pagi.$EXITSTATUSmembedakan gagal dari tidak berjalan. Itu adalah status keluar dari ping terakhir sebelum alert.2berarti job berjalan dan mengembalikan 2. Down dengan0berarti eksekusi terakhir berhasil dan eksekusi berikutnya tidak pernah datang.-1berarti ping terakhir tidak membawa status keluar: URL sukses biasa,/fail, atau/start.- Tombolnya membuka check di Healthchecks. Untuk instance self-hosted, masukkan domain Anda sendiri ke URL. Tombol aksi adalah fitur berbayar; pada paket Gratis tombol itu dihapus dan pesannya tetap dikirim seperti biasa.
Opsi 2: webhook Pocket Alert dengan template
Cara kedua mengirim dokumen JSON kecil ke webhook Pocket Alert, yang kemudian memformat push-nya. Keunggulannya: ia bisa menyertakan output job.
Buka Webhooks di konsol Pocket Alert, buat satu bernama Healthchecks, dan atur template pesannya:
%name% is %status% since %time%
%log%
Biarkan Default priority tidak dipilih, karena payload membawa level-nya sendiri. Salin URL webhook, yang tampak seperti https://p4a.me/wh/abc123xyz. URL itu adalah rahasia, jadi perlakukan seperti kata sandi.
Di Healthchecks, buat integrasi webhook dengan URL itu sebagai POST di kedua bagian, header Content-Type: application/json, dan body berikut. 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 adalah body dari ping terakhir, tempat runitor menaruh output job. Ketika backup yang dibungkus runitor gagal dalam pengujian kami, push-nya berbunyi:
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 membaca field level di tingkat atas dari payload masuk, sehingga high dan low berfungsi seperti pada Opsi 1. Tanpa runitor, $BODY_JSON berupa string kosong dan baris kedua menjadi kosong. API tidak bisa melakukan ini: $BODY_JSON adalah string JSON lengkap, sehingga ia hanya bisa menjadi seluruh message, dan ketika ping tidak memiliki body, message itu kosong dan API menolaknya.
Dua perbedaan lain: judul push selalu Webhook <name>, sehingga nama check dimasukkan ke dalam pesan, dan tombol webhook diatur melalui field actions pada API webhook, bukan lewat formulir konsol.
Uji coba
Di halaman Integrations Healthchecks, setiap integrasi memiliki tombol Test!. Tombol itu mengirim notifikasi "down" untuk check bernama TEST, yang tiba sebagai push high. Kemudian jalankan job yang keluar dengan 1 dan lihat alert sungguhan datang.
Tanpa Healthchecks: wrapper yang mengirim push saat gagal
Jika Anda tidak ingin layanan lain, sebuah wrapper pendek menangani kasus paling umum, yaitu job yang keluar dengan error. Simpan sebagai /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"
Dan di crontab:
POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh
Beberapa pilihan yang disengaja:
--form-stringalih-alih JSON. API menerima data multipart form, dan--form-stringmengirim output apa adanya, termasuk tanda kutip dan baris baru, tanpajqatau escaping.-Fbiasa akan memperlakukan nilai yang diawali@atau<sebagai file.tail -c 2000menyimpan bagian akhir output, tempat error biasanya berada.--retry-max-time 30penting. Jika melewati batas pesan harian, API menjawab429denganRetry-Afterberupa jumlah detik hingga tengah malam UTC, dan--retrydari curl menghormatinya. Dalam pengujian kami, tanpa flag ini curl menungguRetry-After: 30000sampai kami menghentikannya. Dengan flag ini, curl menyerah setelah satu percobaan.- Wrapper mempertahankan status keluar dan mencetak output, sehingga log cron dan
MAILTOtetap bekerja seperti sebelumnya.
Skrip ini lolos shellcheck, dan di bawah cron pada Debian 13 backup yang gagal tiba sebagai "Cron failed: nightly backup on" ditambah nama host, dengan error pg_dump di dalam teks.
Perlu jelas tentang apa yang tidak bisa dilakukan ini. Wrapper hanya berjalan ketika cron menjalankannya. Jika baris crontab terhapus, daemon mati, atau mesin mati, tidak ada yang dikirim: kegagalan senyap dari awal artikel ini. Job yang macet selamanya juga tidak terdeteksi. Untuk kasus itu Anda butuh sesuatu di luar mesin yang menunggu heartbeat, dan itulah fungsi Healthchecks. CLI Pocket Alert dapat menggantikan pemanggilan curl jika Anda lebih suka begitu.
Batasan yang jujur
- Healthchecks harus tetap aktif agar bisa mendeteksi. Pada layanan hosted, itu tugas mereka. Jika Anda self-host di mesin yang sama dengan cron job, mesin yang mati akan ikut mematikan monitor. Jalankan di tempat lain.
- Template body dibatasi 1.000 karakter di Healthchecks. Itu cukup untuk body di atas, tetapi tidak untuk pesan panjang yang ditulis manual.
- Output panjang dipotong dalam push. Push membawa sekitar 3 KB pertama dari pesan; teks lengkapnya ada di riwayat pesan di aplikasi.
- Setiap alert adalah satu pesan. Job yang bolak-balik down dan up setiap beberapa menit mengirim push setiap kali, dan pada paket Gratis dengan batas 50 pesan per hari, jumlahnya cepat habis. Perbaiki job-nya, atau naikkan grace time.
Jika tidak ada yang datang
- Gunakan tombol Test! terlebih dahulu. Jika tes datang tetapi alert sungguhan tidak, pastikan integrasinya diaktifkan untuk check tersebut di halaman check.
- Periksa halaman Integrations di Healthchecks. Integrasi yang gagal ditandai Failed di sana; arahkan kursor untuk melihat error terakhir, misalnya
Received status code 401.401berarti headerTokensalah.400biasanya berarti body bukan JSON yang valid: pastikan Anda memakai$NAME_JSONtanpa tanda kutip di sekelilingnya, dan bukan"$NAME". - Check baru tidak memberi alert sampai ping pertamanya. Sampai saat itu ia berstatus "new", bukan "down".
- Periksa zona waktu check cron. Jika check selalu terlambat atau terlalu cepat satu jam, zona waktu server tidak sama dengan yang ada di check.
- Lihat di feed. Push
lowtidak berbunyi, jadi pemulihan bisa tampak seperti tidak pernah datang.
FAQ
Sebaiknya saya memakai rute API atau rute webhook?
Rute API menaruh nama check di judul push dan tidak memerlukan pembuatan apa pun di Pocket Alert. Rute webhook bisa menyertakan output job, jadi jika memakai runitor, pilih webhook.
Bisakah saya hanya menerima alert "down"?
Bisa. Gunakan body low yang tenang untuk "up", seperti di atas, atau kosongkan URL "up" dan Healthchecks tidak mengirim apa pun saat pemulihan.
Bagaimana dengan systemd timer?
Idenya sama. Healthchecks memiliki tipe jadwal OnCalendar yang menerima ekspresi yang sama dengan timer Anda. Kirim /start dari ExecStartPre, atau bungkus perintah ExecStart dengan runitor.
Di mana saya bisa membaca lebih lanjut tentang alert cron?
Halaman alert cron job membahas pengiriman push dari job itu sendiri, alert backup membahas alat backup, dan panduan Proxmox membahas backup pada hypervisor.
Buat akun gratis, tambahkan satu integrasi webhook di Healthchecks, dan biarkan job yang diam-diam berhenti berjalan itu yang membangunkan Anda.