ClickStack으로 Nginx 로그 모니터링

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

사용자 지정 구성을 로드하도록 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

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으로 설정하세요

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

대시보드 및 시각화

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

대시보드 구성 다운로드

대시보드 구성 파일 다운로드.

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

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

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

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

문제 해결

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

환경 변수 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 데이터 전송을 참조하십시오.