11.2 메트릭과 경보
무엇으로 모니터링하느냐는 질문에 공식 FAQ가 내놓는 답은 REST API의 두 엔드포인트입니다. GET /metrics는 Prometheus 텍스트 포맷으로 지표를 노출하고, GET /patroni는 같은 노드의 상태를 JSON으로 반환합니다. 엔드포인트 자체는 8.2 조회 엔드포인트에서 다뤘으므로, 이 챕터는 그중 무엇을 보고 어디에 경보를 걸지에 집중합니다.
GET /metrics 주요 항목
메트릭은 노드 단위입니다. 각 노드의 REST API가 자기 관점의 값을 반환하므로, 클러스터 전체 그림은 모든 노드를 수집해 합쳐야 나옵니다.
먼저 role을 나타내는 gauge 군입니다. 해당 role이면 1, 아니면 0입니다.
| 메트릭 | 1인 조건 |
|---|---|
patroni_primary | 이 노드가 leader |
patroni_standby_leader | standby cluster의 leader |
patroni_replica | replica |
patroni_sync_standby | synchronous standby |
patroni_quorum_standby | quorum standby |
WAL 위치는 세 개의 counter로 노출됩니다.
| 메트릭 | 의미 |
|---|---|
patroni_xlog_location | 현재 WAL 위치. leader가 아니면 0 |
patroni_xlog_received_location | 수신한 WAL 위치. replica가 아니면 0 |
patroni_xlog_replayed_location | replay를 마친 WAL 위치. replica가 아니면 0 |
PostgreSQL 프로세스 쪽 상태는 다음 항목으로 봅니다.
| 메트릭 | 의미 |
|---|---|
patroni_postgres_running | 1이면 PostgreSQL 실행 중 |
patroni_postgres_state | 상태의 숫자 코드(0~14). 코드와 상태 이름의 매핑 표가 공식 문서에 있다 |
patroni_postgres_streaming | 1이면 streaming 복제로 동작 중 |
patroni_postgres_in_archive_recovery | 1이면 archive 기반 복구로 동작 중 |
patroni_postgres_timeline | 현재 timeline 번호 |
patroni_postgres_server_version | PostgreSQL 서버 버전 |
마지막으로 Patroni와 클러스터 운영 상태입니다. 경보 후보 대부분이 여기서 나옵니다.
| 메트릭 | 의미 |
|---|---|
patroni_cluster_unlocked | 1이면 leader lock을 아무도 갖지 않은 상태 |
patroni_failsafe_mode_is_active | 1이면 failsafe mode가 동작 중 |
patroni_dcs_last_seen | DCS와 마지막으로 통신에 성공한 시각(epoch) |
patroni_pending_restart | 1이면 재시작해야 적용되는 설정이 대기 중 |
patroni_is_paused | 1이면 자동 failover가 꺼진 상태(pause) |
GET /patroni 병용
/metrics가 숫자만 내보내는 것과 달리 GET /patroni는 노드의 state, role, PostgreSQL 버전, xlog 위치, timeline, replication 정보, tags, 그리고 cluster_unlocked, failsafe_mode_is_active, pause 같은 클러스터 상태 필드까지 JSON 하나로 반환합니다. 메트릭 대시보드에 나오지 않는 tags나 replication 상세를 확인할 때, 그리고 경보가 울린 노드를 직접 조사할 때는 이쪽을 씁니다.
curl -s http://127.0.0.1:8008/patroni | jq .
Prometheus 수집 예시
/metrics는 GET 계열의 safe 엔드포인트라 restapi.authentication의 Basic-auth 대상이 아닙니다. 노드별로 REST API 포트를 target에 나열하면 됩니다.
scrape_configs:
- job_name: patroni
metrics_path: /metrics
static_configs:
- targets:
- 10.0.0.1:8008
- 10.0.0.2:8008
- 10.0.0.3:8008
restapi.certfile로 TLS를 켠 클러스터라면 scrape 설정에 scheme: https와 CA 설정이 추가로 필요합니다. 공식 문서 기준으로 safe 엔드포인트를 보호하는 방법은 TLS와 verify_client 조합뿐이므로, 클라이언트 인증서를 요구하도록 구성했다면 Prometheus 쪽에도 인증서를 배포해야 합니다.
어디에 경보를 걸 것인가
공식 문서는 메트릭 목록을 제공할 뿐 경보 기준을 제시하지 않습니다. 아래는 각 지표의 의미에서 따라 나오는 후보이고, 임계값과 지속 시간은 환경에 맞춰 DBA가 정할 몫입니다.
가장 먼저 걸 만한 것은 primary 개수입니다. 모든 노드의 patroni_primary 합이 1이어야 정상입니다. 합이 0으로 지속되면 leader 부재이고 patroni_cluster_unlocked와 함께 확인합니다. 2 이상이면 이중 primary가 의심되는 상황으로, 11.3 시나리오 E의 확인 절차로 넘어갑니다. 같은 맥락에서 patroni_postgres_running이 0인 노드는 Patroni는 살아 있는데 PostgreSQL이 내려간 상태이므로 노드 단위 경보 1순위입니다.
복제 lag을 직접 담은 메트릭은 /metrics에 없습니다. leader의 patroni_xlog_location과 각 replica의 patroni_xlog_replayed_location 차이로 계산하거나, 로드밸런서 레벨에서 GET /replica?lag=<max-lag> health check를 병용하는 방법이 있습니다.
느리게 쌓이는 문제들도 경보 대상이 됩니다. patroni_pending_restart가 오랫동안 1이면 바꾼 설정이 적용되지 않은 채 방치된 것이고, patroni_is_paused가 장기간 1이면 유지보수 후 patronictl resume을 잊었을 가능성이 큽니다. pause 중에는 자동 failover가 없으므로 이 상태의 장기화 자체가 위험입니다.
변화를 감지하는 축도 있습니다. patroni_postgres_timeline의 증가는 failover 또는 switchover가 있었다는 뜻이므로, 계획에 없는 증가나 짧은 간격의 연속 증가(flapping)에 알림을 겁니다. patroni_dcs_last_seen은 현재 시각과의 차이가 벌어지기 시작하면 DCS 통신 문제이므로, patroni_failsafe_mode_is_active와 함께 DCS 장애 시나리오의 조기 신호로 쓸 수 있습니다.
정리
/metrics는 노드 단위 지표이므로 전 노드를 수집해 클러스터 관점으로 합산하는 것이 시작점입니다. primary 합계, postgres_running, lag, pending_restart, timeline, dcs_last_seen, is_paused가 경보 후보가 되며, 기준선은 공식 권고가 아니라 각 지표의 의미에서 DBA가 도출합니다. 숫자 뒤의 상세가 필요하면 GET /patroni로 내려갑니다.