블로그로 돌아가기

Healthchecks.io로 크론 작업 모니터링: 작업이 실패하거나 실행되지 않으면 휴대폰으로 푸시 알림

Healthchecks.io로 크론 작업 모니터링: 작업이 실패하거나 실행되지 않으면 휴대폰으로 푸시 알림

크론 작업은 두 가지 방식으로 망가질 수 있습니다. 실행은 되지만 실패하는 경우입니다. pg_dump가 데이터베이스에 연결하지 못하거나 디스크가 가득 찰 수 있습니다. 다른 하나는 아예 실행되지 않는 경우입니다. crontab 줄이 삭제되거나, 설정 없이 서버를 다시 구축하거나, cron 데몬이 죽어 있을 수 있습니다. 앞의 경우에는 어딘가에 오류가 남습니다. 뒤의 경우에는 아무것도 남지 않아서, 어젯밤 백업이 필요한 날에야 문제를 알게 됩니다.

작업이 "실패했다"고 알려 주기를 기다리는 알림 방식으로는 시작조차 하지 않은 작업을 잡아낼 수 없습니다. 이를 잡으려면 반대 방향의 구성이 필요합니다. 작업이 끝날 때마다 보고를 보내고, 그 보고가 오지 않을 때 다른 쪽에서 경보를 울리는 방식입니다.

이 가이드는 오픈소스 크론 모니터링 도구인 Healthchecks.io로 이 구성을 만들고, 알림은 Pocket Alert로 휴대폰에 보내는 방법을 다룹니다. 실패는 강하게, 복구는 조용하게 알려 줍니다. 아래 내용은 셀프 호스팅 Healthchecks v5.0.3 Docker 이미지에서 테스트했고, 호스팅 서비스에서도 동일하게 동작합니다.

준비물

  • healthchecks.io 계정(무료 Hobbyist 플랜은 작업 20개를 모니터링할 수 있습니다), 또는 healthchecks/healthchecks Docker 이미지로 직접 설치한 인스턴스.
  • 휴대폰에 설치한 Pocket Alert 앱(iPhone 또는 Android)과 API 키 페이지에서 발급받은 API 키. 시작하는 데는 무료 플랜으로 충분합니다.
  • 크론 작업을 실행하는 기기에 설치된 curl.

데드 맨 스위치

Healthchecks는 이를 하트비트 모니터링, 즉 일종의 데드 맨 스위치라고 부릅니다. 작업마다 체크가 하나씩 생기고, 이 체크에는 고유한 핑 URL이 있습니다. 작업이 끝날 때 이 URL로 요청을 보냅니다. 다음 요청이 제시간에 도착하지 않으면 체크가 다운 상태가 되고 알림이 발송됩니다.

"제시간"은 두 설정으로 정해집니다.

  • 주기는 핑을 얼마나 자주 받을지 정합니다. 매시간, 매일 같은 식입니다.
  • 유예 시간은 예상 시각이 지난 뒤 Healthchecks가 다운으로 판단하기까지 기다리는 시간입니다. 작업이 보통 걸리는 시간에 여유분을 더해서 설정하세요.

크론 작업이라면 일정 유형으로 Cron을 고르고, crontab에 있는 표현식과 서버의 시간대를 입력하세요. 그러면 Healthchecks는 일정한 간격이 아니라 하루 중 정해진 시각에 핑이 올 것으로 기대합니다. 크론 표현식 편집기에서 표현식의 의미를 자세히 확인할 수 있습니다.

테스트에서는 일정 */2 * * * *에 유예 시간 1분으로 설정한 체크가 16:09:13에 핑을 받았습니다. 16:10에는 아무 핑도 오지 않았고, 체크는 정확히 유예 시간 한 번이 지난 16:11:00에 다운되었습니다.

핑 URL에는 여러 변형이 있습니다.

요청의미
https://hc-ping.com/<uuid>성공. 작업이 끝났습니다.
https://hc-ping.com/<uuid>/start작업 시작. Healthchecks는 유예 시간 안에 성공 보고가 오기를 기다리고 실행 시간을 기록합니다.
https://hc-ping.com/<uuid>/fail작업 실패. 체크가 즉시 다운됩니다.
https://hc-ping.com/<uuid>/<0-255>종료 상태. 0은 성공, 그 외 값은 실패로 처리합니다.

셀프 호스팅 인스턴스에서는 기본 주소가 자신의 도메인과 /ping/입니다. 예를 들어 https://hc.example.com/ping/<uuid>처럼 씁니다.

크론 작업에 연결하기

체크를 만들고 핑 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 변수이며, 명령 안에서 셸이 확장합니다. 이 줄은 세 가지 일을 합니다.

  • /start를 보냅니다. 그래서 멈춘 작업은 유예 시간이 지나면 다운 처리됩니다. 테스트에서는 뒤따르는 요청 없이 /start만 보냈을 때 체크가 정확히 유예 시간 한 번 뒤에 다운되었습니다.
  • 작업을 실행합니다.
  • 작업의 종료 상태인 $?를 보냅니다. 정상 종료면 /0을, 실패하면 /2 또는 스크립트가 반환한 값을 보내고, 체크는 바로 다운됩니다.

curl 옵션은 핑 자체가 문제를 일으키지 않도록 막아 줍니다.

  • **-m 10**은 각 요청을 10초로 제한합니다. 멈춘 /start 때문에 작업이 지연되면 안 되기 때문입니다.
  • **--retry 5**는 시간 초과와 408, 429, 500, 502, 503, 504 응답을 점점 길어지는 간격으로 재시도합니다. 패킷 하나가 유실됐다고 호출이 울리면 곤란하니까요.
  • **-fsS**는 HTTP 오류가 나면 curl이 실패하게 하고, 문제가 없으면 조용히 있게 합니다. 그래서 cron이 curl의 진행 표시줄을 메일로 보내지 않습니다.
  • **-o /dev/null**은 응답 본문을 버립니다. 본문은 OK뿐입니다.

작업이 pg_dump | gzip > dump.gz 같은 파이프라인이라면, 종료 상태는 gzip가 아니라 pg_dump의 상태입니다. bash에서 set -o pipefail을 설정한 스크립트로 옮겨서, 덤프가 실패했는데도 성공으로 보고되지 않도록 하세요.

runitor에 맡기기

runitor는 명령을 감싸서 핑을 대신 처리해 주는 작은 Go 바이너리입니다. 실행 전에는 /start를, 실행 후에는 종료 상태를 보내고, 명령 출력의 마지막 10,000바이트를 핑에 첨부합니다.

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와 함께 다운되었고, 오류 출력이 알림에 그대로 담겨 왔습니다.

Pocket Alert로 알림 보내기

Healthchecks는 범용 Webhook 연동을 통해 Pocket Alert에 연결됩니다. Integrations로 이동해 Webhook을 찾고 Add Integration을 클릭하세요. 폼에는 "Execute when a check goes down"과 "Execute when a check goes up" 두 섹션이 있고, 각각 고유한 URL, 메서드, 본문, 헤더를 설정합니다. 이렇게 나뉘어 있어서 "다운"은 강하게, "업"은 조용하게 보낼 수 있습니다.

두 섹션 모두 $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로 설정하세요. 요청 헤더는 한 줄에 하나씩 입력합니다.

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로 실패와 누락을 구분할 수 있습니다. 알림 직전 마지막 핑의 종료 상태입니다. 2는 작업이 실행되어 2를 반환했다는 뜻입니다. 0과 함께 다운되었다면 마지막 실행은 성공했는데 다음 실행이 오지 않았다는 뜻입니다. -1은 마지막 핑에 종료 상태가 없었다는 뜻입니다. 단순 성공 URL, /fail, /start 중 하나입니다.
  • 버튼은 Healthchecks에서 해당 체크를 엽니다. 셀프 호스팅 인스턴스라면 URL에 자신의 도메인을 넣으세요. 액션 버튼은 유료 기능입니다. 무료 플랜에서는 버튼이 제거되고 메시지 자체는 평소처럼 전달됩니다.

방법 2: 템플릿을 쓰는 Pocket Alert 웹훅

두 번째 방법은 작은 JSON 문서를 Pocket Alert 웹훅으로 보내면 Pocket Alert가 푸시를 구성하는 방식입니다. 장점은 작업의 출력을 포함할 수 있다는 것입니다.

Pocket Alert 콘솔의 웹훅을 열고 Healthchecks라는 이름으로 하나 만든 뒤, 메시지 템플릿을 설정하세요.

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

페이로드가 자체 레벨을 가지므로 Default priority는 선택하지 마세요. 웹훅 URL을 복사하면 https://p4a.me/wh/abc123xyz처럼 생겼습니다. 이 URL 자체가 비밀이므로 비밀번호처럼 다루세요.

Healthchecks에서는 이 URL을 사용해 웹훅 연동을 만듭니다. 두 섹션 모두 POST로 설정하고, 헤더는 Content-Type: application/json을 넣고, 본문은 다음과 같이 입력합니다. 다운일 때:

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

업일 때:

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

$BODY_JSON은 마지막 핑의 본문이며, 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은 빈 문자열이 되고 둘째 줄은 비어 있습니다. API로는 이 방식을 쓸 수 없습니다. $BODY_JSON은 완전한 JSON 문자열이라 message 전체가 되어야 하는데, 핑에 본문이 없으면 메시지가 비게 되어 API가 요청을 거부합니다.

그 밖의 차이점도 있습니다. 푸시 제목은 항상 Webhook <name> 형식이므로 체크 이름은 메시지에 넣어야 합니다. 또 웹훅 버튼은 콘솔 폼이 아니라 웹훅 API의 actions 필드로 설정합니다.

테스트하기

Healthchecks Integrations 페이지에서는 연동마다 Test! 버튼이 있습니다. TEST라는 이름의 체크에 대한 "다운" 알림을 보내며, 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**이 중요합니다. 일일 메시지 한도를 넘으면 API는 429와 함께 자정 UTC까지 남은 초를 담은 Retry-After를 응답하는데, curl의 --retry는 이 값을 따릅니다. 테스트에서 이 옵션이 없을 때 curl은 Retry-After: 30000을 기다리며 멈춰 있었고, 우리가 직접 종료해야 했습니다. 이 옵션이 있으면 curl은 한 번 시도한 뒤 포기합니다.
  • 래퍼는 종료 상태를 유지하고 출력을 그대로 보여 줍니다. 그래서 cron 로그와 MAILTO도 예전처럼 동작합니다.

shellcheck도 통과하며, Debian 13의 cron에서 실행했을 때 실패한 백업은 "Cron failed: nightly backup on"과 호스트 이름으로 시작하고, 본문에 pg_dump 오류가 담긴 알림으로 도착했습니다.

이 방식의 한계도 분명히 해 두겠습니다. 래퍼는 cron이 실행할 때만 동작합니다. crontab 줄이 삭제되었거나, 데몬이 중지되었거나, 기기가 꺼져 있다면 아무것도 전송되지 않습니다. 이 글의 시작 부분에서 말한 조용한 실패 그대로입니다. 영원히 멈춰 있는 작업도 알아채지 못합니다. 이런 경우에는 기기 바깥에서 하트비트를 기다리는 무언가가 필요하며, 그것이 바로 Healthchecks의 역할입니다. 다른 방법을 선호한다면 Pocket Alert CLI로 curl 호출을 대체할 수도 있습니다.

솔직한 한계

  • 알림을 받으려면 Healthchecks가 살아 있어야 합니다. 호스팅 서비스에서는 이 일을 그쪽에서 맡습니다. 크론 작업과 같은 기기에 셀프 호스팅하면, 기기가 죽을 때 모니터도 함께 죽습니다. 다른 곳에서 실행하세요.
  • 본문 템플릿은 Healthchecks에서 1,000자로 제한됩니다. 위 예시 본문에는 충분하지만, 길게 직접 쓴 메시지에는 부족합니다.
  • 긴 출력은 푸시에서 잘립니다. 푸시에는 메시지의 앞부분 약 3KB만 담깁니다. 전체 텍스트는 앱의 메시지 기록에 있습니다.
  • 알림 하나는 메시지 하나입니다. 몇 분 간격으로 다운과 업을 반복하는 작업은 그때마다 푸시를 보냅니다. 무료 플랜의 하루 50개 메시지 한도는 금방 찹니다. 작업을 고치거나 유예 시간을 늘리세요.

알림이 도착하지 않는다면

  • 먼저 Test! 버튼을 누르세요. 테스트 알림은 오는데 실제 알림이 오지 않는다면, 해당 체크 페이지에서 연동이 그 체크에 활성화되어 있는지 확인하세요.
  • Healthchecks의 Integrations 페이지를 보세요. 실패한 연동에는 Failed 표시가 붙습니다. 마우스를 올리면 Received status code 401 같은 마지막 오류를 볼 수 있습니다. 401은 Token 헤더가 잘못되었다는 뜻입니다. 400은 보통 본문이 올바른 JSON이 아니라는 뜻이니, $NAME_JSON을 따옴표 없이 썼는지, "$NAME"으로 쓰지 않았는지 확인하세요.
  • 새 체크는 첫 핑을 받기 전까지 알림을 보내지 않습니다. 그 전까지는 "다운"이 아니라 "새 체크" 상태입니다.
  • 크론 체크의 시간대를 확인하세요. 체크가 항상 한 시간 빠르거나 늦다면, 서버의 시간대와 체크에 설정한 시간대가 맞지 않는 것입니다.
  • 피드를 확인하세요. low 푸시는 소리가 나지 않으므로, 복구 알림이 아예 오지 않은 것처럼 보일 수 있습니다.

자주 묻는 질문

API 방식과 웹훅 방식 중 무엇을 써야 하나요?

API 방식은 체크 이름을 푸시 제목에 넣으며, Pocket Alert에서 따로 만들 것이 없습니다. 웹훅 방식은 작업의 출력을 포함할 수 있으므로, runitor를 쓴다면 웹훅을 선택하세요.

"다운" 알림만 받을 수 있나요?

네. 위에서 설명한 것처럼 "업"에는 조용한 low 본문을 쓰거나, "업" URL을 비워 두세요. 그러면 복구 시 Healthchecks가 아무것도 보내지 않습니다.

systemd 타이머는 어떻게 하나요?

원리는 같습니다. Healthchecks에는 OnCalendar 일정 유형이 있어서 타이머와 같은 표현식을 쓸 수 있습니다. /start에서 ExecStartPre를 보내거나, ExecStart 명령을 runitor로 감싸세요.

크론 알림에 대해 더 읽을 곳이 있나요?

크론 작업 알림 페이지에서는 작업 자체에서 푸시를 보내는 방법을, 백업 알림 페이지에서는 백업 도구를 다룹니다. Proxmox 가이드에서는 하이퍼바이저의 백업을 설명합니다.

무료 계정을 만들고, Healthchecks에 웹훅 연동을 하나 추가해 보세요. 조용히 멈춰 버린 작업이 이제 여러분을 깨우게 될 것입니다.

이 글 공유하기