8.2 조회 엔드포인트

health check가 상태 코드 중심이라면, 조회 엔드포인트는 JSON 내용 자체가 목적이다. 노드 하나의 상세 상태는 /patroni, 클러스터 전체 토폴로지는 /cluster, timeline 분기 이력은 /history, 현재 dynamic configuration은 /config로 확인한다. 넷 다 GET 요청이며, 기본 구성에서는 인증 없이 응답하는 safe 엔드포인트다. 보호 방법은 8.4 REST API 보안에서 다룬다.

GET /patroni

노드 자신의 상태를 반환한다. 모니터링 수집용으로 쓰이지만 원래 역할은 그보다 무겁다. leader lock이 비었을 때 각 노드는 다른 멤버들의 /patroni를 호출해 WAL 위치를 비교하고 자신이 승격 자격이 있는지 판단한다. 즉 leader race의 실체가 이 엔드포인트 호출이다.

    flowchart TD
  EXP["leader key 만료"] --> POLL["각 replica가 멤버들의<br/>/patroni 호출"]
  POLL --> CMP["WAL 위치 비교"]
  CMP --> RACE["자격 있는 노드가<br/>leader key 생성 시도"]
  RACE --> WIN["성공한 노드가 promote"]
  

leader race의 전체 절차와 후보 자격 조건은 Part VI에서 다룬다.

curl -s http://127.0.0.1:8008/patroni | jq .

{
  "state": "running",
  "postmaster_start_time": "2026-07-30 09:12:33.041954+09:00",
  "role": "primary",
  "server_version": 170005,
  "xlog": {"location": 67110992},
  "timeline": 5,
  "replication": [
    {"application_name": "patroni2", "state": "streaming", "sync_state": "async"}
  ],
  "dcs_last_seen": 1753861230,
  "tags": {},
  "database_system_identifier": "7431218477243559023",
  "patroni": {"version": "4.1.4", "scope": "demo"}
}

값은 예시이며 일부 하위 필드는 생략했다. 주요 필드를 해석하면 다음과 같다.

클러스터 상황에 따라 cluster_unlocked(leader lock 부재), failsafe_mode_is_active, pause 같은 상태 지표가 함께 실린다. 셋 중 하나라도 보인다면 클러스터가 평상시 상태가 아니라는 신호다.

GET /cluster

클러스터 토폴로지와 상태 전체를 JSON으로 생성한다.

curl -s http://127.0.0.1:8008/cluster | jq .

{
  "members": [
    {
      "name": "patroni1",
      "role": "leader",
      "state": "running",
      "api_url": "http://10.89.0.4:8008/patroni",
      "host": "10.89.0.4",
      "port": 5432,
      "timeline": 5
    },
    {
      "name": "patroni2",
      "role": "replica",
      "state": "streaming",
      "api_url": "http://10.89.0.6:8008/patroni",
      "host": "10.89.0.6",
      "port": 5433,
      "timeline": 5,
      "receive_lsn": "0/4000060",
      "receive_lag": 0,
      "replay_lsn": "0/4000060",
      "replay_lag": 0,
      "lag": 0,
      "lsn": "0/4000060"
    }
  ],
  "scope": "demo",
  "scheduled_switchover": {
    "at": "2026-08-05T02:00:00+09:00",
    "from": "patroni1",
    "to": "patroni2"
  }
}

members 배열의 각 항목은 멤버 이름, role, state, REST API 주소(api_url), 접속 host와 port, timeline, tag를 담는다. replica 항목에는 lag 정보가 추가되는데, receive_lsn/receive_lag는 수신되어 디스크에 기록된 WAL 기준, replay_lsn/replay_lag는 실제로 replay된 WAL 기준이다. 수신은 따라갔는데 replay가 밀리는 노드라면 두 값이 벌어진다. scheduled_switchover 객체는 예약된 switchover가 있을 때만 나타나며 실행 시각(at)과 전환 대상(from, to)을 보여준다.

GET /history

failover나 switchover로 timeline이 분기한 이력을 반환한다. PostgreSQL의 timeline history 파일과 유사한 형식에 timeline 생성 시각이 더해진 구조다.

curl -s http://127.0.0.1:8008/history | jq .

[
  [1, 25623960, "no recovery target specified", "2019-09-23T16:57:57+02:00"],
  [2, 25624344, "no recovery target specified", "2019-09-24T09:22:33+02:00"]
]

각 원소는 4원소 배열로, 순서대로 timeline 번호, 그 timeline이 끝난 LSN, 사유 문자열, 새 timeline이 생성된 ISO 8601 시각이다. 위 예시라면 timeline 1이 LSN 25623960에서 끝나고 다음 날 timeline 2로 넘어갔다는 기록이다. 짧은 간격으로 timeline이 연달아 생성되어 있다면 failover가 반복됐다는 뜻이므로 원인 추적이 필요하다.

GET /config

DCS에 저장된 현재 dynamic configuration을 반환한다. patronictl show-config가 보여주는 것과 같은 내용을 HTTP로 얻는 통로다.

curl -s http://127.0.0.1:8008/config | jq .

{
  "ttl": 30,
  "loop_wait": 10,
  "retry_timeout": 10,
  "maximum_lag_on_failover": 1048576,
  "postgresql": {
    "use_pg_rewind": true,
    "parameters": {
      "max_connections": "100"
    }
  }
}

ttl, loop_wait, retry_timeout 같은 HA 루프 파라미터와 postgresql.parameters 아래의 PostgreSQL 설정이 그대로 보인다. 변경은 같은 경로에 PATCH나 PUT을 보내며, 계약은 8.3 쓰기 연산에서 정리한다. dynamic configuration이 구성 3계층에서 차지하는 위치는 Part IV 참고.

정리

노드 하나를 들여다볼 때는 /patroni, 클러스터 전체를 볼 때는 /cluster, 과거 이력은 /history, 현재 설정은 /config를 호출한다. 이 중 /patroni는 단순한 모니터링 편의 기능이 아니라 leader race에 실제로 쓰이는 내부 프로토콜의 일부다.