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

# ClickStack으로 PostgreSQL 메트릭 모니터링

> ClickStack으로 PostgreSQL 메트릭 모니터링

export const TrackedLink = ({href, eventName, children, ...rest}) => {
  const handleClick = () => {
    try {
      if (typeof window !== "undefined" && window.galaxy && eventName) {
        window.galaxy.track(eventName, {
          interaction: "click"
        });
      }
    } catch (e) {}
  };
  return <a href={href} onClick={handleClick} {...rest}>
      {children}
    </a>;
};

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

<Info>
  **핵심 요약**

  ClickStack에서 OTel PostgreSQL 수신기를 사용해 PostgreSQL 성능 메트릭을 모니터링할 수 있습니다. 데모 데이터셋과 사전 구축된 대시보드가 포함되어 있습니다.
</Info>

<div id="existing-postgres">
  ## 기존 PostgreSQL 통합
</div>

이 섹션에서는 ClickStack OTel collector를 PostgreSQL 수신기로 구성하여, 기존 PostgreSQL 설치에서 ClickStack으로 메트릭을 전송하도록 설정하는 방법을 설명합니다.

기존 환경을 직접 구성하기 전에 PostgreSQL 메트릭 통합을 테스트해 보고 싶다면, [다음 섹션](#demo-dataset)에서 제공하는 사전 구성된 데모 데이터셋으로 테스트할 수 있습니다.

<div id="prerequisites">
  ##### 사전 요구 사항
</div>

* 실행 중인 ClickStack 인스턴스
* 기존 PostgreSQL 설치(버전 9.6 이상)
* ClickStack에서 PostgreSQL로의 네트워크 접근(기본 포트 5432)
* 적절한 권한이 있는 PostgreSQL 모니터링 사용자

<Steps>
  <Step>
    #### 모니터링 사용자에게 필요한 권한이 있는지 확인

    PostgreSQL 수신기는 통계 뷰에 대한 읽기 권한이 있는 사용자가 필요합니다. 모니터링 사용자에게 `pg_monitor` 역할을 부여하십시오.

    ```sql theme={null}
    GRANT pg_monitor TO your_monitoring_user;
    ```
  </Step>

  <Step>
    #### 사용자 지정 OTel collector 구성 생성

    ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정하여 기본 OpenTelemetry collector 구성을 확장할 수 있습니다.

    `postgres-metrics.yaml` 파일을 생성하십시오.

    ```yaml theme={null}
    receivers:
      postgresql:
        endpoint: postgres-host:5432
        transport: tcp
        username: otel_monitor
        password: ${env:POSTGRES_PASSWORD}
        databases:
          - postgres
          - your_application_db # 실제 데이터베이스 이름으로 대체
        collection_interval: 30s
        tls:
          insecure: true

    processors:
      resourcedetection:
        detectors: [env, system, docker]
        timeout: 5s
      batch:
        timeout: 10s
        send_batch_size: 10000

    exporters:
      clickhouse:
        endpoint: tcp://localhost:9000
        database: default
        ttl: 96h

    service:
      pipelines:
        metrics/postgres:
          receivers: [postgresql]
          processors: [resourcedetection, batch]
          exporters: [clickhouse]
    ```

    <Note>
      `tls: insecure: true` 설정은 개발/테스트 환경에서 SSL 검증을 비활성화합니다. 운영 환경에서 SSL이 활성화된 PostgreSQL을 사용하는 경우 이 줄을 제거하거나 적절한 인증서를 구성하십시오.
    </Note>
  </Step>

  <Step>
    #### 사용자 지정 구성으로 ClickStack 배포

    사용자 지정 구성을 마운트하십시오.

    ```bash theme={null}
    docker run -d \
      --name clickstack-postgres \
      -p 8123:8123 -p 9000:9000 -p 4317:4317 -p 4318:4318 \
      -e HYPERDX_API_KEY=your-api-key \
      -e CLICKHOUSE_PASSWORD=your-clickhouse-password \
      -e POSTGRES_PASSWORD=secure_password_here \
      -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
      -v "$(pwd)/postgres-metrics.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      clickhouse/clickstack:latest
    ```
  </Step>

  <Step>
    #### 메트릭 수집 확인

    구성이 완료되면 HyperDX에 로그인하여 메트릭이 수집되고 있는지 확인하십시오.

    1. Metrics Explorer로 이동합니다
    2. `postgresql`로 시작하는 메트릭을 검색합니다. (예: `postgresql.backends`, `postgresql.commits`)
    3. 구성한 수집 인터벌에 따라 메트릭 데이터 포인트가 표시되어야 합니다

    메트릭이 수집되기 시작하면 [대시보드 및 시각화](#dashboards) 섹션으로 이동하여 사전 구축된 대시보드를 가져오십시오.
  </Step>
</Steps>

<div id="demo-dataset">
  ## 데모 데이터세트
</div>

운영 환경을 구성하기 전에 PostgreSQL 메트릭 통합을 테스트하려는 사용자를 위해, 실제 PostgreSQL 메트릭 패턴을 반영한 미리 생성된 데이터세트를 제공합니다.

<Info>
  **데이터베이스 수준 메트릭만 포함**

  이 데모 데이터셋에는 샘플 데이터를 가볍게 유지하기 위해 데이터베이스 수준 메트릭만 포함되어 있습니다. 실제 PostgreSQL 데이터베이스를 모니터링할 때는 테이블 및 인덱스 메트릭도 자동으로 수집됩니다.
</Info>

<Steps>
  <Step>
    #### 샘플 메트릭 데이터셋 다운로드

    미리 생성된 메트릭 파일을 다운로드합니다(현실적인 패턴이 반영된 24시간 분량의 PostgreSQL 메트릭).

    ```bash theme={null}
    # Gauge 메트릭 다운로드(연결, 데이터베이스 크기)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-gauge.csv

    # Sum 메트릭 다운로드(커밋, 롤백, 작업)
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgres-metrics-sum.csv
    ```

    데이터셋에는 다음과 같은 현실적인 패턴이 포함되어 있습니다.

    * **오전 연결 급증(08:00)** - 로그인 집중 시간
    * **캐시 성능 문제(11:00)** - Blocks\_read 급증
    * **애플리케이션 버그(14:00-14:30)** - 롤백 비율이 15%까지 급증
    * **교착 상태 발생(14:15, 16:30)** - 드물게 발생하는 교착 상태
  </Step>

  <Step>
    #### ClickStack 시작

    ClickStack 인스턴스를 시작합니다.

    ```bash theme={null}
    docker run -d --name clickstack-postgres-demo \
      -p 8080:8080 -p 4317:4317 -p 4318:4318 \
      clickhouse/clickstack-all-in-one:latest
    ```

    ClickStack이 완전히 시작될 때까지 약 30초 정도 기다립니다.
  </Step>

  <Step>
    #### ClickStack에 메트릭 로드

    메트릭을 ClickHouse에 직접 로드합니다.

    ```bash theme={null}
    # Gauge 메트릭 로드
    cat postgres-metrics-gauge.csv | docker exec -i clickstack-postgres-demo \
      clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

    # Sum 메트릭 로드
    cat postgres-metrics-sum.csv | docker exec -i clickstack-postgres-demo \
      clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"
    ```
  </Step>

  <Step>
    #### HyperDX에서 메트릭 확인

    로드가 완료되면 메트릭을 가장 빠르게 확인하는 방법은 사전 구축된 대시보드를 사용하는 것입니다.

    대시보드를 가져와 여러 PostgreSQL 메트릭을 한 번에 보려면 [대시보드 및 시각화](#dashboards) 섹션으로 이동하십시오.

    <Info>
      **시간대 표시**

      HyperDX는 브라우저의 로컬 시간대로 타임스탬프를 표시합니다. 데모 데이터는 **2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)** 범위를 포함합니다. 위치와 관계없이 데모 메트릭이 표시되도록 시간 범위를 **2025-11-09 00:00:00 - 2025-11-12 00:00:00**로 설정하십시오. 메트릭이 표시되면 더 명확하게 시각화할 수 있도록 범위를 24시간으로 좁힐 수 있습니다.
    </Info>
  </Step>
</Steps>

<div id="dashboards">
  ## 대시보드 및 시각화
</div>

ClickStack으로 PostgreSQL 모니터링을 빠르게 시작할 수 있도록 PostgreSQL 메트릭을 위한 핵심 시각화를 제공합니다.

<Steps>
  <Step>
    #### <TrackedLink href={'/ko/examples/postgres-metrics-dashboard.json'} download="postgres-metrics-dashboard.json" eventName="docs.postgres_metrics_monitoring.dashboard_download">다운로드</TrackedLink>할 대시보드 구성 파일
  </Step>

  <Step>
    #### 사전 구축된 대시보드 가져오기

    1. HyperDX를 열고 Dashboards 섹션으로 이동합니다
    2. 오른쪽 상단의 점 3개 메뉴에서 **Import Dashboard**를 클릭합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=21af53f2ddc48534745ebc3f01de39ef" alt="대시보드 가져오기 버튼" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. `postgres-metrics-dashboard.json` 파일을 업로드한 다음 **Finish Import**를 클릭합니다

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/import-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=06633de13d9406e87da357adc9a339d8" alt="가져오기 완료 대화상자" width="3808" height="1910" data-path="images/clickstack/postgres/import-dashboard.png" />
  </Step>

  <Step>
    #### 대시보드 보기

    모든 시각화가 미리 구성된 상태로 대시보드가 생성됩니다:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-metrics-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=c6fed08b4556d8af308767a33aa8d4fd" alt="PostgreSQL 메트릭 대시보드" width="3808" height="1910" data-path="images/clickstack/postgres/postgres-metrics-dashboard.png" />

    <Note>
      데모 데이터세트의 경우 시간 범위를 \*\*2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)\*\*로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되지 않습니다.
    </Note>
  </Step>
</Steps>

<div id="troubleshooting">
  ## 문제 해결
</div>

<div id="troubleshooting-not-loading">
  ### 사용자 지정 구성이 로드되지 않는 경우
</div>

환경 변수가 설정되어 있는지 확인하세요:

```bash theme={null}
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
```

사용자 지정 구성 파일이 마운트되었는지 확인하세요:

```bash theme={null}
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
```

<div id="no-metrics">
  ### HyperDX에 메트릭이 표시되지 않는 경우
</div>

PostgreSQL에 연결할 수 있는지 확인하십시오:

```bash theme={null}
docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"
```

OTel collector의 로그를 확인하세요:

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres
```

<div id="auth-errors">
  ### 인증 오류
</div>

password가 올바르게 설정되어 있는지 확인하세요:

```bash theme={null}
docker exec <clickstack-container> printenv POSTGRES_PASSWORD
```

자격 증명을 직접 테스트하세요:

```bash theme={null}
psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"
```

<div id="next-steps">
  ## 다음 단계
</div>

* 중요한 임계값(연결 수 한도, 높은 롤백 비율, 낮은 캐시 적중률)에 대한 [알림](/ko/clickstack/features/alerts)을 설정하세요
* `pg_stat_statements` 확장 기능을 사용해 쿼리 수준 모니터링을 활성화하세요
* 서로 다른 엔드포인트와 서비스 이름으로 수신기 구성을 복제해 여러 PostgreSQL 인스턴스를 모니터링하세요

<div id="going-to-production">
  ## 프로덕션 환경으로 전환
</div>

이 가이드는 빠른 설정을 위해 ClickStack에 기본 제공되는 OpenTelemetry Collector를 확장해 사용합니다. 프로덕션 환경에 배포할 때는 자체 OTel Collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 전송하는 것을 권장합니다. 프로덕션 환경 구성은 [OpenTelemetry 데이터 전송](/ko/clickstack/ingesting-data/opentelemetry)을 참조하십시오.