ClickStack으로 Nginx 로그 모니터링

요약OTel filelog 수신기를 사용해 ClickStack에서 Nginx 액세스 로그(JSON 포맷)를 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함됩니다.

기존 Nginx 통합

이 섹션에서는 ClickStack OTel collector 구성을 수정해 기존 Nginx 설치에서 로그를 ClickStack으로 전송하도록 설정하는 방법을 설명합니다. 기존 환경을 직접 구성하기 전에 통합을 테스트하려면, 다음 섹션에서 미리 구성된 환경과 샘플 데이터로 테스트할 수 있습니다.

사전 준비 사항

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

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 블록에 추가하세요:

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를 다시 로드하세요.

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

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

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로 라우팅합니다

사용자 지정 구성에서는 새 수신기와 파이프라인만 정의합니다
프로세서(memory_limiter, transform, batch)와 exporter(clickhouse)는 기본 ClickStack 구성에 이미 정의되어 있으므로 이름으로 참조만 하면 됩니다
time_parser 연산자는 원본 로그 시간을 유지하기 위해 Nginx의 time_local 필드에서 타임스탬프를 추출합니다
파이프라인은 기존 프로세서를 거쳐 수신기의 데이터를 ClickHouse exporter로 라우팅합니다

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

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

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

옵션 1: Docker Compose

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

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

옵션 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)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  clickhouse/clickstack-all-in-one:latest

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

HyperDX에서 로그 확인하기

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

검색 보기로 이동하세요
source를 Logs로 설정하고 request, request_time, upstream_response_time 등의 필드가 포함된 로그 항목이 표시되는지 확인하세요

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

데모 데이터세트

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

샘플 데이터세트 다운로드

# 로그 다운로드
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

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

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

테스트용 collector 구성 생성

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

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

데모 구성으로 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)/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

HyperDX에서 로그 확인

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

HyperDX를 열고 계정에 로그인하세요(먼저 계정을 만들어야 할 수 있습니다)
Search view로 이동한 다음 소스를 Logs로 설정하세요
시간 범위를 2025-10-19 11:00:00 - 2025-10-22 11:00:00으로 설정하세요

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

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

대시보드 및 시각화

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

대시보드 구성 다운로드

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

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

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

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

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

문제 해결

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

환경 변수 CUSTOM_OTELCOL_CONFIG_FILE이 올바르게 설정되어 있는지 확인하세요

docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE

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

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

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

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

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

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

tail -f /var/log/nginx/access.log

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

docker exec `<container>` cat /var/log/nginx/access.log

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

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

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

docker exec `<container>` cat /etc/otel/supervisor-data/agent.log

다음 단계

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

운영 환경으로 전환하기

이 가이드는 빠르게 설정할 수 있도록 ClickStack에 내장된 OpenTelemetry Collector를 활용합니다. 운영 환경에 배포하는 경우 자체 OTel Collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 전송하는 것을 권장합니다. 운영 환경 구성은 OpenTelemetry 데이터 전송을 참조하십시오.

시작하기

기능

ClickStack 관리

가이드

통합 파트너

ClickStack으로 Nginx 로그 모니터링

기존 Nginx 통합

사전 준비 사항

옵션 1: Docker Compose

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

데모 데이터세트

대시보드 및 시각화

문제 해결

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

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

다음 단계

운영 환경으로 전환하기

​기존 Nginx 통합

사전 준비 사항

옵션 1: Docker Compose

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

​데모 데이터세트

​대시보드 및 시각화

​문제 해결

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

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

​다음 단계

​운영 환경으로 전환하기

기존 Nginx 통합

데모 데이터세트

대시보드 및 시각화

문제 해결

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

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

다음 단계

운영 환경으로 전환하기