요약OTel
filelog 수신기를 사용해 ClickStack에서 Nginx 액세스 로그(JSON 포맷)를 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 포함됩니다.기존 Nginx 통합
사전 준비 사항
- 실행 중인 ClickStack 인스턴스
- 기존에 설치된 Nginx
- Nginx 설정 파일을 수정할 수 있는 권한
1
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 블록에 추가하세요:2
사용자 지정 OTel collector 구성 만들기
ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정해 기본 OpenTelemetry Collector 구성을 확장할 수 있습니다. 사용자 지정 구성은 OpAMP를 통해 HyperDX가 관리하는 기본 구성과 머지됩니다.다음 구성으로 nginx-monitoring.yaml 파일을 만드세요:- 표준 위치에서 Nginx 로그를 읽습니다
- JSON 로그 항목을 파싱합니다
- 원본 로그 타임스탬프를 추출하여 유지합니다
- HyperDX에서 필터링할 수 있도록 source: Nginx 속성을 추가합니다
- 전용 파이프라인을 통해 로그를 ClickHouse exporter로 라우팅합니다
- 사용자 지정 구성에서는 새 수신기와 파이프라인만 정의합니다
- 프로세서(memory_limiter, transform, batch)와 exporter(clickhouse)는 기본 ClickStack 구성에 이미 정의되어 있으므로 이름으로 참조만 하면 됩니다
- time_parser 연산자는 원본 로그 시간을 유지하기 위해 Nginx의 time_local 필드에서 타임스탬프를 추출합니다
- 파이프라인은 기존 프로세서를 거쳐 수신기의 데이터를 ClickHouse exporter로 라우팅합니다
3
사용자 지정 구성을 로드하도록 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 배포 구성을 업데이트합니다:옵션 2: Docker Run (올인원 이미지)
docker run 명령으로 올인원 이미지를 사용하는 경우:ClickStack collector에 nginx 로그 파일을 읽는 데 필요한 적절한 권한이 있는지 확인하십시오. production 환경에서는 읽기 전용 마운트(:ro)를 사용하고 최소 권한 원칙을 따르십시오.
4
HyperDX에서 로그 확인하기
구성이 완료되면 HyperDX에 로그인한 다음 로그가 정상적으로 유입되는지 확인하세요:- 검색 보기로 이동하세요
source를 Logs로 설정하고request,request_time,upstream_response_time등의 필드가 포함된 로그 항목이 표시되는지 확인하세요
데모 데이터세트
1
샘플 데이터세트 다운로드
- 실제와 유사한 트래픽 패턴의 로그 항목
- 다양한 엔드포인트와 HTTP 메서드
- 성공 요청과 오류가 혼합된 데이터
- 실제와 유사한 응답 시간과 바이트 수
2
3
4
HyperDX에서 로그 확인
ClickStack이 실행되면 다음을 수행하세요:- HyperDX를 열고 계정에 로그인하세요(먼저 계정을 만들어야 할 수 있습니다)
- 검색 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시간으로 좁힐 수 있습니다.
대시보드 및 시각화
1
대시보드 구성 파일
2
사전 구축된 대시보드 가져오기
- HyperDX를 열고 Dashboards 섹션으로 이동합니다.
- 오른쪽 상단의 줄임표 메뉴에서 “Import Dashboard”를 클릭합니다.
- nginx-logs-dashboard.json 파일을 업로드한 다음 가져오기를 완료합니다.
3
모든 시각화가 사전 구성된 상태로 대시보드가 생성됩니다
데모 데이터세트를 사용하는 경우 시간 범위를 **2025-10-20 11:00:00 - 2025-10-21 11:00:00 (UTC)**로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되지 않습니다.
문제 해결
사용자 지정 구성이 로드되지 않는 경우
- 환경 변수 CUSTOM_OTELCOL_CONFIG_FILE이 올바르게 설정되어 있는지 확인하세요
- 사용자 지정 구성 파일이 /etc/otelcol-contrib/custom.config.yaml 경로에 마운트되었는지 확인하세요
- 사용자 지정 구성 내용을 확인하여 정상적으로 읽히는지 확인하십시오
HyperDX에 로그가 표시되지 않는 경우
- nginx가 JSON 형식으로 로그를 기록하고 있는지 확인하십시오
- collector가 로그를 읽을 수 있는지 확인하세요
- 실제 적용된 구성에 filelog 수신기가 포함되어 있는지 확인하세요
- collector 로그에 오류가 있는지 확인하세요