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 로 내려간다.

11.1 로그 11.3 흔한 장애 시나리오