메인 콘텐츠로 건너뛰기
요약OTel JMX Metric Gatherer를 사용해 ClickStack에서 Apache Kafka 성능 메트릭을 모니터링합니다. 데모 데이터셋과 사전 구축된 대시보드가 포함되어 있습니다.

​
기존 Kafka 배포와 통합

기존 Kafka 배포를 모니터링하려면 OpenTelemetry JMX Metric Gatherer 컨테이너를 실행하여 메트릭을 수집하고 OTLP를 통해 ClickStack으로 전송하십시오. 기존 설정을 수정하지 않고 먼저 이 통합을 테스트하려면 데모 데이터셋 섹션으로 건너뛰십시오.
사전 요구 사항
  • 실행 중인 ClickStack 인스턴스
  • JMX가 활성화된 기존 Kafka 설치(버전 2.0 이상)
  • ClickStack과 Kafka 간 네트워크 연결(JMX 포트 9999, Kafka 포트 9092)
  • OpenTelemetry JMX Metric Gatherer JAR(다운로드 방법은 아래 참조)
1

​
ClickStack API Key 가져오기

JMX Metric Gatherer는 데이터를 ClickStack의 OTLP 엔드포인트로 전송하며, 이 엔드포인트에는 인증이 필요합니다.
  1. ClickStack URL에서 HyperDX를 여세요(예: http://localhost:8080)
  2. 필요한 경우 계정을 만들거나 로그인하세요
  3. Team Settings → API Keys로 이동하세요
  4. 수집 API Key를 복사하세요
  1. 환경 변수로 설정하세요:
export CLICKSTACK_API_KEY=your-api-key-here
2

​
OpenTelemetry JMX Metric Gatherer 다운로드

JMX Metric Gatherer JAR 파일을 다운로드합니다:
curl -L -o opentelemetry-jmx-metrics.jar \
  https://github.com/open-telemetry/opentelemetry-java-contrib/releases/download/v1.32.0/opentelemetry-jmx-metrics.jar
3

​
Kafka JMX 활성화 여부 확인

Kafka 브로커에서 JMX가 활성화되어 있는지 확인하십시오. Docker 배포의 경우:
services:
  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      # ... 기타 Kafka 구성
    ports:
      - "9092:9092"
      - "9999:9999"
Docker를 사용하지 않는 배포 환경에서는 Kafka 시작 시 다음 설정을 적용하십시오:
export JMX_PORT=9999
JMX에 접근 가능한지 확인하십시오:
netstat -an | grep 9999
4

​
Docker Compose로 JMX Metric Gatherer 배포

이 예시는 Kafka, JMX Metric Gatherer, ClickStack를 포함한 전체 구성을 보여줍니다. 기존 배포 환경에 맞게 서비스 이름과 endpoint를 조정하십시오:
services:
  clickstack:
    image: clickhouse/clickstack-all-in-one:latest
    ports:
      - "8080:8080"
      - "4317:4317"
      - "4318:4318"
    networks:
      - monitoring

  kafka:
    image: confluentinc/cp-kafka:latest
    hostname: kafka
    container_name: kafka
    environment:
      KAFKA_NODE_ID: 1
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT'
      KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:9092'
      KAFKA_PROCESS_ROLES: 'broker,controller'
      KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
      KAFKA_LISTENERS: 'PLAINTEXT://kafka:9092,CONTROLLER://kafka:29093'
      KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
      KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
      CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      KAFKA_JMX_OPTS: '-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=kafka -Dcom.sun.management.jmxremote.rmi.port=9999'
    ports:
      - "9092:9092"
      - "9999:9999"
    networks:
      - monitoring

  kafka-jmx-exporter:
    image: eclipse-temurin:11-jre
    depends_on:
      - kafka
      - clickstack
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./opentelemetry-jmx-metrics.jar:/app/opentelemetry-jmx-metrics.jar
    command: >
      sh -c "java
      -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi
      -Dotel.jmx.target.system=kafka
      -Dotel.metrics.exporter=otlp
      -Dotel.exporter.otlp.protocol=http/protobuf
      -Dotel.exporter.otlp.endpoint=http://clickstack:4318
      -Dotel.exporter.otlp.headers=authorization=\${CLICKSTACK_API_KEY}
      -Dotel.resource.attributes=service.name=kafka,kafka.broker.id=broker-0
      -Dotel.jmx.interval.milliseconds=10000
      -jar /app/opentelemetry-jmx-metrics.jar"
    networks:
      - monitoring

networks:
  monitoring:
    driver: bridge
주요 구성 매개변수:
  • service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi - JMX 연결 URL(사용 중인 Kafka 호스트명을 사용하세요)
  • otel.jmx.target.system=kafka - Kafka 전용 메트릭을 활성화합니다
  • http://clickstack:4318 - OTLP HTTP 엔드포인트(사용 중인 ClickStack 호스트명을 사용하세요)
  • authorization=\${CLICKSTACK_API_KEY} - 인증에 사용할 API Key(필수)
  • service.name=kafka,kafka.broker.id=broker-0 - 필터링에 사용할 리소스 속성
  • 10000 - 밀리초 단위 수집 인터벌(10초)
5

​
HyperDX에서 메트릭 확인

HyperDX에 로그인하고 메트릭이 수집되고 있는지 확인합니다:
  1. Chart Explorer로 이동합니다
  2. kafka.message.count 또는 kafka.partition.count를 검색합니다
  3. 메트릭이 10초 간격으로 표시되어야 합니다
확인할 주요 메트릭:
  • kafka.message.count - 처리된 총 메시지 수
  • kafka.partition.count - 총 파티션 수
  • kafka.partition.under_replicated - 클러스터가 정상 상태라면 0이어야 합니다
  • kafka.network.io - 네트워크 처리량
  • kafka.request.time.* - 요청 지연 시간 백분위수
활동을 생성하여 더 많은 메트릭이 표시되도록 하려면:
# 테스트 토픽 생성
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# 테스트 메시지 전송
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"
Kafka 컨테이너 내부에서 Kafka 클라이언트 명령(kafka-topics, kafka-console-producer 등)을 실행할 때는 JMX 포트 충돌을 방지하기 위해 명령 앞에 unset JMX_PORT &&를 추가하십시오.

​
데모 데이터셋

프로덕션 시스템을 구성하기 전에 Kafka 메트릭 통합을 테스트하려는 사용자를 위해, 실제와 유사한 Kafka 메트릭 패턴이 반영된 사전 생성 데이터셋을 제공합니다.
1

​
샘플 메트릭 데이터셋 다운로드

사전 생성된 메트릭 파일을 다운로드하세요(실제와 유사한 패턴이 반영된 29시간 분량의 Kafka 메트릭).
# 게이지 메트릭 다운로드(파티션 수, 큐 크기, 지연 시간, consumer lag)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-gauge.csv

# 합계 메트릭 다운로드(메시지 속도, 바이트 속도, 요청 수)
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-sum.csv
이 데이터셋에는 단일 broker 전자상거래 Kafka 클러스터의 현실적인 패턴이 포함되어 있습니다.
  • 06:00-08:00: 아침 시간대 급증 - 야간 기준치에서 트래픽이 급격히 증가
  • 10:00-10:15: 플래시 세일 - 평소 트래픽의 3.5배까지 급증
  • 11:30: 배포 이벤트 - 복제가 부족한 파티션과 함께 consumer lag가 12배 급증
  • 14:00-15:30: 쇼핑 피크 시간대 - 기준치의 2.8배 수준의 높은 트래픽이 지속
  • 17:00-17:30: 퇴근 후 급증 - 두 번째 트래픽 피크
  • 18:45: consumer 리밸런싱 - 리밸런싱 중 lag가 6배 급증
  • 20:00-22:00: 저녁 시간대 감소 - 야간 수준으로 급격히 감소
2

​
ClickStack 시작

ClickStack 인스턴스를 시작하세요.
docker run -d --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  clickhouse/clickstack-all-in-one:latest
3

​
ClickStack에 메트릭 로드

메트릭을 ClickHouse에 직접 로드하세요.
# 게이지 메트릭 로드(파티션 수, 큐 크기, 지연 시간, consumer lag)
cat kafka-metrics-gauge.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"

# 합계 메트릭 로드(메시지 속도, 바이트 속도, 요청 수)
cat kafka-metrics-sum.csv | docker exec -i clickstack-demo \
  clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"
4

​
HyperDX에서 메트릭 확인

로드가 완료되면 메트릭을 가장 빠르게 확인하는 방법은 사전 구축된 대시보드를 사용하는 것입니다.Dashboards and visualization 섹션으로 이동하여 대시보드를 가져오고 모든 Kafka 메트릭을 한 번에 확인하세요.
시간대 표시HyperDX는 브라우저의 로컬 시간대로 timestamp를 표시합니다. 데모 데이터는 2025-11-05 16:00:00 - 2025-11-06 16:00:00 (UTC) 기간에 걸쳐 있습니다. 위치와 관계없이 데모 메트릭이 표시되도록 시간 범위를 2025-11-04 16:00:00 - 2025-11-07 16:00:00로 설정하세요. 메트릭이 표시되면 더 명확하게 시각화할 수 있도록 범위를 24시간으로 좁힐 수 있습니다.

​
대시보드 및 시각화

ClickStack을 사용해 Kafka 모니터링을 빠르게 시작할 수 있도록 Kafka 메트릭에 대한 핵심 시각화를 제공합니다.
1

​
대시보드 구성 파일

2

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

  1. HyperDX를 열고 Dashboards 섹션으로 이동합니다
  2. 오른쪽 상단의 점 3개 메뉴에서 Import Dashboard를 클릭합니다
  1. kafka-metrics-dashboard.json 파일을 업로드한 다음 Finish Import를 클릭합니다
3

​
대시보드 보기

모든 시각화가 미리 구성된 상태로 대시보드가 생성됩니다.
데모 데이터셋의 경우 시간 범위를 **2025-11-05 16:00:00 - 2025-11-06 16:00:00 (UTC)**로 설정하십시오(로컬 시간대에 맞게 조정). 가져온 대시보드에는 기본적으로 시간 범위가 지정되어 있지 않습니다.

​
문제 해결

​
HyperDX에 메트릭이 표시되지 않는 경우

API Key가 설정되어 컨테이너에 전달되는지 확인하세요: 
# 환경 변수 확인
echo $CLICKSTACK_API_KEY

# 컨테이너 내 환경 변수 확인
docker exec <jmx-exporter-container> env | grep CLICKSTACK_API_KEY
없으면 설정한 후 다시 시작하세요: 
export CLICKSTACK_API_KEY=your-api-key-here
docker compose up -d kafka-jmx-exporter
메트릭이 ClickHouse로 전달되고 있는지 확인하세요: 
docker exec <clickstack-container> clickhouse-client --query "
SELECT DISTINCT MetricName 
FROM otel_metrics_sum 
WHERE ServiceName = 'kafka' 
LIMIT 10
"
결과가 보이지 않으면 JMX exporter 로그를 확인하세요: 
docker compose logs kafka-jmx-exporter | grep -i "error\|connection" | tail -10
메트릭을 채우기 위해 Kafka 트래픽을 발생시킵니다: 
# 테스트 토픽 생성
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# 테스트 메시지 전송
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

​
인증 오류

Authorization failed 또는 401 Unauthorized가 표시되면:
  1. HyperDX UI에서 API Key를 확인하세요 (설정 → API Keys → 수집 API key)
  2. 다시 export하고 재시작하세요:
export CLICKSTACK_API_KEY=your-correct-api-key
docker compose down
docker compose up -d

​
Kafka 클라이언트 명령 실행 시 포트 충돌

Kafka 컨테이너 내부에서 Kafka 명령을 실행할 때 다음과 같은 메시지가 표시될 수 있습니다: 
Error: Port already in use: 9999
명령어 앞에 unset JMX_PORT &&를 붙이십시오: 
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --list --bootstrap-server kafka:9092"

​
네트워크 연결 문제

JMX exporter 로그에 Connection refused가 표시되면 다음 사항을 확인하십시오. 모든 컨테이너가 동일한 Docker 네트워크에 연결되어 있는지 확인하십시오. 
docker compose ps
docker network inspect <network-name>
연결을 테스트하세요: 
# JMX exporter에서 ClickStack으로
docker exec <jmx-exporter-container> sh -c "timeout 2 bash -c 'cat < /dev/null > /dev/tcp/clickstack/4318' && echo 'Connected' || echo 'Failed'"

​
다음 단계

  • 중요한 메트릭(과소 복제된 파티션, consumer lag 증가, 요청 지연 시간 급증)에 대한 알림을 설정하세요
  • 특정 사용 사례에 맞는 추가 대시보드(토픽별 처리량, consumer group 모니터링)를 만드세요
  • 고유한 kafka.broker.id resource 속성을 사용해 추가 JMX Metric Gatherer 인스턴스를 배포하여 여러 Kafka broker를 모니터링하세요

​
프로덕션 환경으로 전환

이 가이드는 메트릭을 JMX Metric Gatherer에서 ClickStack의 OTLP 엔드포인트로 직접 전송하며, 테스트 및 소규모 배포에는 적합합니다. 프로덕션 환경에서는 자체 OpenTelemetry Collector를 agent로 배포하여 JMX Exporter에서 메트릭을 수신하고 ClickStack으로 전달하세요. 이를 통해 배칭, 복원력, 중앙 집중식 구성 관리의 이점을 얻을 수 있습니다. 프로덕션 배포 패턴과 collector 구성 예시는 OpenTelemetry로 수집하기를 참조하십시오.
마지막 수정일 2026년 6월 10일