요약OTel filelog 수신기를 사용해 ClickStack에서 Kafka 브로커 로그(Log4j 포맷)를 수집하고 시각화합니다. 데모 데이터세트와 사전 구축된 대시보드가 제공됩니다.
- 실행 중인 ClickStack 인스턴스
- 기존 Kafka 설치(버전 2.0 이상)
- Kafka 로그 파일(
server.log, controller.log 등)에 대한 접근 권한
Kafka 로깅 구성 확인
Kafka는 Log4j를 사용하며, kafka.logs.dir 시스템 속성 또는 LOG_DIR 환경 변수로 지정된 디렉터리에 로그를 씁니다. 로그 파일 위치를 확인하십시오:# 기본 위치
ls $KAFKA_HOME/logs/ # 표준 Apache Kafka (기본값: <install-dir>/logs/)
ls /var/log/kafka/ # RPM/DEB 패키지 설치
server.log: 일반 브로커 로그(시작, 연결, 복제, 오류)controller.log: 컨트롤러 관련 이벤트(리더 선출, 파티션 재할당)state-change.log: 파티션 및 레플리카 상태 전환
Kafka의 기본 Log4j 패턴은 다음과 같은 행을 생성합니다:[2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)
Docker 기반 Kafka 배포(예: confluentinc/cp-kafka)에서는 기본 Log4j 구성에 콘솔 appender만 포함되어 있으며 file appender는 없으므로 logs는 stdout에만 기록됩니다. filelog 수신기를 사용하려면 log4j.properties에 file appender를 추가하거나 stdout을 파이프로 전달하는 방식(예: | tee /var/log/kafka/server.log)으로 logs를 파일로 리디렉션해야 합니다.
Kafka용 사용자 지정 OTel collector 구성 만들기
ClickStack에서는 사용자 지정 설정 파일을 마운트하고 환경 변수를 설정해 기본 OpenTelemetry Collector 구성을 확장할 수 있습니다. 사용자 지정 구성은 OpAMP를 통해 HyperDX가 관리하는 기본 구성과 머지됩니다.다음 내용으로 kafka-logs-monitoring.yaml 파일을 만드세요:receivers:
filelog/kafka:
include:
- /var/log/kafka/server.log
- /var/log/kafka/controller.log # 선택 사항, log4j가 별도의 파일 어펜더로 구성된 경우에만 존재
- /var/log/kafka/state-change.log # 선택 사항, 위와 동일
start_at: beginning
multiline:
line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
operators:
- type: regex_parser
regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
parse_from: body
parse_to: attributes
timestamp:
parse_from: attributes.timestamp
layout: '%Y-%m-%d %H:%M:%S,%L'
severity:
parse_from: attributes.severity
- type: move
from: attributes.message
to: body
- type: add
field: attributes.source
value: "kafka"
- type: add
field: resource["service.name"]
value: "kafka-production"
service:
pipelines:
logs/kafka:
receivers: [filelog/kafka]
processors:
- memory_limiter
- transform
- batch
exporters:
- clickhouse
- 사용자 지정 구성에서는 새 수신기와 파이프라인만 정의합니다. 프로세서(
memory_limiter, transform, batch)와 익스포터(clickhouse)는 기본 ClickStack 구성에 이미 정의되어 있으므로 이름만 참조하면 됩니다.
multiline 구성은 스택 트레이스가 하나의 로그 항목으로 수집되도록 합니다.- 이 구성은 collector가 시작될 때 기존 로그를 모두 읽도록
start_at: beginning을 사용합니다. 운영 환경에 배포할 때는 collector가 다시 시작될 때 로그를 다시 수집하지 않도록 start_at: end로 변경하십시오.
사용자 지정 구성을 로드하도록 ClickStack 구성하기
기존 ClickStack 배포에서 사용자 지정 collector 구성을 활성화하려면 다음을 수행해야 합니다.
- 사용자 지정 구성 파일을
/etc/otelcol-contrib/custom.config.yaml에 마운트합니다.
- 환경 변수
CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml를 설정합니다.
- collector가 Kafka 로그를 읽을 수 있도록 Kafka 로그 디렉터리를 마운트합니다.
ClickStack 배포 구성을 업데이트합니다.services:
clickstack:
# ... 기존 구성 ...
environment:
- CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
# ... 기타 환경 변수 ...
volumes:
- ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
- /var/log/kafka:/var/log/kafka:ro
# ... 기타 볼륨 ...
docker에서 All-in-One image를 사용하는 경우 다음을 실행합니다.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)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
-v /var/log/kafka:/var/log/kafka:ro \
clickhouse/clickstack-all-in-one:latest
ClickStack collector에 Kafka 로그 파일을 읽을 수 있는 적절한 권한이 있는지 확인하십시오. 운영 환경에서는 읽기 전용 마운트(:ro)를 사용하고 최소 권한 원칙을 따르십시오.
HyperDX에서 로그 확인
구성이 완료되면 HyperDX에 로그인하여 로그가 정상적으로 유입되는지 확인합니다:샘플 데이터세트 다운로드
샘플 로그 파일을 다운로드합니다:curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/server.log
테스트 collector 구성 생성
다음 구성으로 kafka-logs-demo.yaml 파일을 생성합니다:cat > kafka-logs-demo.yaml << 'EOF'
receivers:
filelog/kafka:
include:
- /tmp/kafka-demo/server.log
start_at: beginning
multiline:
line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
operators:
- type: regex_parser
regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
parse_from: body
parse_to: attributes
timestamp:
parse_from: attributes.timestamp
layout: '%Y-%m-%d %H:%M:%S,%L'
severity:
parse_from: attributes.severity
- type: move
from: attributes.message
to: body
- type: add
field: attributes.source
value: "kafka-demo"
- type: add
field: resource["service.name"]
value: "kafka-demo"
service:
pipelines:
logs/kafka-demo:
receivers: [filelog/kafka]
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)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
-v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
clickhouse/clickstack-all-in-one:latest
HyperDX에서 로그 확인
ClickStack이 실행되면 다음을 수행합니다:
- HyperDX를 열고 계정에 로그인합니다(먼저 계정을 생성해야 할 수 있습니다)
- Search 보기로 이동한 다음 source를
Logs로 설정합니다
- 시간 범위에 **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**가 포함되도록 설정합니다
사전 구축된 대시보드 가져오기
- HyperDX를 열고 대시보드 섹션으로 이동합니다.
- 오른쪽 상단의 점 3개 메뉴에서 “Import Dashboard”를 클릭합니다.
- kafka-logs-dashboard.json 파일을 업로드한 다음 “Finish Import”를 클릭합니다.
모든 시각화가 사전 구성된 상태로 대시보드가 생성됩니다
데모 데이터세트를 사용하는 경우 시간 범위를 **2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC)**를 포함하도록 설정합니다.docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog
docker exec <container> cat /etc/otel/supervisor-data/agent.log
tail -1 /var/log/kafka/server.log
regex_parser 정규식을 조정하세요.
- 중요한 이벤트(브로커 장애, 복제 오류, consumer group 관련 문제)에 대한 알림을 설정합니다
- 보다 포괄적인 Kafka 모니터링을 위해 Kafka 메트릭과 함께 사용합니다
- 특정 사용 사례(컨트롤러 이벤트, 파티션 재할당)를 위한 추가 대시보드를 생성합니다
이 가이드는 빠르게 설정할 수 있도록 ClickStack에 내장된 OpenTelemetry Collector를 기반으로 작성되었습니다. 프로덕션 배포에서는 자체 OTel Collector를 실행하고 데이터를 ClickStack의 OTLP 엔드포인트로 전송하는 방식을 권장합니다. 프로덕션용 구성은 OpenTelemetry 데이터 전송을 참조하십시오.
