Airflow

웹서버 헬스체크 엔드포인트 (/api/v2/monitor/health)

Airflow 인스턴스의 헬스 상태를 확인하려면 ``/api/v2/monitor/health`` 엔드포인트에 접근하면 된다. 이 엔드포인트는 metadatabase, scheduler, triggerer, dag_processor에 걸친 높은 수준의 헬스 상태를 JSON으로 반환하며, 스케줄러/트리거러/Dag 프로세서가 여러 개 실행 중일 때는 인스턴스별 상세 정보도 포함한다.

``metadatabase.status``는 DB와 유효한 연결을 맺을 수 있으면 ``"healthy"``, 아니면 ``"unhealthy"``다. scheduler/triggerer/dag_processor 각각은 ``status``(레거시 집계 필드로, 실행 중인 인스턴스가 하나라도 살아있으면 healthy, 실행 중인 잡이 아예 없어도 unhealthy), ``detailed_status``(healthy=모든 실행 중 인스턴스가 살아있음, degraded=일부만 살아있음, down=하나도 살아있지 않거나 잡 자체가 없음), ``latest_*_heartbeat``(실행 중인 잡들 중 가장 최근 하트비트, 없으면 null), ``instances``(실행 중인 잡마다 한 항목: status, hostname, 해당 하트비트, 트리거러의 team_name, Dag 프로세서의 bundle_names)를 갖는다. HA 배포에서 모든 스케줄러/트리거러/Dag 프로세서를 다 보고 싶다면 ``detailed_status``와 ``instances``를 봐야 하고, 레거시 ``status``는 최소 하나라도 살아있는지만 신경 쓰는 단순 프로브에 유용하다.

HTTP 응답 코드(200)는 REST 호출 자체의 성공 여부만 의미할 뿐, 애플리케이션의 헬스 상태를 나타내지 않으므로 응답 코드로 헬스를 판단해서는 안 된다. 이 체크가 동작하려면 최소 하나의 웹서버가 필요하다 — 웹서버가 죽으면 스케줄러 모니터링 능력도 함께 잃게 되므로, 더 확실히 하려면 CLI 체크나 스케줄러 전용 헬스체크 서버를 함께 고려해야 한다. 또한 이 엔드포인트를 웹서버 자체의 liveness/readiness 프로브로 쓰면 웹서버 상태가 DB/스케줄러 등 다른 코어 컴포넌트 가용성에 종속되어 불필요하게 자주 재시작될 수 있으므로, 웹서버 프로브에는 ``api/v2/version`` 같은 엔드포인트를 고려하는 편이 낫다.

스케줄러 전용 헬스체크 서버

웹서버와 독립적으로 스케줄러 헬스를 체크하기 위해, Airflow는 옵션으로 각 스케줄러 안에 작은 HTTP 서버를 띄워 ``/health`` 엔드포인트를 제공할 수 있다. 스케줄러가 healthy면 200, unhealthy면 503을 반환한다. 이를 실행하려면 ``[scheduler] enable_health_check``를 ``True``로 설정해야 하며(기본값 False), 서버는 ``[scheduler] scheduler_health_check_server_port``(기본 8974)에서 동작하고, 내부적으로 ``http.server.BaseHTTPRequestHandler``를 작은 서버로 사용한다.

쿠버네티스에서는 스케줄러 디플로이먼트에 livenessProbe로 CLI 체크를, 웹서버에는 readinessProbe로 HTTP 엔드포인트를 연결하는 방식이 권장된다.

CLI 체크: 스케줄러, DB, Celery

스케줄러는 시작 시 ``airflow.jobs.job.Job`` 테이블에 호스트와 타임스탬프(하트비트) 정보를 담은 엔트리를 만들고 주기적으로 갱신한다. ``airflow jobs check --job-type SchedulerJob --local``로 로컬 스케줄러가 정상 동작하는지, HA 환경이라면 ``--allow-multiple --limit 100``으로 어떤 스케줄러든 하나라도 동작 중인지 확인할 수 있다. 실패 시 0이 아닌 종료 코드를 반환한다.

DB가 정상 동작하는지는 ``airflow db check``로 확인하며 역시 실패 시 0이 아닌 코드를 반환한다.

Celery 클러스터는 Flower로 HTTP 기반 모니터링을 할 수 있고, ``celery inspect ping``으로 CLI에서 워커 상태를 확인할 수 있다(``[celery] worker_enable_remote_control``이 True여야 동작하며, False면 명령이 실패한다).