6.1 상태 조회 명령

pg_auto_failover의 모든 상태는 monitor의 pg_auto_failover 데이터베이스에 있습니다. pg_autoctl show 계열 명령은 이 데이터베이스를 조회해 읽기 쉽게 출력합니다. monitor 노드에서 실행하면 모든 formation을 보여 줍니다. 데이터 노드에서 실행하면 해당 노드가 속한 group만 보여 줍니다. 같은 정보를 SQL로 직접 읽을 수도 있어 모니터링 시스템과 연동하기 쉽습니다.

명령과 데이터의 관계

show file과 show systemd는 로컬 명령이며, 나머지는 monitor를 조회합니다. 따라서 monitor가 멈추면 show state도 실패합니다. 이때는 pg_autoctl show state --local로 keeper가 마지막에 기록한 로컬 상태를 확인할 수 있습니다.

show state

가장 자주 사용하는 명령입니다. 실습의 3노드 구성에서 primary를 kill한 직후 출력은 다음과 같았습니다.

 Name |  Node |  Host:Port |       TLI: LSN |   Connection |      Reported State |      Assigned State
------+-------+------------+----------------+--------------+---------------------+--------------------
node1 |     1 | node1:5432 |   5: 0/9012B10 |   read-write |             primary |             primary
node2 |     2 | node2:5432 |   4: 0/90045C0 | read-write ! |             primary |             demoted
node3 |     3 | node3:5432 |   5: 0/9012B10 |    read-only |           secondary |           secondary

각 열의 의미는 다음과 같습니다.

열	의미
TLI: LSN	노드가 마지막으로 보고한 timeline과 WAL 위치
Connection	노드가 제공하는 연결 종류. monitor가 접속에 실패하면 `!`, 아직 접속을 시도하지 않았으면 `?`
Reported State	keeper가 보고한 현재 상태
Assigned State	monitor가 정한 목표 상태

위 출력의 node2는 이미 종료된 이전 primary입니다. 마지막 보고는 primary로 남아 있습니다. monitor는 demoted를 목표로 정했지만 keeper가 응답하지 않아 두 값이 다릅니다. Connection 열의 !는 health check가 실패하고 있음을 나타냅니다. 두 상태가 다른 노드가 오래 남아 있다면 해당 노드의 keeper가 전이를 수행하지 못하고 있다는 뜻입니다.

--json을 붙이면 모니터링 스크립트가 읽기 쉬운 형식으로 출력됩니다.

{
    "health": 1,
    "node_id": 1,
    "group_id": 0,
    "nodehost": "node1",
    "nodename": "node1",
    "nodeport": 5432,
    "reported_lsn": "0/9055360",
    "reported_tli": 9,
    "candidate_priority": 50,
    "replication_quorum": true,
    "current_group_state": "primary",
    "assigned_group_state": "primary"
}

show events

pgautofailover.event 테이블의 최근 기록을 보여 줍니다. 기본값은 10건이며 --count로 늘릴 수 있습니다. monitor는 상태가 전이될 때마다 사유를 기록합니다. 따라서 장애가 발생한 경위를 재구성할 때 가장 먼저 확인합니다.

pg_autoctl show events --count 20

                    Event Time |   Node |       Current State |      Assigned State | Comment
-------------------------------+--------+---------------------+---------------------+-----------
 2026-09-28 05:11:37.749521+00 |    0/2 |           secondary |           secondary | Node node 2 "node2" (node2:5432) is marked as unhealthy by the monitor
 2026-09-28 05:11:50.616124+00 |    0/1 |             primary |        wait_primary | Setting goal state of node 1 "node1" (node1:5432) to wait_primary because none of the standby nodes in the quorum are healthy at the moment.

Node 열의 0/2는 group 0의 node id 2를 뜻합니다.

show settings, uri, standby-names

pg_autoctl show settings        # get formation settings 와 같다
pg_autoctl show uri
pg_autoctl show standby-names

show settings는 formation의 number_sync_standbys와 현재 primary의 synchronous_standby_names를 보여 줍니다. 노드별 candidate priority와 replication quorum도 한 번에 확인됩니다. show uri는 monitor URI와 애플리케이션용 multi-host URI를 출력합니다. 실습에서 확인한 값은 postgres://node1:5432,node2:5432/appdb?target_session_attrs=read-write&sslmode=require였습니다.

show file과 show systemd

   File | Path
--------+----------------
 Config | /var/lib/pgaf/config/pg_autoctl/var/lib/pgaf/data/pg_autoctl.cfg
  State | /var/lib/pgaf/share/pg_autoctl/var/lib/pgaf/data/pg_autoctl.state
   Init | /var/lib/pgaf/share/pg_autoctl/var/lib/pgaf/data/pg_autoctl.init
    Pid | /tmp/pg_autoctl/var/lib/pgaf/data/pg_autoctl.pid

경로는 XDG_CONFIG_HOME, XDG_DATA_HOME 아래에 PGDATA 경로를 그대로 이어 붙인 형태입니다. pid 파일은 /tmp 아래에 있으므로 컨테이너에서는 주의해야 합니다(9.4).

watch

pg_autoctl watch는 state와 events를 한 화면에서 계속 갱신하는 대시보드입니다. 터미널 전체를 사용하는 대화형 화면이므로 이 노트의 실습 스크립트에서는 사용하지 않았습니다. 짧게 확인할 때는 watch pg_autoctl show state로도 충분합니다.

SQL로 직접 조회

monitor에 psql로 접속하면 같은 정보를 SQL로도 확인합니다. 실습 monitor에는 테이블이 세 개 있었습니다.

\dt pgautofailover.*
--  pgautofailover | event     | table
--  pgautofailover | formation | table
--  pgautofailover | node      | table

select nodeid, nodename, goalstate, reportedstate, health,
       candidatepriority, replicationquorum, reportedlsn
  from pgautofailover.node order by nodeid;

select eventtime, nodename, reportedstate, goalstate, description
  from pgautofailover.event
 where eventtime > now() - interval '10 min'
 order by eventid;

이 노트의 실습 스크립트 wait-state.sh도 reportedstate와 goalstate를 SQL로 읽습니다. 두 값이 모두 목표 값에 도달할 때까지 기다립니다.

경고

reportedstate만 확인해 판단하면 잘못된 결론에 이르기 쉽습니다. 실습 초기에는 reportedstate = 'secondary'만 확인하는 스크립트를 사용했습니다. 그 결과 실제로는 기동에 실패해 멈춘 노드가 0.1초 만에 복귀했다고 잘못 판정했습니다. 종료된 노드의 마지막 보고 값이 그대로 남아 있었기 때문입니다. 두 상태가 같은지와 health가 1인지도 함께 확인해야 합니다.

정리

show state로 현재 상태와 목표 상태의 차이를 확인합니다. show events로는 그 차이가 발생한 이유를 확인합니다. 두 명령 모두 monitor 테이블만 읽습니다. 따라서 SQL로 직접 모니터링을 구성해도 됩니다. 지표 설계는 9.2에서 다룹니다.

명령과 데이터의 관계​

show state​

show events​

show settings, uri, standby-names​

show file과 show systemd​

watch​

SQL로 직접 조회​

정리​