> ## 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>
  **요약**

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

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

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

자체 기존 환경을 구성하기 전에 PostgreSQL 로그 통합을 먼저 테스트하려면 ["데모 데이터세트"](/ko/clickstack/integration-examples/postgres-logs#demo-dataset) 섹션의 사전 구성된 설정과 샘플 데이터를 사용할 수 있습니다.

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

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

<Steps>
  <Step>
    #### 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`에 다음 설정을 추가하거나 수정하십시오:

    ```conf theme={null}
    # 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                 # 잠금 경합 로깅
    ```

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

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

    ```bash theme={null}
    # systemd의 경우
    sudo systemctl restart postgresql

    # Docker의 경우
    docker restart 
    ```

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

    ```bash theme={null}
    # Linux 기본 로그 위치
    tail -f /var/lib/postgresql/{version}/main/log/postgresql-*.log

    # macOS Homebrew
    tail -f /usr/local/var/postgres/log/postgresql-*.log
    ```
  </Step>

  <Step>
    #### 사용자 지정 OTel collector 구성 만들기

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

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

    ```yaml theme={null}
    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로 라우팅합니다

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

  <Step>
    #### 사용자 지정 구성 파일을 로드하도록 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 배포 구성을 업데이트합니다:

    ```yaml theme={null}
    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`으로 올인원 이미지를 사용하는 경우에는 다음과 같습니다.

    ```bash theme={null}
    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
    ```

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

  <Step>
    #### HyperDX에서 로그 확인하기

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-logs-search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=87ab35375b03f510dedf4c94fa6169e6" alt="로그 Search view" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=f67799801fd754bb381c4a88ba259b1a" alt="Log view" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-log-view.png" />
  </Step>
</Steps>

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

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

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

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

    ```bash theme={null}
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/postgres/postgresql.log
    ```
  </Step>

  <Step>
    #### 테스트용 collector 구성 생성

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

    ```yaml theme={null}
    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
    ```
  </Step>

  <Step>
    #### 데모 구성으로 ClickStack 실행

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

    ```bash theme={null}
    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
    ```
  </Step>

  <Step>
    #### HyperDX에서 로그 확인

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

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

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-logs-search-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=87ab35375b03f510dedf4c94fa6169e6" alt="로그 Search view" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-log-view.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=f67799801fd754bb381c4a88ba259b1a" alt="로그 view" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-log-view.png" />
  </Step>
</Steps>

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

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

<Steps>
  <Step>
    #### <TrackedLink href={'/ko/examples/postgres-logs-dashboard.json'} download="postgresql-logs-dashboard.json" eventName="docs.postgres_logs_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. `postgresql-logs-dashboard.json` 파일을 업로드한 뒤 **Finish Import**를 클릭합니다

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

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-8c05c8a2/mGB-7MnBG_6npuhw/images/clickstack/postgres/postgres-logs-dashboard.png?fit=max&auto=format&n=mGB-7MnBG_6npuhw&q=85&s=7a4ae98a5f93e2ee57257ae7a3c58a09" alt="로그 대시보드" width="3808" height="1926" data-path="images/clickstack/postgres/postgres-logs-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 | head -10
```

<div id="no-logs">
  ### HyperDX에 로그가 표시되지 않는 경우
</div>

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

```bash theme={null}
docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
```

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

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

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

```bash theme={null}
docker exec <container> cat /tmp/postgres-demo/postgresql.log | wc -l
```

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

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

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

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