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

# ClickStack으로 Nginx 로그 모니터링

> ClickStack으로 Nginx 모니터링

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` 수신기를 사용해 ClickStack에서 Nginx 액세스 로그(JSON 포맷)를 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함됩니다.
</Info>

<div id="existing-nginx">
  ## 기존 Nginx 통합
</div>

이 섹션에서는 ClickStack OTel collector 구성을 수정해 기존 Nginx 설치에서 로그를 ClickStack으로 전송하도록 설정하는 방법을 설명합니다.
기존 환경을 직접 구성하기 전에 통합을 테스트하려면, [다음 섹션](/ko/clickstack/integration-examples/nginx-logs#demo-dataset)에서 미리 구성된 환경과 샘플 데이터로 테스트할 수 있습니다.

<div id="prerequisites">
  ##### 사전 준비 사항
</div>

* 실행 중인 ClickStack 인스턴스
* 기존에 설치된 Nginx
* Nginx 설정 파일을 수정할 수 있는 권한

<Steps>
  <Step>
    #### Nginx 로그 포맷 구성

    먼저, 로그를 더 쉽게 파싱할 수 있도록 Nginx가 JSON 포맷으로 로그를 출력하게 구성합니다. 다음 로그 포맷 정의를 `nginx.conf`에 추가하세요:

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

    * **Linux (apt/yum)**: `/etc/nginx/nginx.conf`
    * **macOS (Homebrew)**: `/usr/local/etc/nginx/nginx.conf` 또는 `/opt/homebrew/etc/nginx/nginx.conf`
    * **Docker**: 구성 파일은 일반적으로 볼륨으로 마운트됩니다

    다음 로그 포맷 정의를 `http` 블록에 추가하세요:

    ```nginx theme={null}
    http {
        log_format json_combined escape=json
        '{'
          '"time_local":"$time_local",'
          '"remote_addr":"$remote_addr",'
          '"request_method":"$request_method",'
          '"request_uri":"$request_uri",'
          '"status":$status,'
          '"body_bytes_sent":$body_bytes_sent,'
          '"request_time":$request_time,'
          '"upstream_response_time":"$upstream_response_time",'
          '"http_referer":"$http_referer",'
          '"http_user_agent":"$http_user_agent"'
        '}';

        access_log /var/log/nginx/access.log json_combined;
        error_log /var/log/nginx/error.log warn;
    }
    ```

    이 변경을 적용한 후 Nginx를 다시 로드하세요.
  </Step>

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

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

    다음 구성으로 nginx-monitoring.yaml 파일을 만드세요:

    ```yaml theme={null}
    receivers:
      filelog:
        include:
          - /var/log/nginx/access.log
          - /var/log/nginx/error.log
        start_at: end 
        operators:
          - type: json_parser
            parse_from: body
            parse_to: attributes
          - type: time_parser
            parse_from: attributes.time_local
            layout: '%d/%b/%Y:%H:%M:%S %z'
          - type: add
            field: attributes.source
            value: "nginx"

    service:
      pipelines:
        logs/nginx:
          receivers: [filelog]
          processors:
            - memory_limiter
            - transform
            - batch
          exporters:
            - clickhouse
    ```

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

    * 표준 위치에서 Nginx 로그를 읽습니다
    * JSON 로그 항목을 파싱합니다
    * 원본 로그 타임스탬프를 추출하여 유지합니다
    * HyperDX에서 필터링할 수 있도록 source: Nginx 속성을 추가합니다
    * 전용 파이프라인을 통해 로그를 ClickHouse exporter로 라우팅합니다

    <Note>
      - 사용자 지정 구성에서는 새 수신기와 파이프라인만 정의합니다
      - 프로세서(memory\_limiter, transform, batch)와 exporter(clickhouse)는 기본 ClickStack 구성에 이미 정의되어 있으므로 이름으로 참조만 하면 됩니다
      - time\_parser 연산자는 원본 로그 시간을 유지하기 위해 Nginx의 time\_local 필드에서 타임스탬프를 추출합니다
      - 파이프라인은 기존 프로세서를 거쳐 수신기의 데이터를 ClickHouse exporter로 라우팅합니다
    </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가 읽을 수 있도록 Nginx 로그 디렉터리를 마운트합니다

    ##### 옵션 1: Docker Compose

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

    ```yaml theme={null}
    services:
      clickstack:
        # ... 기존 구성 ...
        environment:
          - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
          # ... 기타 환경 변수 ...
        volumes:
          - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
          - /var/log/nginx:/var/log/nginx: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)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v /var/log/nginx:/var/log/nginx:ro \
      clickhouse/clickstack-all-in-one:latest
    ```

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

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

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

    1. 검색 보기로 이동하세요
    2. `source`를 Logs로 설정하고 `request`, `request&#95;time`, `upstream&#95;response&#95;time` 등의 필드가 포함된 로그 항목이 표시되는지 확인하세요

    다음은 표시되어야 하는 화면의 예시입니다:

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-86180b7b/GdbFSEeOFE5jL52t/images/clickstack/nginx-logs-search-view.png?fit=max&auto=format&n=GdbFSEeOFE5jL52t&q=85&s=7cd09323a68598cbdd73dc48b04aa0e6" alt="로그 보기" width="3838" height="1938" data-path="images/clickstack/nginx-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-86180b7b/GdbFSEeOFE5jL52t/images/clickstack/log-view.png?fit=max&auto=format&n=GdbFSEeOFE5jL52t&q=85&s=8f3c19676e8f64dff30252bb141d8b79" alt="로그 보기" width="3838" height="1934" data-path="images/clickstack/log-view.png" />
  </Step>
</Steps>

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

프로덕션 시스템을 구성하기 전에 nginx 통합을 테스트하려는 사용자를 위해, 실제와 유사한 트래픽 패턴이 반영된 미리 생성된 nginx 액세스 로그 샘플 데이터세트를 제공합니다.

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

    ```bash theme={null}
    # 로그 다운로드
    curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
    ```

    데이터세트에는 다음이 포함됩니다:

    * 실제와 유사한 트래픽 패턴의 로그 항목
    * 다양한 엔드포인트와 HTTP 메서드
    * 성공 요청과 오류가 혼합된 데이터
    * 실제와 유사한 응답 시간과 바이트 수
  </Step>

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

    다음 내용으로 `nginx-demo.yaml` 파일을 생성하세요:

    ```yaml theme={null}
    cat > nginx-demo.yaml << 'EOF'
    receivers:
      filelog:
        include:
          - /tmp/nginx-demo/access.log
        start_at: beginning  # 데모 데이터는 처음부터 읽기
        operators:
          - type: json_parser
            parse_from: body
            parse_to: attributes
          - type: time_parser
            parse_from: attributes.time_local
            layout: '%d/%b/%Y:%H:%M:%S %z'
          - type: add
            field: attributes.source
            value: "nginx-demo"

    service:
      pipelines:
        logs/nginx-demo:
          receivers: [filelog]
          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)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
      -v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
      clickhouse/clickstack-all-in-one:latest
    ```
  </Step>

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

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

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

    검색 화면에는 다음과 같이 표시됩니다:

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

      HyperDX는 브라우저의 로컬 시간대를 기준으로 타임스탬프를 표시합니다. 데모 데이터는 UTC 기준 2025-10-20 11:00:00 - 2025-10-21 11:00:00 범위에 걸쳐 있습니다. 넓은 시간 범위를 지정하면 위치와 관계없이 데모 로그를 확인할 수 있습니다. 로그가 표시되면 더 명확하게 시각화할 수 있도록 범위를 24시간으로 좁힐 수 있습니다.
    </Info>

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-86180b7b/GdbFSEeOFE5jL52t/images/clickstack/nginx-logs-search-view.png?fit=max&auto=format&n=GdbFSEeOFE5jL52t&q=85&s=7cd09323a68598cbdd73dc48b04aa0e6" alt="Log view" width="3838" height="1938" data-path="images/clickstack/nginx-logs-search-view.png" />

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-86180b7b/GdbFSEeOFE5jL52t/images/clickstack/log-view.png?fit=max&auto=format&n=GdbFSEeOFE5jL52t&q=85&s=8f3c19676e8f64dff30252bb141d8b79" alt="Log view" width="3838" height="1934" data-path="images/clickstack/log-view.png" />
  </Step>
</Steps>

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

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

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

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

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-86180b7b/GdbFSEeOFE5jL52t/images/clickstack/import-dashboard.png?fit=max&auto=format&n=GdbFSEeOFE5jL52t&q=85&s=e8785b3f62e7b41a092bdb9099f3db32" alt="대시보드 가져오기" width="3024" height="556" data-path="images/clickstack/import-dashboard.png" />

    3. nginx-logs-dashboard.json 파일을 업로드한 다음 가져오기를 완료합니다.

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-86180b7b/GdbFSEeOFE5jL52t/images/clickstack/finish-nginx-logs-import.png?fit=max&auto=format&n=GdbFSEeOFE5jL52t&q=85&s=26ec96455338960a8804b3bacadfb2de" alt="가져오기 완료" width="3812" height="1906" data-path="images/clickstack/finish-nginx-logs-import.png" />
  </Step>

  <Step>
    #### 모든 시각화가 사전 구성된 상태로 대시보드가 생성됩니다

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

    <Image img="https://mintcdn.com/private-7c7dfe99-mintlify-86180b7b/GdbFSEeOFE5jL52t/images/clickstack/nginx-logs-dashboard.png?fit=max&auto=format&n=GdbFSEeOFE5jL52t&q=85&s=7053e876e9d3b1bd0deae4e0e8f70f18" alt="예시 대시보드" width="3812" height="1906" data-path="images/clickstack/nginx-logs-dashboard.png" />
  </Step>
</Steps>

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

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

* 환경 변수 CUSTOM\_OTELCOL\_CONFIG\_FILE이 올바르게 설정되어 있는지 확인하세요

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

* 사용자 지정 구성 파일이 /etc/otelcol-contrib/custom.config.yaml 경로에 마운트되었는지 확인하세요

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

* 사용자 지정 구성 내용을 확인하여 정상적으로 읽히는지 확인하십시오

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

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

* nginx가 JSON 형식으로 로그를 기록하고 있는지 확인하십시오

```bash theme={null}
tail -f /var/log/nginx/access.log
```

* collector가 로그를 읽을 수 있는지 확인하세요

```bash theme={null}
docker exec `<container>` cat /var/log/nginx/access.log
```

* 실제 적용된 구성에 filelog 수신기가 포함되어 있는지 확인하세요

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

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

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

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

* 중요한 메트릭(오류율, 지연 시간 임계값)에 대한 [알림](/ko/clickstack/features/alerts)을 설정하세요
* 특정 사용 사례(API 모니터링, 보안 이벤트)를 위한 추가 [대시보드](/ko/clickstack/features/dashboards/overview)를 만드세요

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

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