ClickStack으로 PostgreSQL 메트릭 모니터링

기존 PostgreSQL 통합

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

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

사전 요구 사항

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

모니터링 사용자에게 필요한 권한이 있는지 확인

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

GRANT pg_monitor TO your_monitoring_user;

사용자 지정 OTel collector 구성 생성

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

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

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]

사용자 지정 구성으로 ClickStack 배포

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

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

메트릭 수집 확인

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

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

메트릭이 수집되기 시작하면 대시보드 및 시각화 섹션으로 이동하여 사전 구축된 대시보드를 가져오십시오.

데모 데이터세트

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

샘플 메트릭 데이터셋 다운로드

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

# 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) - 드물게 발생하는 교착 상태

ClickStack 시작

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

docker run -d --name clickstack-postgres-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

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

ClickStack에 메트릭 로드

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

# 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"

HyperDX에서 메트릭 확인

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

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

대시보드 및 시각화

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

대시보드 구성 다운로드

대시보드 구성 파일 다운로드.

사전 구축된 대시보드 가져오기

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

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

대시보드 보기

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

문제 해결

사용자 지정 구성이 로드되지 않는 경우

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

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

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

docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

HyperDX에 메트릭이 표시되지 않는 경우

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

docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"

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

docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres

인증 오류

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

docker exec <clickstack-container> printenv POSTGRES_PASSWORD

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

psql -h postgres-host -U otel_monitor -d postgres -c "SELECT version();"

다음 단계

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

프로덕션 환경으로 전환하기

이 가이드는 ClickStack에 기본 제공되는 OpenTelemetry Collector를 빠르게 설정할 수 있도록 확장한 것입니다. 프로덕션 배포에서는 자체 OTel Collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 전송하는 것을 권장합니다. 프로덕션 구성은 OpenTelemetry 데이터 전송을 참조하십시오.