ClickStack를 사용한 Nginx 트레이스 모니터링

Nginx에 tracing을 추가하는 가장 쉬운 방법은 OpenTelemetry 지원이 기본으로 포함된 공식 Nginx image를 사용하는 것입니다.

nginx:otel image 사용

현재 사용 중인 Nginx image를 OpenTelemetry가 활성화된 버전으로 교체하십시오:

# docker-compose.yml 또는 Dockerfile에서
image: nginx:1.27-otel

이 image에는 ngx_otel_module.so가 미리 설치되어 있어 바로 사용할 수 있습니다.

nginx.conf 파일에 OpenTelemetry 구성을 추가하십시오. 이 구성은 module을 로드하고 트레이스를 ClickStack의 OTLP 엔드포인트로 보냅니다.

먼저 API Key를 가져오십시오:

1. ClickStack URL에서 HyperDX를 엽니다
2. 설정 → API Keys로 이동합니다
3. 수집 API Key를 복사합니다
4. 이를 환경 변수로 설정합니다: export CLICKSTACK_API_KEY=your-api-key-here

다음을 nginx.conf에 추가하십시오:

load_module modules/ngx_otel_module.so;

events {
    worker_connections 1024;
}

http {
    # OpenTelemetry exporter 구성
    otel_exporter {
        endpoint <clickstack-host>:4317;
        header authorization ${CLICKSTACK_API_KEY};
    }
    
    # 이 nginx 인스턴스를 식별하기 위한 서비스 이름
    otel_service_name "nginx-proxy";
    
    # tracing 활성화
    otel_trace on;
    
    server {
        listen 80;
        
        location / {
            # 이 location에 대해 tracing 활성화
            otel_trace_context propagate;
            otel_span_name "$request_method $uri";
            
            # 트레이스에 요청 세부 정보 추가
            otel_span_attr http.status_code $status;
            otel_span_attr http.request.method $request_method;
            otel_span_attr http.route $uri;
            
            # 기존 프록시 또는 애플리케이션 구성
            proxy_pass http://your-backend;
        }
    }
}

Docker에서 Nginx를 실행하는 경우 환경 변수를 컨테이너에 전달하십시오:

services:
  nginx:
    image: nginx:1.27-otel
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

<clickstack-host>를 ClickStack 인스턴스의 호스트명 또는 IP 주소로 바꾸십시오.

구성 이해하기

추적되는 항목: Nginx로 들어오는 각 요청은 다음 정보를 보여주는 트레이스 스팬을 생성합니다:

• 요청 메서드와 경로
• HTTP 상태 코드
• 요청 소요 시간
• 타임스탬프

스팬 속성: otel_span_attr 지시어는 각 트레이스에 메타데이터를 추가하므로, HyperDX에서 상태 코드, 메서드, route 등을 기준으로 요청을 필터링하고 분석할 수 있습니다.

이 변경을 적용한 후 Nginx 구성을 테스트하십시오:

nginx -t

테스트가 통과하면 Nginx를 다시 로드하십시오:

# Docker의 경우
docker-compose restart nginx

# systemd의 경우
sudo systemctl reload nginx

구성이 완료되면 HyperDX에 로그인하여 트레이스가 정상적으로 수집되는지 확인하십시오. 다음과 비슷한 화면이 표시되어야 합니다. 트레이스가 보이지 않으면 시간 범위를 조정해 보십시오:

아직 ClickStack을 실행하지 않았다면 다음과 같이 시작하세요:

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest

계속하기 전에 ClickStack이 완전히 초기화될 때까지 약 30초 정도 기다리세요.

• 포트 8080: HyperDX 웹 인터페이스
• 포트 4317: OTLP gRPC 엔드포인트 (nginx 모듈에서 사용)
• 포트 4318: OTLP HTTP 엔드포인트 (데모 트레이스에서 사용)

샘플 트레이스 파일을 다운로드하고 timestamp를 현재 시각으로 업데이트하세요:

# 트레이스 다운로드
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json

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

• 실제와 유사한 타이밍의 트레이스 스팬 1,000개
• 다양한 트래픽 패턴을 가진 9개의 endpoint
• 약 93%의 성공률(200), 약 3%의 클라이언트 오류(404), 약 4%의 서버 오류(500)
• 10ms~800ms 범위의 지연 시간
• 기존 트래픽 패턴을 유지한 채 현재 시각으로 이동한 데이터

API Key를 환경 변수로 설정하세요(아직 설정하지 않았다면):

export CLICKSTACK_API_KEY=your-api-key-here

API Key 가져오기:

1. ClickStack URL에서 HyperDX를 엽니다
2. 설정 → API Keys로 이동합니다
3. 수집 API Key를 복사합니다

그런 다음 트레이스를 ClickStack으로 전송합니다:

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nginx-traces-sample.json

트레이스가 성공적으로 전송되었음을 나타내는 {"partialSuccess":{}}와 같은 응답이 표시되어야 합니다. 1,000개의 트레이스가 모두 ClickStack으로 수집됩니다.

1. HyperDX를 열고 계정에 로그인합니다(먼저 계정을 만들어야 할 수도 있습니다)
2. 검색 보기로 이동한 다음 source를 Traces로 설정합니다
3. 시간 범위를 2025-10-25 13:00:00 - 2025-10-28 13:00:00으로 설정합니다

검색 보기에는 다음과 같이 표시됩니다:

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

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

3. nginx-trace-dashboard.json 파일을 업로드한 다음 "Finish Import"를 클릭합니다.