메인 콘텐츠로 건너뛰기
쿼리 인사이트는 Managed Postgres 인스턴스에서 SQL 문별 텔레메트리를 수집하고 영향도가 큰 순서대로 모든 쿼리 패턴의 순위를 매기므로, Cloud Console을 벗어나지 않고도 “p99가 서서히 증가하고 있다”에서 “이 패턴에서 디스크 스필이 발생하고 있다”까지 바로 파악할 수 있습니다. 데이터는 pg_stat_ch에서 가져옵니다. 이 도구는 SQL 문별 Counter를 ClickHouse Cloud로 스트리밍하는 오픈 소스 Postgres 확장 기능입니다. 텔레메트리는 데이터베이스를 떠나기 전에 Postgres 내부에서 정규화되며, 리터럴은 제거되고 플레이스홀더로 대체되므로 쿼리한 정확한 값은 텔레메트리 스트림에 들어가지 않습니다.

​
쿼리 인사이트 열기

Cloud Console에서 Managed Postgres 인스턴스를 열고 왼쪽 사이드바에서 쿼리 인사이트를 클릭합니다. 페이지는 실제 사용 순서에 맞춰 네 개의 영역으로 나뉩니다:
  • 한 화면에서 데이터베이스 상태를 점검할 수 있는 개요.
  • 데이터베이스에서 실행된 모든 쿼리 패턴의 순위를 보여 주며, 의심되는 기준으로 정렬할 수 있는 느린 패턴 테이블.
  • 개별 실행 내역을 최신순으로 나열하는 최근 쿼리 패널.
  • 단일 패턴에 대한 모든 카운터를 집계해 보여 주는 세부 정보 플라이아웃.
상단의 시간 범위 선택기를 사용해 최근 15분, 1시간, 1일, 1주 또는 1개월로 전환합니다. 집계 버킷 크기는 자동으로 조정됩니다. 최근 15분 또는 1시간에는 1분 버킷, 최근 1일에는 5분 버킷, 최근 1주 또는 1개월에는 1시간 버킷을 사용하므로 차트가 빠르게 응답합니다.

​
개요

개요는 6개 패널로 구성된 3×2 그리드입니다:
PanelWhat it shows
Queries / sec선택한 기간 기준으로 초당 비율로 환산한 쿼리량입니다.
Query latency평균, p50, p95, p99를 하나의 차트에 표시하므로, 지연 시간의 꼬리 구간이 중앙값과 벌어지기 시작하는 시점을 확인할 수 있습니다.
Operations breakdown워크로드가 실제로 SELECT, INSERT, UPDATE 및 기타 작업으로 어떻게 구성되는지 보여주는 도넛 차트입니다.
Rows returned / affected선택한 기간 동안 워크로드가 처리한 총 행 수입니다.
Buffer hit ratio공유 블록 적중 수와 공유 블록 읽기 수를 비교한 도넛 차트이며, 범례에는 총 CPU 시간이 표시됩니다.
Errors시간 경과에 따라 구분한 총 오류 수입니다.
이 화면 하나만으로도 데이터베이스가 정상 상태인지 판단할 수 있습니다. 정상적인 인스턴스는 익숙한 패턴을 보입니다 — buffer hit ratio는 90%대 후반이고, 쿼리량은 애플리케이션 트래픽과 함께 움직이며, 오류율은 일정하거나 0에 가깝고, 백분위수 지연 시간은 서로 비슷한 수준으로 따라갑니다.

​
느린 쿼리 패턴

개요에서 문제가 보이면, 조사 작업은 패턴 테이블에서 시작됩니다. 각 정규화된 쿼리 패턴은 한 행으로 표시되며, 리터럴 값이 제거되므로 같은 statement를 실행한 항목은 동일한 행으로 묶입니다.

​
의심되는 항목을 기준으로 정렬하기

이 테이블은 기본적으로 Total runtime 내림차순으로 정렬됩니다. 이렇게 정렬하면 맨 위의 패턴이 대개 “무엇이 가장 큰 비용을 발생시키는가?”에 대한 답이 됩니다. 다만 개별적으로 가장 느린 패턴은 아닐 수 있습니다. 하루에 800만 번 실행되며 12밀리초가 걸리는 쿼리가, 한 번 실행되고 3초가 걸린 쿼리보다 더 중요할 수 있습니다. 각 정렬은 서로 다른 관점을 제공합니다:
  • Total runtime — 데이터베이스가 가장 많은 실제 경과 시간을 소비한 지점입니다.
  • CPU time — 컴퓨트 사용량이 많은 패턴입니다.
  • Calls — 호출 빈도가 높은 패턴입니다.
  • Errors — 반복적으로 실패하는 패턴입니다.
  • Avg / P50 / P95 / P99 / Max latency — 백분위수 기준으로 이상치를 보여줍니다.
  • Rows returned, Blocks read, Blocks hit, WAL bytes — 엔진, 캐시 또는 write-ahead log를 통해 가장 많은 데이터를 이동시킨 패턴입니다.
추가 컬럼을 보거나 숨기려면 Columns 버튼을 클릭하세요. 패턴 테이블은 백분위수 세부 정보, 캐시 적중률, 패턴별 CPU 시간을 포함해 총 19개의 컬럼을 제공합니다.

​
테이블 범위 좁히기

조사 중인 워크로드의 원하는 범위만 보이도록 테이블을 필터링합니다:
  • 데이터베이스
  • 사용자
  • 작업 (SELECT, INSERT, UPDATE, DELETE, …)
  • 애플리케이션 — connection string에 있는 application_name
“orders service가 sales DB에서 수행하는 작업만 보여줘” 라는 요청은 드롭다운 2개로 처리할 수 있습니다. 필터 값은 인스턴스에서 실제로 실행된 내용을 기준으로 자동으로 채워집니다.

​
최근 쿼리

패턴 테이블 아래의 최근 쿼리 패널에는 개별 실행이 최신순으로 나열됩니다. 즉, 패턴당 1행이 아니라 실행된 SQL 문(statement) 1개당 1행이 표시됩니다. 집계 대신 원시 이벤트 스트림이 필요할 때 사용하십시오. 예를 들어 수정 사항이 적용되었는지 확인하거나 오류가 정확히 발생한 시점을 찾을 때 유용합니다. 기본 컬럼은 Time, Operation, Query, Duration, Rows, Database, User, Blks read입니다. Columns 선택기를 열면 Application, Blks hit, CPU user, CPU sys, PID를 볼 수 있습니다. 이 테이블은 패턴 테이블과 동일한 Database, User, Operation, Application 필터를 지원하며, Time, Duration, Rows, Blks read, CPU time 기준으로 정렬할 수 있습니다. 아무 행이나 클릭하면 패턴 테이블과 동일한 상세 플라이아웃이 열리며, 해당 단일 실행의 패턴으로 범위가 한정됩니다.

​
세부 정보 플라이아웃

패턴 또는 최근 쿼리 테이블에서 아무 행이나 클릭하면 오른쪽에 쿼리 세부 정보 플라이아웃이 열립니다. 이 플라이아웃은 선택한 시간 범위에서 해당 패턴의 모든 실행을 모아, 느린 이유를 보여 주는 카운터를 집계합니다. 플라이아웃은 스크롤 가능한 단일 레이아웃으로, 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 — 바이트 수와 레코드 수입니다.
느린 pattern을 진단하는 데 필요한 모든 정보를 한곳, 한 화면에서 확인할 수 있습니다.

​
쿼리 인사이트 API

동일한 텔레메트리는 ClickHouse Cloud OpenAPI를 통해 프로그래밍 방식으로도 이용할 수 있습니다. Slow patterns 테이블은 list slow query patterns 엔드포인트에 매핑되며, 세부 정보 패널은 get slow query pattern 엔드포인트에 매핑됩니다. 이 엔드포인트는 단일 패턴의 집계 메트릭과 최근 실행 내역을 함께 반환합니다.

​
동작 방식

​
Postgres에서 정규화되며, 전송 전에

pg_stat_ch는 parse-analyze 단계를 가로채 각 리터럴을 플레이스홀더($1, $2, …)로 바꾸고, 그 결과 패턴을 queryid를 키로 사용하는 백엔드별 LRU에 캐시합니다. 실행기가 SQL 문을 마치면, 그 캐시된 패턴이 이벤트에 첨부됩니다. 값이 포함된 정확한 SQL 문은 데이터베이스 밖으로 나가지 않습니다.

​
데이터베이스에 부담을 최소화

프로듀서는 statement당 약 3%의 오버헤드를 추가합니다. enqueue 경로는 공유 메모리 링 버퍼에서 비차단 try-lock을 사용합니다. 부하가 높아지면 이 확장 기능은 Postgres에 백프레셔를 가하는 대신 카운터를 증가시키고 이벤트를 삭제합니다.

​
집계가 아닌 원시 이벤트

pg_stat_ch는 샘플링이 적용된 상태에서 실행된 각 SQL 문(최상위 및 중첩)에 대해 원시 이벤트 1개를 내보냅니다. UI의 모든 백분위수, 순위, 세부 분석은 동일한 이벤트 스트림에 대해 실행되는 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.
마지막 수정일 2026년 6월 10일