Healthchecks 메트릭을 Prometheus에 통합하여 크론 작업 모니터링하기

Python 및 Django 기반의 오픈소스 도구인 Healthchecks는 주기적인 크론(Cron) 작업이나 백그라운드 태스크의 상태를 추적하는 데 매우 유용합니다. 여기에 Prometheus를 연동하면 작업 상태를 시각화하고 정교한 알람 체계를 구축하여 운영 안정성을 높일 수 있습니다.

Prometheus 통합 활성화

Healthchecks 내부에서 메트릭 노출 기능을 활성화해야 합니다. 프로젝트 설정 파일인 hc/settings.py 내의 설정을 확인합니다. 기본적으로는 활성화되어 있으나, 환경 변수를 통해 제어할 수 있습니다.

# 메트릭 노출 여부 설정
ENABLE_METRICS = envbool("PROMETHEUS_ENABLED", "True")

인증을 위한 읽기 전용 API 키 생성

Prometheus 서버가 Healthchecks 데이터에 안전하게 접근하려면 전용 권한이 필요합니다.

Healthchecks 대시보드에 로그인한 후 해당 프로젝트의 SETTINGS 메뉴로 이동합니다.
API Access 섹션에서 API key (read-only) 항목을 찾습니다.
Create 버튼을 클릭하여 고유한 API 키를 생성하고 복사해 둡니다.

Prometheus 스크레이프 설정

Prometheus의 설정 파일(prometheus.yml)에 Healthchecks 엔드포인트를 추가하여 데이터를 주기적으로 수집하도록 구성합니다.

scrape_configs:
  - job_name: 'hc_monitor'
    metrics_path: '/projects/[PROJECT_ID]/metrics/[READ_ONLY_KEY]'
    static_configs:
      - targets: ['hc.your-domain.com']

여기서 [PROJECT_ID]와 [READ_ONLY_KEY]를 실제 값으로 치환해야 하며, 도메인은 본인의 인스턴스 주소를 입력합니다.

주요 제공 메트릭 항목

통합이 완료되면 hc/integrations/prometheus/views.py를 통해 다음과 같은 주요 메트릭이 노출됩니다.

hc_check_up: 특정 작업의 정상 여부 (1: 정상, 0: 장애)
hc_check_started: 작업의 실행 시작 여부
hc_check_grace: 유예 기간 적용 여부
hc_check_paused: 일시 중지된 작업 상태
hc_checks_total: 전체 모니터링 대상 수
hc_checks_down_total: 현재 장애 상태인 작업의 총합

경고(Alert) 규칙 정의

수집된 메트릭을 기반으로 작업 장애 시 즉각적인 알림을 보낼 수 있는 규칙을 작성합니다.

groups:
- name: hc_alert_rules
  rules:
  - alert: CronJobFailure
    expr: hc_checks_down_total > 0
    for: 3m
    labels:
      severity: critical
    annotations:
      summary: "Healthchecks 장애 감지"
      description: "현재 {{ $value }}개의 태스크가 정상적으로 완료되지 않았습니다."

커스텀 메트릭 확장하기

기본 제공 메트릭 외에 특정 비즈니스 로직에 맞는 데이터가 필요하다면 views.py 내의 metrics 함수를 수정하여 확장할 수 있습니다. 아래는 마지막 핑(Ping) 이후 경과 시간을 분 단위로 계산하여 노출하는 예시입니다.

def generate_custom_metrics(checks):
    yield "# HELP hc_job_last_seen_minutes 분 단위의 마지막 작업 감지 시간\n"
    yield "# TYPE hc_job_last_seen_minutes gauge\n"
    
    current_time = time.time()
    for item in checks:
        if item.last_ping:
            # 초 단위 차이를 분 단위로 변환
            diff_min = int((current_time - item.last_ping.timestamp()) / 60)
            labels = f'{{job_name="{item.name}", job_id="{item.unique_key}"}}'
            yield f"hc_job_last_seen_minutes{labels} {diff_min}\n"

이와 같이 코드를 수정하면 대시보드에서 각 작업이 마지막으로 실행된 시점을 더욱 상세하게 추적할 수 있습니다. 수집된 모든 데이터는 Grafana와 같은 시각화 도구와 결합하여 통합 모니터링 환경을 구축하는 데 활용됩니다.

태그: Healthchecks prometheus Cron-Monitoring Django DevOps

7월 11일 19:19에 게시됨

괴물 클럽