pg_stat_ch에서 가져옵니다.
이 도구는 SQL 문별 카운터를 ClickHouse Cloud로 스트리밍하는
오픈 소스 Postgres 확장 기능입니다. 텔레메트리는 데이터베이스를 떠나기 전에
Postgres 내부에서 정규화되며, 리터럴은 제거되고 플레이스홀더로 대체되므로
쿼리한 정확한 값은 텔레메트리 스트림에 들어가지 않습니다.
Cloud Console에서 ClickHouse Managed Postgres 인스턴스를 열고 왼쪽 사이드바에서
쿼리 인사이트를 클릭합니다. 페이지는 실제 사용 순서에 맞춰 다섯 개의
영역으로 나뉩니다:
- 한 화면에서 데이터베이스 상태를 점검할 수 있는 개요.
- 데이터베이스에서 실행된 모든 쿼리 패턴의 순위를 보여 주며, 의심되는 기준으로 정렬할 수 있는 느린 패턴 테이블.
- 개별 실행 내역을 최신순으로 나열하는 최근 쿼리 패널.
- 활성 세션이 각 대기 이벤트에서 소비한 시간을 기준으로 순위를 보여 주는 대기(Waits) 테이블.
- 단일 패턴에 대한 모든 카운터를 집계해 보여 주는 상세 정보 패널.
개요
개요는 9개 패널로 구성된 3×3 그리드입니다. 처음 두 행은 쿼리 활동을 보여줍니다:
이 화면 하나만으로도 데이터베이스가 정상 상태인지 판단할 수 있습니다. 정상적인 인스턴스는
익숙한 패턴을 보입니다 — buffer hit ratio는 90%대 후반이고, 쿼리량은
애플리케이션 트래픽과 함께 움직이며, 오류율은 일정하거나 0에 가깝고, 백분위수
지연 시간은 서로 비슷한 수준으로 따라갑니다.

대기 차트
세 번째 행에는 30초마다 수집한 샘플을 기반으로 프라이머리의 활성 세션이 무엇을 기다리고 있었는지가 표시됩니다.
Lock wait time이 증가하는 동안 Blocked sessions가 계속 0보다 큰지
확인하십시오. 이는 잠금 경합(lock contention)이 지속되고 있음을 의미할 수 있습니다. 대기 차트를
클릭하면 대기 테이블이 열립니다.

느린 쿼리 패턴
개요에서 문제가 감지되면, 조사는 패턴 테이블에서 시작됩니다. 각 정규화된 쿼리 패턴이 한 행씩 표시되며, 리터럴은 제거되므로 동일한 구문을 실행한 항목은 같은 행으로 묶입니다.
- Total runtime — 데이터베이스가 가장 많은 실제 경과 시간을 소비한 지점입니다.
- CPU time — 컴퓨트 사용량이 많은 패턴입니다.
- Calls — 호출 빈도가 높은 패턴입니다.
- Errors — 반복적으로 실패하는 패턴입니다.
- Avg / P50 / P95 / P99 / Max latency — 백분위수 기준으로 이상치를 보여줍니다.
- Rows returned, Blocks read, Blocks hit, WAL bytes — 엔진, 캐시 또는 write-ahead log를 통해 가장 많은 데이터를 이동시킨 패턴입니다.
- 데이터베이스
- 사용자
- 작업 (
SELECT,INSERT,UPDATE,DELETE, …) - 애플리케이션 — connection string에 있는
application_name
sales DB에서 수행하는 작업만 보여줘”
라는 요청은 드롭다운 2개로 처리할 수 있습니다. 필터 값은
인스턴스에서 실제로 실행된 내용을 기준으로 자동으로 채워집니다.
최근 쿼리
패턴 테이블 아래의 최근 쿼리 패널에는 개별 실행이 최신순으로 나열됩니다. 즉, 패턴당 1행이 아니라 실행된 SQL 문(statement) 1개당 1행이 표시됩니다. 집계 대신 원시 이벤트 스트림이 필요할 때 사용하십시오. 예를 들어 수정 사항이 적용되었는지 확인하거나 오류가 정확히 발생한 시점을 찾을 때 유용합니다.
대기
대기를 펼치거나 대기 차트를 클릭하면 선택한 시간 범위 동안의 평균 활성 세션 수를 기준으로 정렬된 대기 이벤트를 확인할 수 있습니다.
개별 이벤트에 대한 설명은
Postgres 대기 이벤트 참고 문서를 참조하십시오.
세부 정보 플라이아웃
패턴 또는 최근 쿼리 테이블에서 아무 행이나 클릭하면 오른쪽에 쿼리 세부 정보 플라이아웃이 열립니다. 이 플라이아웃은 선택한 시간 범위에서 해당 패턴의 모든 실행을 모아, 느린 이유를 보여 주는 카운터를 집계합니다. 플라이아웃은 스크롤 가능한 단일 레이아웃으로, 5개의 섹션으로 구성됩니다.- 쿼리 패턴 — 리터럴을
$1,$2, …로 대체한 정규화된 SQL과 클립보드에 복사하는 버튼입니다. - 집계 리소스 사용량 — 총 호출 수, 평균/P95/P99/최대 지연 시간, 총 런타임, 반환된 행 수, 캐시 적중률, 읽은 block 수, 적중한 block 수, CPU 시간, WAL 바이트, 오류를 포함한 13개의 통계 카드 그리드입니다.
- 쿼리 컨텍스트 — 이 패턴이 발생한 데이터베이스, 사용자, 작업, 애플리케이션입니다.
- 주목할 만한 실행 — 오류가 발생한 실행, 유난히 느린 실행, 대량의 결과를 반환한 실행을 전체 최근 목록보다 먼저 표시합니다.
- 최근 실행 내역 — 동일한 패턴의 개별 실행이며, 실행별 카운터가 포함됩니다.


- 공유 블록 — read와 hit는 항상 표시되며, written과 dirtied는 0이 아닐 때만 표시됩니다.
- 로컬 및 임시 블록 작업 — 0이 아닌 임시 블록 작업은 sort 또는 hash가 디스크로 spill되었음을 의미합니다.
- 읽기 / 쓰기 시간 — CPU 시간과 별도로 표시되는 I/O 시간입니다.
- CPU 시간 — 사용자 시간과 시스템 시간이 각각 별도로 표시됩니다.
- 병렬 worker — 계획된 수와 실제로 시작된 수를 보여줍니다.
- JIT — 전체 JIT 컴파일 시간과 함수 개수입니다.
- WAL — 바이트 수와 레코드 수입니다.
쿼리 인사이트 API
SQL 문별 텔레메트리는 ClickHouse Cloud OpenAPI를 통해서도 이용할 수 있습니다. 느린 패턴 테이블은 list slow query patterns 엔드포인트에 매핑되며, 상세 정보 패널은 get slow query pattern 엔드포인트에 매핑됩니다. 이 엔드포인트는 단일 패턴의 집계 메트릭과 최근 실행 내역을 함께 반환합니다.pg_stat_ch는 parse-analyze 단계를 가로채 각 리터럴을
플레이스홀더($1, $2, …)로 바꾸고, 그 결과 패턴을 queryid를 키로 사용하는
백엔드별 LRU에 캐시합니다. 실행기가 SQL 문을 마치면, 그 캐시된 패턴이
이벤트에 첨부됩니다. 값이 포함된 정확한 SQL 문은 데이터베이스 밖으로
나가지 않습니다.
프로듀서는 statement당 약 3%의 오버헤드를 추가합니다. enqueue 경로는
공유 메모리 링 버퍼에서 비차단 try-lock을 사용합니다. 부하가
높아지면 이 확장 기능은 Postgres에 백프레셔를 가하는 대신 카운터를
증가시키고 이벤트를 삭제합니다.
대기는 샘플링됩니다
대기 차트와 대기 테이블은 프라이머리에서 30초마다 수집한 샘플을 사용합니다. 짧은 대기는 샘플 수집 사이에 시작되고 끝나 표시되지 않을 수 있으므로, 이 화면들은 지속적인 대기와 잠금 경합(lock contention)을 파악하는 데 가장 유용합니다.pg_stat_ch는 샘플링이 적용된 상태에서 실행된 각 SQL 문(최상위 및
중첩)에 대해 원시 이벤트 1개를 내보냅니다. 쿼리 백분위수, 순위, 세부
분석은 이 이벤트 스트림을 바탕으로 ClickHouse에서 계산됩니다.
Insights 백엔드는 ClickHouse Cloud입니다.
트래픽이 많은 Postgres 인스턴스에서 발생하는 쿼리별 telemetry 데이터는 하루에
수백만 행에 이르지만, 열 지향 Compression 덕분에 실행 단위의 세부 데이터를
몇 개월 동안도 저렴하게 보관할 수 있으며, 수십억 행에 대한 1초 미만의 집계로
1주일 또는 1개월 범위로 분석하더라도 UI를 즉각적으로 사용할 수 있습니다.
pg_stat_ch는 Apache 2.0 라이선스로 제공됩니다. 어떤 Postgres에서든 실행할 수 있고, 어떤
ClickHouse로든 전송할 수 있습니다. 소스 코드와 이슈는 다음에서 확인할 수 있습니다.
github.com/clickhouse/pg_stat_ch.
관련 페이지
- 모니터링 대시보드 — 기본 제공 리소스 및 활동 차트
- Prometheus 엔드포인트 — 호스트 수준 메트릭을 자체 관측성 스택으로 스크레이프
- ClickHouse Managed Postgres OpenAPI — 느린 패턴과 최근 실행 내역을 프로그래밍 방식으로 조회
- 확장 기능 — ClickHouse Managed Postgres 인스턴스에서 사용할 수 있는 확장 기능
pg_stat_chon GitHub — Query Insights를 지원하는 오픈소스 확장 기능