> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-fbfa8bee.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Postgres 쿼리 인사이트

> Managed Postgres용 구문별 텔레메트리: 데이터베이스에서 실행되는 모든 쿼리 패턴을 영향도순으로 보여주고, 각 쿼리가 느린 이유를 설명하는 진단 카운터를 함께 제공합니다

export const Image = ({img, alt, size}) => {
  return <Frame>
      <img src={img} alt={alt} />
    </Frame>;
};

export const galaxyOnClick = eventName => () => {
  try {
    if (typeof window !== "undefined" && window.galaxy && eventName) {
      window.galaxy.track(eventName, {
        interaction: "click"
      });
    }
  } catch (e) {}
};

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <Icon />
                <span>베타</span>
            </a>;
  }
  return <div className="betaBadge">
            <Icon />
            <span>
                베타 기능. 
                <u>
                    <a href="/docs/beta-and-experimental-features#beta-features">
                        자세히 보기.
                    </a>
                </u>
            </span>
        </div>;
};

쿼리 인사이트는 [Managed Postgres](/ko/products/managed-postgres/overview) 인스턴스에서 SQL 문별 텔레메트리를 수집하고
영향도가 큰 순서대로 모든 쿼리 패턴의 순위를 매기므로,
Cloud Console을 벗어나지 않고도 "p99가 서서히 증가하고 있다"에서 "이 패턴에서 디스크 스필이 발생하고 있다"까지
바로 파악할 수 있습니다.

데이터는 [`pg_stat_ch`](https://github.com/clickhouse/pg_stat_ch)에서 가져옵니다.
이 도구는 SQL 문별 카운터를 ClickHouse Cloud로 스트리밍하는
오픈 소스 Postgres 확장 기능입니다. 텔레메트리는 데이터베이스를 떠나기 전에
Postgres 내부에서 정규화되며, 리터럴은 제거되고 플레이스홀더로 대체되므로
쿼리한 정확한 값은 텔레메트리 스트림에 들어가지 않습니다.

<div id="open">
  ## 쿼리 인사이트 열기
</div>

Cloud Console에서 Managed Postgres 인스턴스를 열고 왼쪽 사이드바에서
**쿼리 인사이트**를 클릭합니다. 페이지는 실제 사용 순서에 맞춰 네 개의
영역으로 나뉩니다:

* 한 화면에서 데이터베이스 상태를 점검할 수 있는 **개요**.
* 데이터베이스에서 실행된 모든 쿼리 패턴의 순위를 보여 주며,
  의심되는 기준으로 정렬할 수 있는 **느린 패턴** 테이블.
* 개별 실행 내역을 최신순으로 나열하는 **최근 쿼리** 패널.
* 단일 패턴에 대한 모든 카운터를 집계해 보여 주는 **세부 정보 플라이아웃**.

상단의 **시간 범위** 선택기를 사용해 최근 15분, 1시간, 1일, 1주 또는 1개월로 전환합니다. 집계 버킷 크기는
자동으로 조정됩니다. 최근 15분 또는 1시간에는 1분 버킷,
최근 1일에는 5분 버킷, 최근 1주 또는 1개월에는 1시간 버킷을 사용하므로
차트가 빠르게 응답합니다.

<div id="overview">
  ## 개요
</div>

개요는 6개 패널로 구성된 3×2 그리드입니다:

| Panel                        | What 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에 가깝고, 백분위수
지연 시간은 서로 비슷한 수준으로 따라갑니다.

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/rF8ZX2ZZNpnwXrqH/images/managed-postgres/monitoring/query-insights-overview.png?fit=max&auto=format&n=rF8ZX2ZZNpnwXrqH&q=85&s=9658996396f6e5acb4a12512a59a0ba8" alt="초당 쿼리 수, 쿼리 지연 시간 백분위수, 작업 구성 도넛 차트, 반환/영향을 받은 행 영역 차트, 95.2%의 buffer hit ratio 도넛 차트, 오류 세로 막대 차트를 보여주는 Query Insights 개요" size="lg" border width="2724" height="1612" data-path="images/managed-postgres/monitoring/query-insights-overview.png" />

<div id="slow-patterns">
  ## 느린 쿼리 패턴
</div>

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

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/rF8ZX2ZZNpnwXrqH/images/managed-postgres/monitoring/query-insights-patterns.png?fit=max&auto=format&n=rF8ZX2ZZNpnwXrqH&q=85&s=5e78da12ad4bdfc0dca21f08e261040c" alt="Database, User, Operation, Calls, Errors, Avg latency, P95, Max latency, Total runtime, Rows returned, Cache hit 컬럼과 함께 정규화된 쿼리별로 한 행씩 표시되는 느린 쿼리 패턴 테이블" size="lg" border width="2610" height="702" data-path="images/managed-postgres/monitoring/query-insights-patterns.png" />

<div id="sort">
  ### 의심되는 항목을 기준으로 정렬하기
</div>

이 테이블은 기본적으로 **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개의 컬럼을 제공합니다.

<div id="filters">
  ### 테이블 범위 좁히기
</div>

조사 중인 워크로드의 원하는 범위만 보이도록 테이블을
필터링합니다:

* **데이터베이스**
* **사용자**
* **작업** (`SELECT`, `INSERT`, `UPDATE`, `DELETE`, …)
* **애플리케이션** — connection string에 있는 `application_name`

"orders service가 `sales` DB에서 수행하는 작업만 보여줘"
라는 요청은 드롭다운 2개로 처리할 수 있습니다. 필터 값은
인스턴스에서 실제로 실행된 내용을 기준으로 자동으로 채워집니다.

<div id="recent-queries">
  ## 최근 쿼리
</div>

패턴 테이블 아래의 **최근 쿼리** 패널에는 개별 실행이
최신순으로 나열됩니다. 즉, 패턴당 1행이 아니라 실행된
SQL 문(statement) 1개당 1행이 표시됩니다. 집계 대신 원시 이벤트
스트림이 필요할 때 사용하십시오. 예를 들어 수정 사항이
적용되었는지 확인하거나 오류가 정확히 발생한 시점을
찾을 때 유용합니다.

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/rF8ZX2ZZNpnwXrqH/images/managed-postgres/monitoring/query-insights-recent-queries.png?fit=max&auto=format&n=rF8ZX2ZZNpnwXrqH&q=85&s=9c28e89654201a2e06084871cc04a1ba" alt="Database, User, Operation, Application 필터 드롭다운과 Time, Operation, Query, Duration, Rows, Database, User, Blks read 컬럼이 있는 최근 쿼리 테이블" size="lg" border width="2614" height="1384" data-path="images/managed-postgres/monitoring/query-insights-recent-queries.png" />

기본 컬럼은 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 기준으로
정렬할 수 있습니다.

아무 행이나 클릭하면 패턴 테이블과 동일한 상세 플라이아웃이 열리며,
해당 단일 실행의 패턴으로 범위가 한정됩니다.

<div id="detail">
  ## 세부 정보 플라이아웃
</div>

패턴 또는 최근 쿼리 테이블에서 아무 행이나 클릭하면 오른쪽에 **쿼리
세부 정보** 플라이아웃이 열립니다. 이 플라이아웃은 선택한 시간 범위에서
해당 패턴의 모든 실행을 모아, 느린 이유를 보여 주는
카운터를 집계합니다.

플라이아웃은 스크롤 가능한 단일 레이아웃으로, 5개의 섹션으로 구성됩니다.

* **쿼리 패턴** — 리터럴을 `$1`,
  `$2`, …로 대체한 정규화된 SQL과 클립보드에 복사하는 버튼입니다.
* **집계 리소스 사용량** — 총
  호출 수, 평균/P95/P99/최대 지연 시간, 총 런타임, 반환된 행 수, 캐시
  적중률, 읽은 block 수, 적중한 block 수, CPU 시간, WAL 바이트, 오류를 포함한 13개의 통계 카드 그리드입니다.
* **쿼리 컨텍스트** — 이 패턴이 발생한 데이터베이스, 사용자, 작업, 애플리케이션입니다.
* **주목할 만한 실행** — 오류가 발생한 실행, 유난히 느린 실행,
  대량의 결과를 반환한 실행을 전체 최근 목록보다 먼저 표시합니다.
* **최근 실행** — 동일한 패턴의 개별 실행이며,
  실행별 카운터가 포함됩니다.

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/rF8ZX2ZZNpnwXrqH/images/managed-postgres/monitoring/query-insights-detail-aggregate.png?fit=max&auto=format&n=rF8ZX2ZZNpnwXrqH&q=85&s=38e7ec303612b05be6f39a0289dc459d" alt="쿼리 패턴 코드 블록과 총 호출 수, 지연 시간 백분위수, 총 런타임, 반환된 행 수, 캐시 적중률, 읽은 block 수, 적중한 block 수, CPU 시간, WAL 바이트, 오류를 포함한 13개의 통계 카드가 있는 집계 리소스 사용량 그리드를 보여 주는 쿼리 세부 정보 플라이아웃" size="md" border width="1270" height="1670" data-path="images/managed-postgres/monitoring/query-insights-detail-aggregate.png" />

<Image img="https://mintcdn.com/private-7c7dfe99-mintlify-fbfa8bee/rF8ZX2ZZNpnwXrqH/images/managed-postgres/monitoring/query-insights-detail-recent.png?fit=max&auto=format&n=rF8ZX2ZZNpnwXrqH&q=85&s=fd681d60ffa0891e3ff111d181c0fd6f" alt="쿼리 세부 정보 플라이아웃의 다음 화면으로, 데이터베이스, 사용자, 작업, 애플리케이션이 있는 쿼리 컨텍스트 섹션과 timestamp, OK 상태, server role, host id, duration, 행 수, 캐시 적중, CPU, 공유 block 읽기 수, 공유 block 적중 수에 대한 실행별 카운터가 있는 최근 실행 카드를 보여 줍니다" size="md" border width="1278" height="1148" data-path="images/managed-postgres/monitoring/query-insights-detail-recent.png" />

<div id="counters">
  ### 실행별 카운터
</div>

최근 실행을 펼치면 시간이 어디에 쓰였는지 정확히 짚어주는
카운터를 확인할 수 있습니다:

* **공유 블록** — read와 hit는 항상 표시되며, written과 dirtied는
  0이 아닐 때만 표시됩니다.
* **로컬 및 임시 블록 작업** — 0이 아닌 임시 블록 작업은 sort 또는
  hash가 디스크로 spill되었음을 의미합니다.
* **읽기 / 쓰기 시간** — CPU 시간과 별도로 표시되는 I/O 시간입니다.
* **CPU 시간** — 사용자 시간과 시스템 시간이 각각 별도로 표시됩니다.
* **병렬 worker** — 계획된 수와 실제로 시작된 수를 보여줍니다.
* **JIT** — 전체 JIT 컴파일 시간과 함수 개수입니다.
* **WAL** — 바이트 수와 레코드 수입니다.

느린 pattern을 진단하는 데 필요한 모든 정보를 한곳, 한 화면에서
확인할 수 있습니다.

<div id="api">
  ## 쿼리 인사이트 API
</div>

동일한 텔레메트리는
[ClickHouse Cloud OpenAPI](/ko/products/managed-postgres/openapi#query-insights)를 통해
프로그래밍 방식으로도 이용할 수 있습니다.
[Slow patterns](#slow-patterns) 테이블은
[list slow query patterns](/ko/api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/slowQueryPatternsGetList)
엔드포인트에 매핑되며, [세부 정보 패널](#detail)은
[get slow query pattern](/ko/api-reference/organization/get-list-of-available-organizations#tag/Postgres/operation/slowQueryPatternGet)
엔드포인트에 매핑됩니다. 이 엔드포인트는 단일 패턴의 집계 메트릭과
최근 실행 내역을 함께 반환합니다.

<div id="how-it-works">
  ## 동작 방식
</div>

<div id="how-normalized">
  ### Postgres에서 정규화되며, 전송 전에
</div>

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

<div id="how-overhead">
  ### 데이터베이스에 부담을 최소화
</div>

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

<div id="how-raw-events">
  ### 집계가 아닌 원시 이벤트
</div>

`pg_stat_ch`는 샘플링이 적용된 상태에서 실행된 각 SQL 문(최상위 및
중첩)에 대해 원시 이벤트 1개를 내보냅니다. UI의 모든 백분위수, 순위, 세부
분석은 동일한 이벤트 스트림에 대해 실행되는 ClickHouse 쿼리입니다.

<div id="how-engine">
  ### 고객이 사용하는 것과 동일한 엔진
</div>

Insights 백엔드는 [ClickHouse Cloud](/ko/products/cloud/getting-started/intro)입니다.
트래픽이 많은 Postgres 인스턴스에서 발생하는 쿼리별 telemetry 데이터는 하루에
수백만 행에 이르지만, 열 지향 Compression 덕분에 실행 단위의 세부 데이터를
몇 개월 동안도 저렴하게 보관할 수 있으며, 수십억 행에 대한 1초 미만의 집계로
1주일 또는 1개월 범위로 분석하더라도 UI를 즉각적으로 사용할 수 있습니다.

<div id="how-open-source">
  ### 오픈 소스
</div>

`pg_stat_ch`는 Apache 2.0 라이선스로 제공됩니다. 어떤 Postgres에서든 실행할 수 있고, 어떤
ClickHouse로든 전송할 수 있습니다. 소스 코드와 이슈는 다음에서 확인할 수 있습니다.
[github.com/clickhouse/pg\_stat\_ch](https://github.com/clickhouse/pg_stat_ch).

<div id="related">
  ## 관련 페이지
</div>

* [모니터링 대시보드](/ko/products/managed-postgres/monitoring/dashboard) — 기본 제공 리소스 및 활동 차트
* [Prometheus 엔드포인트](/ko/products/managed-postgres/monitoring/prometheus) — 호스트 수준 메트릭을 자체 관측성 스택으로 스크레이프
* [Managed Postgres OpenAPI](/ko/products/managed-postgres/openapi#query-insights) — 느린 패턴과 최근 실행 내역을 프로그래밍 방식으로 조회
* [확장 기능](/ko/products/managed-postgres/extensions) — Managed Postgres 인스턴스에서 사용할 수 있는 확장 기능
* [GitHub의 `pg_stat_ch`](https://github.com/clickhouse/pg_stat_ch) — Query Insights를 지원하는 오픈소스 확장 기능