핵심 요약ClickStack에서 OTel PostgreSQL 수신기를 사용해 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]
tls: insecure: true 설정은 개발/테스트 환경에서 SSL 검증을 비활성화합니다. 운영 환경에서 SSL이 활성화된 PostgreSQL을 사용하는 경우 이 줄을 제거하거나 적절한 인증서를 구성하십시오.
사용자 지정 구성으로 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 데이터베이스를 모니터링할 때는 테이블 및 인덱스 메트릭도 자동으로 수집됩니다.
샘플 메트릭 데이터셋 다운로드
미리 생성된 메트릭 파일을 다운로드합니다(현실적인 패턴이 반영된 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에 메트릭 로드
메트릭을 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 메트릭을 한 번에 보려면 대시보드 및 시각화 섹션으로 이동하십시오.시간대 표시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시간으로 좁힐 수 있습니다.
사전 구축된 대시보드 가져오기
- HyperDX를 열고 Dashboards 섹션으로 이동합니다
- 오른쪽 상단의 점 3개 메뉴에서 Import Dashboard를 클릭합니다
postgres-metrics-dashboard.json 파일을 업로드한 다음 Finish Import를 클릭합니다
대시보드 보기
모든 시각화가 미리 구성된 상태로 대시보드가 생성됩니다:데모 데이터세트의 경우 시간 범위를 **2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC)**로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되지 않습니다.
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml
docker exec <clickstack-container> psql -h postgres-host -U otel_monitor -d postgres -c "SELECT 1"
docker exec <container> cat /etc/otel/supervisor-data/agent.log | grep -i postgres
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 데이터 전송을 참조하십시오.
