ClickStack으로 PostgreSQL 로그 모니터링

ClickStack으로 PostgreSQL 로그 모니터링

요약

OTel filelog 수신기를 사용해 PostgreSQL 서버 로그(CSV 형식)를 ClickStack으로 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함되어 있습니다.

​

기존 PostgreSQL와의 통합

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

자체 기존 환경을 구성하기 전에 PostgreSQL 로그 통합을 먼저 테스트하려면 “데모 데이터세트” 섹션의 사전 구성된 설정과 샘플 데이터를 사용할 수 있습니다.

사전 요구 사항

• 실행 중인 ClickStack 인스턴스
• 기존 PostgreSQL 설치(버전 9.6 이상)
• PostgreSQL 설정 파일을 수정할 수 있는 권한
• 로그 파일을 저장할 수 있는 충분한 디스크 공간

1. ​

   PostgreSQL 로깅 구성

   PostgreSQL은 여러 로그 포맷을 지원합니다. OpenTelemetry에서 구조화된 방식으로 파싱하려면, 일관되고 파싱하기 쉬운 출력을 제공하는 CSV 형식을 권장합니다.

   postgresql.conf 파일은 일반적으로 다음 위치에 있습니다:

   • Linux (apt/yum): /etc/postgresql/{version}/main/postgresql.conf
   • macOS (Homebrew): /usr/local/var/postgres/postgresql.conf 또는 /opt/homebrew/var/postgres/postgresql.conf
   • Docker: 일반적으로 환경 변수 또는 마운트된 구성 파일을 통해 설정합니다

   postgresql.conf에 다음 설정을 추가하거나 수정하십시오:

   # CSV 로깅에 필요한 설정
   logging_collector = on
   log_destination = 'csvlog'
   
   # 권장: 연결 로깅
   log_connections = on
   log_disconnections = on
   
   # 선택 사항: 모니터링 요구 사항에 따라 조정
   #log_min_duration_statement = 1000  # 1초 이상 소요되는 쿼리 로깅
   #log_statement = 'ddl'               # DDL SQL 문 로깅 (CREATE, ALTER, DROP)
   #log_checkpoints = on                # 체크포인트 활동 로깅
   #log_lock_waits = on                 # 잠금 경합 로깅
   

   이 가이드에서는 안정적으로 구조화된 파싱을 수행하기 위해 PostgreSQL의 csvlog 포맷을 사용합니다. stderr 또는 jsonlog 포맷을 사용 중이라면 이에 맞게 OpenTelemetry collector 구성을 조정해야 합니다.

   이렇게 변경한 후 PostgreSQL을 다시 시작하십시오:

   # systemd의 경우
   sudo systemctl restart postgresql
   
   # Docker의 경우
   docker restart 
   

   로그가 기록되고 있는지 확인하세요:

   # Linux 기본 로그 위치
   tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log
   
   # macOS Homebrew
   tail -f /usr/local/var/postgres/log/postgresql-*.log
   
2. ​

   사용자 지정 OTel collector 구성 만들기

   ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정해 기본 OpenTelemetry Collector 구성을 확장할 수 있습니다. 사용자 지정 구성은 OpAMP를 통해 HyperDX가 관리하는 기본 구성과 머지됩니다.

   다음 구성으로 postgres-logs-monitoring.yaml 파일을 생성하십시오:

   receivers:
     filelog/postgres:
       include:
         - /var/lib/postgresql/*/main/log/postgresql-*.csv # PostgreSQL 설치 경로에 맞게 수정하세요
       start_at: end
       multiline:
         line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
       operators:
         - type: csv_parser
           parse_from: body
           parse_to: attributes
           header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
           lazy_quotes: true
           
         - type: time_parser
           parse_from: attributes.log_time
           layout: '%Y-%m-%d %H:%M:%S.%L %Z'
         
         - type: add
           field: attributes.source
           value: "postgresql"
         
         - type: add
           field: resource["service.name"]
           value: "postgresql-production"
   
   service:
     pipelines:
       logs/postgres:
         receivers: [filelog/postgres]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   

   이 구성은 다음을 수행합니다:

   • PostgreSQL CSV 로그를 기본 위치에서 읽습니다
   • 여러 줄로 된 로그 항목을 처리합니다(오류는 여러 줄에 걸치는 경우가 많습니다)
   • 모든 표준 PostgreSQL 로그 필드를 포함하는 CSV 형식을 파싱합니다
   • 원래 로그 시점을 유지할 수 있도록 타임스탬프를 추출합니다
   • HyperDX에서 필터링할 수 있도록 source: postgresql 속성을 추가합니다
   • 전용 파이프라인을 통해 로그를 ClickHouse exporter로 라우팅합니다

   • 사용자 지정 구성에서는 새 수신기와 파이프라인만 정의합니다
   • processor(memory_limiter, transform, batch)와 exporter(clickhouse)는 기본 ClickStack 구성에 이미 정의되어 있으므로 이름으로 참조만 하면 됩니다
   • csv_parser 연산자는 표준 PostgreSQL CSV 로그 필드를 모두 구조화된 속성으로 추출합니다
   • 이 구성은 collector가 재시작될 때 로그를 다시 수집하지 않도록 start_at: end를 사용합니다. 테스트할 때는 start_at: beginning으로 변경하면 과거 로그를 즉시 확인할 수 있습니다.
   • PostgreSQL 로그 디렉터리 위치에 맞게 include 경로를 조정하십시오
3. ​

   사용자 지정 구성 파일을 로드하도록 ClickStack 구성

   기존 ClickStack 배포에서 사용자 지정 collector 구성을 활성화하려면 다음을 수행해야 합니다.

   1. 사용자 지정 구성 파일을 /etc/otelcol-contrib/custom.config.yaml에 마운트합니다
   2. 환경 변수 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml를 설정합니다
   3. collector가 로그를 읽을 수 있도록 PostgreSQL 로그 디렉터리를 마운트합니다

   옵션 1: Docker Compose

   ClickStack 배포 구성을 업데이트합니다:

   services:
     clickstack:
       # ... 기존 구성 ...
       environment:
         - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
         # ... 기타 환경 변수 ...
       volumes:
         - ./postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
         - /var/lib/postgresql:/var/lib/postgresql:ro
         # ... 기타 볼륨 ...
   

   옵션 2: Docker Run (올인원 이미지)

   docker run으로 올인원 이미지를 사용하는 경우에는 다음과 같습니다.

   docker run --name clickstack \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/postgres-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v /var/lib/postgresql:/var/lib/postgresql:ro \
     clickhouse/clickstack-all-in-one:latest
   

   ClickStack collector에 PostgreSQL 로그 파일을 읽는 데 필요한 적절한 권한이 있는지 확인하세요. 프로덕션 환경에서는 읽기 전용 마운트(:ro)를 사용하고 최소 권한 원칙을 준수하십시오.

4. ​

   HyperDX에서 로그 확인하기

   구성이 완료되면 HyperDX에 로그인한 다음 로그가 정상적으로 유입되는지 확인하십시오:

   1. Search view로 이동합니다
   2. source를 Logs로 설정합니다
   3. PostgreSQL 관련 로그를 보려면 source:postgresql로 필터링합니다
   4. user_name, database_name, error_severity, message, query 등의 필드가 포함된 구조화된 로그 항목이 표시되어야 합니다

​

데모 데이터세트

프로덕션 시스템을 구성하기 전에 PostgreSQL 로그 통합을 테스트하려는 사용자를 위해, 실제 패턴과 유사하게 미리 생성된 PostgreSQL 로그 샘플 데이터셋을 제공합니다.

1. ​

   샘플 데이터셋 다운로드

   샘플 로그 파일을 다운로드하세요.

   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.log
   
2. ​

   테스트용 collector 구성 생성

   다음 구성으로 postgres-logs-demo.yaml 파일을 생성하세요.

   cat > postgres-logs-demo.yaml << 'EOF'
   receivers:
     filelog/postgres:
       include:
         - /tmp/postgres-demo/postgresql.log
       start_at: beginning  # 데모 데이터는 처음부터 읽기
       multiline:
         line_start_pattern: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
       operators:
         - type: csv_parser
           parse_from: body
           parse_to: attributes
           header: 'log_time,user_name,database_name,process_id,connection_from,session_id,session_line_num,command_tag,session_start_time,virtual_transaction_id,transaction_id,error_severity,sql_state_code,message,detail,hint,internal_query,internal_query_pos,context,query,query_pos,location,application_name,backend_type,leader_pid,query_id'
           lazy_quotes: true
           
         - type: time_parser
           parse_from: attributes.log_time
           layout: '%Y-%m-%d %H:%M:%S.%L %Z'
         
         - type: add
           field: attributes.source
           value: "postgresql-demo"
         
         - type: add
           field: resource["service.name"]
           value: "postgresql-demo"
   
   service:
     pipelines:
       logs/postgres-demo:
         receivers: [filelog/postgres]
         processors:
           - memory_limiter
           - transform
           - batch
         exporters:
           - clickhouse
   EOF
   
3. ​

   데모 구성으로 ClickStack 실행

   데모 로그와 구성을 사용해 ClickStack을 실행하세요.

   docker run --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
     -v "$(pwd)/postgres-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
     -v "$(pwd)/postgresql.log:/tmp/postgres-demo/postgresql.log:ro" \
     clickhouse/clickstack-all-in-one:latest
   
4. ​

   HyperDX에서 로그 확인

   ClickStack이 실행되면 다음을 수행하세요.

   1. HyperDX를 열고 계정에 로그인하세요(먼저 계정을 만들어야 할 수 있습니다)
   2. Search view로 이동한 다음 source를 Logs로 설정하세요
   3. 시간 범위를 2025-11-09 00:00:00 - 2025-11-12 00:00:00으로 설정하세요

   시간대 표시

   HyperDX는 브라우저의 로컬 시간대로 타임스탬프를 표시합니다. 데모 데이터는 2025-11-10 00:00:00 - 2025-11-11 00:00:00 (UTC) 범위에 걸쳐 있습니다. 넉넉한 시간 범위를 설정하면 위치와 관계없이 데모 로그를 확인할 수 있습니다. 로그가 보이면 더 명확한 시각화를 위해 24시간 범위로 좁힐 수 있습니다.

​

대시보드 및 시각화

ClickStack으로 PostgreSQL 로그 모니터링을 시작할 수 있도록, PostgreSQL 로그용 필수 시각화를 제공합니다.

1. ​

   대시보드 구성 파일

2. ​

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

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

   3. postgresql-logs-dashboard.json 파일을 업로드한 뒤 Finish Import를 클릭합니다
3. ​

   대시보드 보기

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

   데모 데이터세트의 경우 시간 범위를 **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 | head -10

​

HyperDX에 로그가 표시되지 않는 경우

실제로 적용된 구성에 filelog 수신기가 포함되어 있는지 확인하십시오:

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

collector 로그에서 오류가 있는지 확인하세요:

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

데모 데이터세트를 사용하는 경우 로그 파일에 접근할 수 있는지 확인하세요:

docker exec <container> cat /tmp/postgres-demo/postgresql.log | wc -l

​

다음 단계

• 중요한 이벤트(연결 실패, 느린 쿼리, 오류 급증)에 대한 알림을 설정하세요
• 종합적인 데이터베이스 모니터링을 위해 로그를 PostgreSQL 메트릭과 연관시키세요
• 애플리케이션별 쿼리 패턴에 맞는 사용자 지정 대시보드를 만드세요
• 성능 요구 사항에 따라 느린 쿼리를 식별할 수 있도록 log_min_duration_statement를 구성하세요

​

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

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