Heartbeat 모니터링: 스케줄된 작업이 조용히 중단될 때 알기

Source: Dev.to

서버가 다운될 때 알려주는 가동 시간 모니터링은 유용하지만, 가장 심각한 장애는 다음과 같이 보일 수 있습니다:

• 서버는 정상이다
• 크론 스케줄러가 실행되었다
• 눈에 띄는 오류는 없었다

작업이 조용히 멈춰버린 경우입니다—며칠째 실행되지 않은 야간 데이터 동기화, “완료”됐지만 0바이트만 기록된 백업, 몇 주 전부터 예외를 발생시키기 시작한 보고서 작업 등. 이러한 실패는 엔드포인트가 절대 실패하지 않기 때문에 전통적인 HTTP 모니터링으로는 감지되지 않습니다.

하트비트 모니터링은 이 문제를 해결합니다.

작동 원리

하트비트 모니터는 사망 스위치(dead‑man’s switch)와 같습니다. Tickstem이 엔드포인트를 폴링하는 대신, 작업이 성공적으로 끝날 때마다 Tickstem에 호출을 보냅니다. 예상 간격 + 여유 기간 내에 핑이 도착하지 않으면 알림이 전송됩니다.

다음 두 가지를 설정합니다:

알림 규칙: 연속 두 번의 간격 동안 핑이 없으면 → 알림 전송.

적용 방법

Go

import "github.com/tickstem/heartbeat"

client := heartbeat.New(os.Getenv("TICKSTEM_API_KEY"))

hb, err := client.Create(ctx, heartbeat.CreateParams{
    Name:         "nightly-sync",
    IntervalSecs: 86400,
    GraceSecs:    3600,
})

// at the end of every successful run — token is the credential, no API key needed
if err := client.Ping(ctx, hb.Token); err != nil {
    log.Println("heartbeat ping failed:", err) // non-fatal
}

Node.js

import { HeartbeatClient } from "@tickstem/heartbeat"

const hb = new HeartbeatClient(process.env.TICKSTEM_API_KEY)

const heartbeat = await hb.create({ name: "nightly-sync", interval_secs: 86400 })

// at the end of every successful run
await hb.ping(heartbeat.token).catch(err => console.error("ping failed:", err))

Curl (no SDK needed)

curl -s -X POST https://api.tickstem.dev/v1/heartbeats/$HEARTBEAT_TOKEN/ping

토큰은 URL에 포함되며 인증 헤더는 필요하지 않습니다. curl이 실패하더라도 스크립트는 정상 종료되어야 합니다.

주목할 점

핑은 성공 시에만 발생합니다. 따라서 침묵은 무언가가 잘못됐음을 의미합니다—작업이 크래시했거나, 스케줄되지 않았거나, 실제 작업을 수행하지 않고 종료된 경우입니다. 핑을 비치명적으로 처리하세요; 일시적인 네트워크 오류가 성공적인 동기화를 중단하게 해서는 안 됩니다.

사용 시점

“작업이 실행되었다”와 “유용한 작업을 수행했다”가 다른 경우에 적용합니다:

• 데이터베이스 백업
• 데이터 동기화 / ETL 파이프라인
• 보고서 생성
• 청구서 또는 결제 처리
• 캐시 워밍

가동 시간 모니터링과 하트비트 모니터링은 상호 보완적입니다:

• Uptime = 서버가 살아 있음.
• Heartbeat = 작업이 실제로 제 역할을 수행함.