카프카 모니터링과 운영 완벽 가이드

Apache Kafka의 모니터링과 운영 실무를 다룹니다. JMX 메트릭부터 Prometheus+Grafana, 컨슈머 랙 알림, 로그 관리, 매니지먼트 도구까지 카프카를 안정적으로 운영하는 데 필요한 모든 것을 배웁니다.

---

목차

1. JMX_메트릭_수집
2. Prometheus_그라파나_모니터링
3. 브로커_상태_점검_항목
4. 컨슈머_랙_알림_설정
5. 로그_관리와_트러블슈팅
6. 카프카_매니지먼트_도구_소개

---

1. JMX 메트릭 수집

어느 날 김개발 씨가 출근하자마자 장애 알림을 받았습니다. "카프카 브로커가 응답하지 않는다"는 메시지였습니다.

하지만 정작 어디서부터 조사해야 할지 막막했습니다. 박시니어 씨가 다가와 말했습니다.

"먼저 브로커의 JMX 메트릭을 확인해 봐야죠."

**JMX(Java Management Extensions)**는 카프카 브로커의 내부 상태를 모니터링하기 위한 표준 기술입니다. 마치 자동차의 계기판이 속도와 연료량을 보여주듯, JMX는 브로커의 CPU, 메모리, 네트워크, 디스크 I/O 등 핵심 지표를 실시간으로 제공합니다.

다음 코드를 살펴봅시다.

# server.properties에 JMX 활성화 설정
# 브로커 시작 시 JMX 포트를 지정합니다
KAFKA_JMX_PORT=9999
KAFKA_JMX_HOSTNAME=localhost
bin/kafka-server-start.sh config/server.properties

# JConsole으로 메트릭 확인
# kafka.server:type=BrokerTopicMetrics
# BytesInPerSec - 초당 수신 바이트 수
# BytesOutPerSec - 초당 송신 바이트 수
# MessagesInPerSec - 초당 수신 메시지 수

# jconsole 명령어로 접속
jconsole localhost:9999

"Apache Kafka 완전 정복" 코스의 14번째 카드뉴스에 오신 여러분을 환영합니다. 지난 13화에서는 카프카 보안 설정에 대해 학습했습니다.

SASL 인증부터 SSL/TLS 암호화, ACL 인가까지 카프카를 안전하게 보호하는 방법을 배웠죠. 이번에는 보안으로 지킨 카프카를 어떻게 모니터링하고 안정적으로 운영하는지 알아보겠습니다.

김개발 씨는 입사 6개월 차 개발자입니다. 최근 팀에서 카프카를 도입했고, 김개발 씨가 운영을 담당하게 되었습니다.

하지만 막상 카프카가 잘 돌아가고 있는지 확인할 방법을 몰랐습니다. 그냥 "돌아가고 있겠지"라고 믿고 있었죠.

그날 장애가 발생했습니다. 프로듀서가 메시지를 보내지 못하고, 컨슈머는 데이터를 소비하지 못했습니다.

김개발 씨는 당황해서 브로커를 재시작하기만 했지만, 근본 원인을 알 수 없었습니다. 박시니어 씨가 와서 말했습니다.

"이럴 때 필요한 게 JMX예요. 카프카는 JVM 위에서 돌아가니까, JVM이 제공하는 모니터링 기능을 그대로 쓸 수 있어요." 그렇다면 JMX란 정확히 무엇일까요?

쉽게 비유하자면, JMX는 마치 자동차 계기판과 같습니다. 계기판이 없으면 운전자는 속도가 얼마인지, 연료가 얼마나 남았는지 알 수 없죠.

JMX는 브로커의 상태를 이렇게 세밀하게 보여줍니다. JMX가 없던 시절에는 어떻게 했을까요?

개발자들은 로그 파일을 직접 열어보거나, 운영체제의 top, vmstat 같은 명령어로 간접적으로 상태를 파악해야 했습니다. 하지만 이건 브로커 내부의 카프카 전용 메트릭까지는 볼 수 없었습니다.

JMX를 활성화하는 방법은 아주 간단합니다. KAFKA_JMX_PORT 환경 변수만 설정하면 됩니다.

기본적으로 9999번 포트를 많이 사용합니다. 브로커를 시작할 때 이 환경 변수를 함께 전달하면, JMX가 활성화된 상태로 브로커가 실행됩니다.

활성화 후에는 JConsole이나 VisualVM 같은 도구로 접속할 수 있습니다. JConsole은 JDK에 기본으로 포함된 도구라서 별도 설치가 필요 없습니다.

접속하면 카프카의 MBean 트리를 탐색하면서 수많은 메트릭을 확인할 수 있습니다. 가장 중요한 메트릭은 무엇일까요?

kafka.server:type=BrokerTopicMetrics 아래의 BytesInPerSec(초당 수신 바이트)와 BytesOutPerSec(초당 송신 바이트)를 꼭 확인하세요. 이 두 지표가 브로커의 처리량을 보여줍니다.

또한 kafka.network:type=RequestMetrics에서 요청 처리 시간을, java.lang:type=Memory에서 힙 메모리 사용량을 확인할 수 있습니다. GC(Garbage Collection) 관련 메트릭도 중요합니다.

GC가 자주 발생하면 브로커가 일시적으로 응답하지 않을 수 있습니다. 실무에서는 JConsole을 개발 환경에서 주로 사용하고, 운영 환경에서는 JMX 메트릭을 Prometheus 같은 모니터링 시스템으로 수집합니다.

JConsole은 수동 확인용이기 때문입니다. 자동화된 모니터링이 필요하죠.

주의할 점도 있습니다. JMX 포트를 외부에 노출하면 보안 위험이 있습니다.

지난 시간에 배운 SSL/TLS 설정을 JMX에도 적용하거나, 방화벽으로 접근을 제한하세요. 운영 환경에서는 반드시 인증이 필요합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. JConsole으로 브로커에 접속한 김개발 씨는 깜짝 놀랐습니다.

디스크 사용량이 95%를 넘어가고 있었고, 네트워크 요청 큐가 계속 쌓여 있었습니다. "아, 원인이 여기 있었군요!" 장애의 실체를 처음으로 직접 확인한 순간이었습니다.

실전 팁

💡 - JMX 포트는 브로커마다 다르게 설정하세요 (9999, 10000, 10001...)

• 운영 환경에서 JMX 접속 시 반드시 SSL 인증을 적용하세요
• 이 카드뉴스는 "Apache Kafka 완전 정복" 코스의 14/15편입니다

---

2. Prometheus 그라파나 모니터링

JMX로 브로커 상태를 직접 확인하던 김개발 씨에게 박시니어 씨가 새로운 과제를 주었습니다. "봇이 아니라 사람이 실시간으로 모니터링할 수는 없잖아요.

자동화된 대시보드가 필요합니다." 김개발 씨는 고개를 끄덕였지만, 어디서부터 시작해야 할지 막막했습니다.

Prometheus는 메트릭을 수집하고 저장하는 오픈소스 모니터링 시스템이며, Grafana는 수집된 메트릭을 시각화하는 대시보드 도구입니다. 이 둘을 조합하면 카프카 클러스터의 상태를 아름다운 그래프로 실시간 확인할 수 있습니다.

마치 병원의 모니터링 장비가 환자의 생체 신호를 그래프로 보여주는 것과 같습니다.

다음 코드를 살펴봅시다.

# docker-compose.yml - Prometheus + Grafana 설정
version: '3.8'
services:
  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

# prometheus.yml - 카프카 메트릭 수집 설정
global:
  scrape_interval: 15s
scrape_configs:
  - job_name: 'kafka'
    static_configs:
      - targets:
          - 'jmx-exporter:5556'

JMX로 브로커의 상태를 직접 확인하는 방법을 배운 김개발 씨. 하지만 매번 JConsole을 열어서 수동으로 확인하는 건 현실적이지 않았습니다.

특히 브로커가 3대, 5대로 늘어나면 더욱 불가능해집니다. 박시니어 씨가 말했습니다.

"실무에서는 Prometheus와 Grafana 조합을 씁니다. 이게 사실상 업계 표준이에요." Prometheus와 Grafana를 쉽게 비유하자면, Prometheus는 데이터 수집기이고 Grafana는 데이터 시각화 도구입니다.

신호를 수집하는 센서와, 센서 데이터를 아름다운 그래프로 그려주는 모니터 같은 관계죠. 하지만 카프카의 JMX 메트릭을 Prometheus가 바로 읽을 수는 없습니다.

중간에 JMX Exporter라는 변환기가 필요합니다. JMX Exporter는 JMX 메트릭을 Prometheus가 이해할 수 있는 형식으로 변환해 줍니다.

마치 번역기처럼요. 설정 과정을 단계별로 살펴보겠습니다.

먼저 JMX Exporter를 브로커에 연결합니다. 브로커启动 스크립트에 -javaagent 옵션을 추가하면 됩니다.

그러면 Exporter가 JMX 메트릭을 HTTP 엔드포인트로 노출합니다. 다음으로 Prometheus 설정 파일에서 수집 대상을 지정합니다.

scrape_interval은 메트릭을 수집하는 주기입니다. 보통 15초로 설정합니다.

너무 짧으면 부하가 걸리고, 너무 길면 변화를 놓칠 수 있죠. Prometheus가 메트릭을 수집하면, Grafana에서 대시보드를 만듭니다.

다행히 카프카용 대시보드 템플릿이 Grafana 커뮤니티에 이미 준비되어 있습니다. 템플릿 ID 7589나 11962를 import하면 바로 사용할 수 있습니다.

대시보드에서 꼭 확인해야 할 패널이 있습니다. Bytes In/Out(처리량), Request Latency(요청 지연시간), Under Replicated Partitions(복제 지연 파티션 수), Offline Partitions(오프라인 파티션 수)입니다.

이 네 가지가 카프카 건강의 핵심 지표입니다. 특히 Under Replicated Partitions가 0이 아니면 주의해야 합니다.

이 지표가 올라가면 복제가 제대로 되지 않고 있다는 뜻입니다. 브로커 장애 시 데이터 유실 가능성이 생깁니다.

이 지표에 대한 알림을 반드시 설정하세요. Grafana의 Alerting 기능을 사용하면 메트릭이 임계치를 넘었을 때 자동으로 알림을 보낼 수 있습니다.

Slack, 이메일, PagerDuty 등과 연동할 수 있습니다. 예를 들어 컨슈머 랙이 1000을 넘으면 Slack으로 알림을 보내도록 설정할 수 있습니다.

하지만 초보자들이 흔히 하는 실수가 있습니다. 모든 메트릭을 다 수집하려고 하는 것이죠.

메트릭이 너무 많으면 Prometheus의 저장 공간이 빠르게 차고, 대시보드가 복잡해져 오히려 중요한 신호를 놓칩니다. 처음에는 핵심 메트릭 10~15개로 시작하세요.

다시 김개발 씨 이야기입니다. Grafana 대시보드를 구축한 김개발 씨는 감탄했습니다.

"와, 브로커 3대의 상태가 한 화면에 다 보이네요!" 이제 장애가 발생해도 어디서부터 조사해야 할지 바로 알 수 있게 되었습니다.

실전 팁

💡 - Grafana 커뮤니티에서 카프카 대시보드 템플릿을 import하면 시간을 크게 절약할 수 있습니다

• Prometheus의 저장 기간(retention)을 15~30일로 설정하여 디스크 사용량을 관리하세요
• 이 카드뉴스는 "Apache Kafka 완전 정복" 코스의 14/15편입니다

---

3. 브로커 상태 점검 항목

대시보드가 구축된 후, 김개발 씨는 매일 아침 Grafana를 열어보는 습관을 들였습니다. 하지만 수많은 그래프 중 어떤 것을 먼저 봐야 할지 잘 모르겠습니다.

"박시니어님, 이那么多 그래프 중에서 뭐가 제일 중요한가요?" 박시니어 씨가 미소를 지으며 답했습니다. "핵심만 콕콕 집어드릴게요."

카프카 브로커를 점검할 때 반드시 확인해야 할 핵심 항목들이 있습니다. 브로커 가용성, 디스크 사용량, 네트워크 처리량, 복제 상태, 컨트롤러 상태 등이며, 이 항목들을 정기적으로 점검하면 장애를 사전에 예방할 수 있습니다.

마치 비행기 조종사가 이륙 전 체크리스트를 확인하는 것과 같습니다.

다음 코드를 살펴봅시다.

# 카프카 브로커 상태 점검 스크립트
#!/bin/bash

# 1. 브로커 상태 확인
bin/kafka-broker-api-versions.sh \
  --bootstrap-server localhost:9092

# 2. 토픽 파티션 상태 확인
bin/kafka-topics.sh --describe \
  --bootstrap-server localhost:9092 \
  --topic order-events

# 3. 클러스터 메타데이터 확인
bin/kafka-metadata.sh --snapshot \
  /tmp/kafka/combined-00000000000000000000.log \
  --command "broker" 2>/dev/null || true

# 4. 컨슈머 그룹 랙 확인
bin/kafka-consumer-groups.sh --describe \
  --bootstrap-server localhost:9092 \
  --group order-consumer-group

모니터링 시스템이 구축되었다면, 이제 무엇을 확인해야 할지 알아야 합니다. 아무리 좋은 계기판이라도, 어디를 봐야 하는지 모르면 소용이 없겠죠.

박시니어 씨가 화이트보드에 점검 항목을 적기 시작했습니다. "매일 아침 이것만 확인해요." 첫 번째, 브로커 가용성입니다.

모든 브로커가 정상적으로 실행 중인지 확인합니다. kafka-broker-api-versions.sh 명령어로 브로커가 응답하는지 테스트할 수 있습니다.

응답이 없는 브로커가 있다면 즉시 조사해야 합니다. 두 번째, 디스크 사용량입니다.

카프카는 메시지를 디스크에 저장하므로 디스크가 꽉 차면 심각한 문제가 발생합니다. 디스크 사용량이 **80%**를 넘으면 경고, **90%**를 넘으면 임계 상태로 간주하세요.

retention 설정을 조정하거나 디스크를 추가해야 합니다. 세 번째, 복제 상태입니다.

kafka-topics.sh --describe 명령어로 각 토픽의 파티션 복제 상태를 확인합니다. 여기서 Isr(In-Sync Replicas) 목록을 주목하세요.

ISR 수가 복제 팩터보다 작으면, 일부 복제본이 동기화되지 않고 있다는 뜻입니다. 네 번째, 컨트롤러 상태입니다.

카프카 클러스터에는 하나의 Controller 브로커가 있습니다. 컨트롤러는 파티션 리더 선출, 브로커 장애 감지 등 클러스터 관리를 담당합니다.

컨트롤러가频繁히 변경되면 클러스터에 불안정 요소가 있는 것입니다. 다섯 번째, 네트워크 처리량입니다.

BytesInPerSec과 BytesOutPerSec의 추이를 확인합니다. 갑자기 처리량이 급증하거나 급감하면 원인을 파악해야 합니다.

예를 들어 배치 시간에 처리량이 급증하는 패턴이 정상이라면, 다른 시간대에 갑자기 튀는 것은 비정상입니다. 여섯 번째로 확인할 것은 요청 지연시간입니다.

ProduceRequest와 FetchRequest의 평균 처리 시간을 모니터링합니다. 지연시간이 갑자기 증가하면 디스크 병목, 네트워크 문제, 또는 GC로 인한 일시 정지일 수 있습니다.

김개발 씨가 질문했습니다. "이걸 매일 수동으로 확인해야 하나요?" 박시니어 씨가 웃으며 대답했습니다.

"아니요, 물론 자동화해야죠. 점검 스크립트를 크론으로 매일 실행하고, 이상이 있으면 Slack으로 알림을 보내도록 설정하세요." 실제로 많은 기업에서 이런 점검을 자동화합니다.

쉘 스크립트로 점검 항목들을 순차적으로 실행하고, 각 항목의 결과를 판단하여 정상/경고/임계 상태로 분류합니다. 이 결과를 Prometheus에 노출하면 Grafana 대시보드에서도 확인할 수 있습니다.

초보자들이 자주 놓치는 부분이 있습니다. 바로 로그 디렉토리의 디스크 사용량입니다.

카프카는 데이터 로그뿐만 아니라 운영 로그도 파일로 쌓입니다. 이 로그 파일도 디스크를 차지하므로, log4j 설정으로 로그 로테이션과 보존 기간을 적절히 설정해야 합니다.

점검의 핵심은 꾸준함입니다. 장애가 발생한 후에 확인하는 것이 아니라, 정상적으로 동작할 때의 기준선(baseline)을 미리 알아두어야 이상을 빠르게 감지할 수 있습니다.

실전 팁

💡 - 정상 상태时的 메트릭 기준선을 기록해 두면 이상 감지가 훨씬 쉽습니다

• 디스크 사용량은 파티션 단위로 확인하면 어떤 토픽이 디스크를 많이 차지하는지 알 수 있습니다
• 이 카드뉴스는 "Apache Kafka 완전 정복" 코스의 14/15편입니다

---

4. 컨슈머 랙 알림 설정

김개발 씨가 점심을 먹고 돌아오니, 박시니어 씨가 화면을 가리키고 있었습니다. "이거 봐, 컨슈머 랙이 5만 건이야." 김개발 씨는 고개를 갸웃했습니다.

"랙이요? 카프카에 랙이 있나요?" 박시니어 씨가 설명을 시작했습니다.

"아니, 랙은 쌓인 메시지 수를 말하는 거예요. 이걸 모르면 큰일 날 수 있어요."

**컨슈머 랙(Consumer Lag)**은 프로듀서가 보낸 메시지와 컨슈머가 실제로 처리한 메시지 사이의 차이를 의미합니다. 랙이 쌓이면 컨슈머가 메시지를 따라가지 못하고 있다는 뜻이며, 이는 지연, 메모리 부족, 장애로 이어질 수 있습니다.

마치 컨베이어 벨트에 물건이 쌓여 처리하지 못하는 공장과 같습니다.

다음 코드를 살펴봅시다.

# 컨슈머 랙 확인 명령어
bin/kafka-consumer-groups.sh --describe \
  --bootstrap-server localhost:9092 \
  --group order-consumer-group

# 출력 예시:
# GROUP  TOPIC  PARTITION  CURRENT-OFFSET  LOG-END-OFFSET  LAG
# order  orders 0          15000           65000           50000
# order  orders 1          62000           65000           3000

# 컨슈머 랙 자동 알림 스크립트
LAG=$(bin/kafka-consumer-groups.sh --describe \
  --bootstrap-server localhost:9092 \
  --group order-consumer-group \
  | awk 'NR>1 {sum+=$6} END {print sum}')

if [ "$LAG" -gt 10000 ]; then
  echo "CRITICAL: Consumer lag is $LAG"
  # Slack webhook으로 알림 전송
  curl -X POST -H 'Content-type: application/json' \
    --data "{\"text\":\"Consumer lag alert: $LAG\"}" \
    "$SLACK_WEBHOOK_URL"
fi

박시니어 씨가 화이트보드에 그림을 그렸습니다. 컨베이어 벨트 위에 상자가 쌓여가는 모습이었습니다.

"이 상자들이 메시지고, 벨트 끝에서 상자를 내리는 작업자가 컨슈머예요. 작업자가 느리면 상자는 계속 쌓이겠죠?

이게 바로 컨슈머 랙입니다." 컨슈머 랙의 공식은 단순합니다. LOG-END-OFFSET - CURRENT-OFFSET = LAG.

즉, 토픽에 저장된 마지막 메시지 위치에서 컨슈머가 읽은 위치를 빼면, 아직 처리하지 못한 메시지 수가 나옵니다. 김개발 씨가 물었습니다.

"랙이 조금 있으면 괜찮은 건가요?" 박시니어 씨가 답했습니다. "네, 랙이 0인 것은 사실 불가능해요.

프로듀서가 메시지를 보내는 순간과 컨슈머가 처리하는 순간 사이에는 항상 미세한 시간 차이가 있거든요. 중요한 건 랙이 지속적으로 증가하는지 여부예요." 랙이 증가하는 원인은 크게 세 가지입니다.

첫째, 컨슈머의 처리 속도가 프로듀서의 전송 속도보다 느린 경우입니다. 메시지 처리 로직이 무거우거나, 외부 API 호출로 응답 시간이 길 때 발생합니다.

둘째, 컨슈머에 장애가 발생한 경우입니다. 컨슈머 프로세스가 다운되거나, 예외가 발생해 재시작이 반복되면 랙이 급증합니다.

이 경우는 즉시 조치가 필요합니다. 셋째, 파티션 수와 컨슈머 수의 불균형입니다.

파티션이 4개인데 컨슈머가 2개라면, 각 컨슈머는 2개의 파티션을 담당해야 합니다. 컨슈머 수를 파티션 수와 맞추면 병렬 처리 성능이 올라갑니다.

랙 모니터링은 어떻게 자동화할 수 있을까요? 먼저 정기적으로 kafka-consumer-groups.sh --describe 명령어를 실행하여 랙 값을 수집합니다.

이 값을 Prometheus에 노출하면 Grafana에서 실시간으로 모니터링할 수 있습니다. JMX Exporter를 통해 kafka.consumer:type=consumer-fetch-manager-metrics,client-id=* 메트릭을 수집하면 더 세밀한 랙 정보를 얻을 수 있습니다.

특히 records-lag-max는 컨슈머가 가장 뒤처진 파티션의 랙을 보여줍니다. 알림 설정의 핵심은 적절한 임계치를 정하는 것입니다.

서비스 특성에 따라 다르지만, 일반적으로 랙이 1,000~10,000을 넘으면 경고, 50,000을 넘으면 임계로 설정합니다. 하지만 주문 처리 같은 실시간 서비스에서는 더 낮은 임계치가 필요할 수 있습니다.

Grafana Alerting에서 알림 규칙을 설정할 때 유용한 팁이 있습니다. 단순히 절대값으로 알림을 보내는 것보다, 랙의 증가 추세를 기준으로 하면 더 빠르게 문제를 감지할 수 있습니다.

예를 들어 "5분 동안 랙이 계속 증가하고 있으면 알림" 같은 조건이 효과적입니다. 다시 김개발 씨 이야기입니다.

알림 설정을 완료한 후 며칠 뒤, 김개발 씨의 Slack에 알림이 떴습니다. "Consumer lag alert: 15,000".

김개발 씨는 즉시 원인을 조사했습니다. 컨슈머가 호출하는 외부 API가 느려진 것이 원인이었습니다.

"이걸 안 모니터링하고 있었으면, 고객 불만이 폭주했을 거예요."

실전 팁

💡 - 랙 알림은 절대값뿐만 아니라 증가 추세 기준도 함께 설정하세요

• 컨슈머 재시작 후 랙이 급증하는 것은 일시적이므로, 안정화 시간(5~10분)을 두고 알림을 설정하세요
• 이 카드뉴스는 "Apache Kafka 완전 정복" 코스의 14/15편입니다

---

5. 로그 관리와 트러블슈팅

어느 날 밤, 김개발 씨의 휴대폰에 긴급 연락이 왔습니다. "프로덕션 환경에서 메시지가 유실되는 것 같다." 김개발 씨는 서버에 접속했지만, 수많은 로그 파일 앞에서 어디서부터 봐야 할지 몰랐습니다.

박시니어 씨가 연락을 받고 원격으로 접속했습니다. "로그를 읽는 것도 기술이에요.

방법을 알려드릴게요."

카프카의 서버 로그와 애플리케이션 로그를 체계적으로 관리하면 장애 원인을 빠르게 파악할 수 있습니다. 로그 레벨 설정, 로그 로테이션, 로그 수집 시스템(ELK Stack) 구축이 핵심입니다.

마치 탐정이 증거를 수집하고 분석하는 과정과 같습니다.

다음 코드를 살펴봅시다.

# server.properties - 로그 설정
# 로그 레벨 설정 (DEBUG, INFO, WARN, ERROR)
log4j.rootLogger=INFO, kafkaAppender

# 컨트롤러 로그를 DEBUG로 상향
log4j.logger.kafka.controller=DEBUG, controllerAppender

# 레플리카 관리 로그
log4j.logger.kafka.cluster=INFO

# 로그 파일 경로 및 로테이션 설정
log4j.appender.kafkaAppender=org.apache.log4j.RollingFileAppender
log4j.appender.kafkaAppender.File=/var/log/kafka/server.log
log4j.appender.kafkaAppender.MaxFileSize=100MB
log4j.appender.kafkaAppender.MaxBackupIndex=10

# 트러블슈팅 - 자주 발생하는 에러 로그 검색
grep -i "error\|warn\|exception" /var/log/kafka/server.log | tail -50
grep "OutOfMemory" /var/log/kafka/server.log
grep "FATAL" /var/log/kafka/server.log

카프카를 운영하다 보면 피할 수 없는 것이 장애입니다. 그리고 장애를 해결하려면 로그를 읽어야 합니다.

하지만 로그 파일은 방대하고, 어디에 중요한 정보가 있는지 찾기 어렵습니다. 박시니어 씨가 말했습니다.

"로그 분석의 첫 번째 단계는 어디서부터 읽을지 아는 것입니다." 카프카의 로그는 크게 두 가지입니다. 하나는 브로커의 운영 로그(server.log)이고, 다른 하나는 데이터 로그(메시지가 저장되는 파일)입니다.

트러블슈팅할 때는 운영 로그를 주로 확인합니다. 로그 레벨을 적절히 설정하는 것이 중요합니다.

운영 환경에서는 기본적으로 INFO 레벨을 사용합니다. 하지만 특정 문제를 조사할 때는 DEBUG 레벨로 상향해야 합니다.

전체 로그를 DEBUG로 설정하면 로그가 너무 많아져 성능에 영향을 줄 수 있으므로, 문제와 관련된 컴포넌트만 DEBUG로 설정하세요. 자주 마주치는 에러 패턴을 알아두면 장애 조치가 훨씬 빨라집니다.

**"java.io.IOException: No space left on device"**는 디스크가 꽉 찬 경우입니다. retention 설정을 조정하거나 디스크를 추가해야 합니다.

**"OutOfMemoryError"**는 힙 메모리가 부족한 경우입니다. 힙 크기를 늘리거나, 메시지 배치 크기를 줄여보세요.

8화에서 배운 CLI 명령어로 브로커 설정을 확인할 수 있습니다. **"Leader not available"**은 파티션의 리더 브로커에 접근할 수 없는 경우입니다.

브로커가 다운되었거나, 컨트롤러가 리더를 재선출하지 못한 상태일 수 있습니다. 브로커 상태를 먼저 확인하세요.

**"Connection reset by peer"**은 네트워크 문제입니다. 클라이언트와 브로커 사이의 네트워크 불안정이나, 방화벽 설정 문제일 수 있습니다.

nc(netcat) 명령어로 포트 연결을 테스트해 보세요. 로그를 더 효과적으로 관리하려면 ELK Stack(Elasticsearch, Logstash, Kibana)을 도입하세요.

Logstash가 카프카 브로커의 로그를 수집하고, Elasticsearch에 저장한 뒤, Kibana에서 검색하고 시각화할 수 있습니다. 많은 기업에서 이 조합을 사용합니다.

Filebeat를 사용하면 더 가볍게 로그를 수집할 수 있습니다. Filebeat는 Logstash보다 리소스를 적게 사용하므로, 브로커 서버에 부하를 주지 않습니다.

Filebeat가 로그를 수집하고, 이를 Logstash나 Elasticsearch로 전달하는 구조가 일반적입니다. 초보자들이 자주 하는 실수 중 하나는 로그 확인을 미루는 것입니다.

"정상 동작할 때 로그를 안 봐도 되지 않을까?"라고 생각하지만, 정상 상태의 로그를 알아야 비정상을 감지할 수 있습니다. 평소에 로그를 살펴보는 습관을 들이세요.

다시 김개발 씨의 장애 상황으로 돌아가 봅시다. 박시니어 씨는 grep 명령어로 로그를 검색했습니다.

"FATAL" 키워드로 검색하자, 브로커 2번에서 "Corrupt index file" 에러가 발생한 것을 발견했습니다. 디스크 오류로 인덱스 파일이 손상된 것이었습니다.

손상된 파일을 복구하고 브로커를 재시작하니 정상으로 돌아왔습니다.

실전 팁

💡 - 장애 발생 시 가장 먼저 가장 최근의 ERROR와 WARN 로그부터 확인하세요

• 정상 상태时的 로그를 기록해 두면 이상을 더 빠르게 감지할 수 있습니다
• 이 카드뉴스는 "Apache Kafka 완전 정복" 코스의 14/15편입니다

---

6. 카프카 매니지먼트 도구 소개

카프카 모니터링과 운영을 직접 구축하며 김개발 씨는 깨달았습니다. "CLI 명령어도 좋고, Grafana도 좋지만, 카프카 클러스터 전체를 관리하려면 더 편한 도구가 필요해요." 박시니어 씨가 고개를 끄덕였습니다.

"맞아요. 오픈소스 매니지먼트 도구를 소개할게요."

카프카 클러스터를 시각적으로 관리하는 매니지먼트 도구들이 있습니다. kafka-ui, CMAK(Cluster Manager for Apache Kafka), AKHQ 같은 도구를 사용하면 브로커 상태, 토픽 관리, 컨슈머 그룹 모니터링, 메시지 브라우징 등을 웹 UI에서 편리하게 수행할 수 있습니다.

마치 스마트폰의 설정 앱이 모든 기능을 한곳에서 관리하듯이요.

다음 코드를 살펴봅시다.

# Docker로 kafka-ui 실행 (가장 추천하는 관리 도구)
docker run -d \
  --name kafka-ui \
  -p 8080:8080 \
  -e KAFKA_CLUSTERS_0_NAME=local \
  -e KAFKA_CLUSTERS_0_BOOTSTRAPSERVERS=kafka:9092 \
  -e KAFKA_CLUSTERS_0_ZOOKEEPER=zookeeper:2181 \
  provectuslabs/kafka-ui:latest

# Docker로 AKHQ 실행
docker run -d \
  --name akhq \
  -p 8081:8080 \
  -e AKHQ_CONFIGURATION=\
  "akhq:\n  connections:\n    local:\n      url: kafka:9092" \
  tchiotludo/akhq:latest

# CMAK 실행 (기존 Kafka Manager)
docker run -d \
  --name cmak \
  -p 9000:9000 \
  -e ZK_HOSTS=zookeeper:2181 \
  hlebalbau/kafka-manager:stable

지금까지 JMX, Prometheus, Grafana로 모니터링을 구축하고, 컨슈머 랙과 로그 관리를 알아봤습니다. 하지만 박시니어 씨가 말했듯, 이 모든 것을 더 편하게 할 수 있는 도구들이 있습니다.

김개발 씨가 물었습니다. "CLI 명령어로 다 할 수 있는데, 굳이 UI 도구가 필요한가요?" 박시니어 씨가 답했습니다.

"물론 CLI로 다 할 수 있어요. 하지만 토픽을 생성하고, 컨슈머 그룹을 확인하고, 메시지 내용을 보는 작업을 매번 터미널에서 하려면 시간이 많이 걸리죠.

UI 도구는 이런 반복 작업을 몇 번의 클릭으로 끝내줍니다." 대표적인 매니지먼트 도구 세 가지를 비교해 보겠습니다. 첫 번째, kafka-ui입니다.

현재 가장 인기 있는 카프카 웹 UI 도구입니다. 프로벡투스 랩스(Provectus)에서 개발했으며, 토픽 관리, 컨슈머 그룹 모니터링, 메시지 브라우징, 스키마 레지스트리 연동 등 거의 모든 기능을 제공합니다.

UI가 깔끔하고 직관적이라 초보자도 쉽게 사용할 수 있습니다. Docker로 간단히 실행할 수 있고, 보안 설정도 지원합니다.

두 번째, AKHQ입니다. 원래 이름은 KafkaHQ였습니다.

카프카 클러스터 관리는 물론, 커넥트, 스트림즈, 스키마 레지스트리까지 통합 관리할 수 있는 강력한 도구입니다. 특히 ACL 관리와 토픽 설정 변경 기능이 뛰어납니다.

다중 클러스터를 동시에 관리할 수 있는 것도 큰 장점입니다. **세 번째, CMAK(Cluster Manager for Apache Kafka)**입니다.

예전에는 Yahoo Kafka Manager로 불렸습니다. 가장 오래된 도구 중 하나로, 클러스터 상태 확인과 리밸런싱에 특화되어 있습니다.

하지만 최근 업데이트가 줄어들고, UI가 다소 구식이라는 단점이 있습니다. 이 중에서 어떤 도구를 선택해야 할까요?

박시니어 씨의 추천은 kafka-ui입니다. "가장 활발하게 개발되고 있고, 기능도 충분하며, UI도 직관적이에요.

처음 시작한다면 kafka-ui를 추천해요." 매니지먼트 도구를 운영 환경에 도입할 때 주의할 점이 있습니다. 보안 설정이 필수입니다.

도구에 인증을 걸지 않으면, 네트워크에 접근할 수 있는 누구나 카프카 클러스터를 조작할 수 있습니다. kafka-ui는 Spring Security 기반 인증을 지원하므로, 반드시 활성화하세요.

또한 읽기 전용 모드를 고려해 보세요. 운영 환경에서는 실수로 토픽을 삭제하거나 설정을 변경하는 것을 방지하기 위해, 읽기 전용으로만 사용하는 것도 좋은 전략입니다.

Docker Compose로 전체 스택을 구성하면 카프카, ZooKeeper, Prometheus, Grafana, kafka-ui를 한 번에 실행할 수 있습니다. 로컬 개발 환경에서 이렇게 구성해 두면, 새로운 팀원도 빠르게 개발 환경을 세팅할 수 있습니다.

다시 김개발 씨 이야기로 마무리해 봅시다. kafka-ui를 도입한 김개발 씨는 감탄했습니다.

"토픽 생성도 클릭 한 번이고, 메시지 내용도 바로 볼 수 있고, 컨슈머 랙도 그래프로 보이네요!" 박시니어 씨가 말했습니다. "도구가 좋아진다고 운영이 자동으로 좋아지는 건 아니에요.

중요한 건 정기적으로 점검하고, 알림을 설정하고, 문제가 생기면 빠르게 대응하는 거예요. 도구는 그 과정을 돕는 수단일 뿐이에요." 김개발 씨는 고개를 끄덕였습니다.

모니터링, 알림, 로그 관리, 매니지먼트 도구. 카프카를 안정적으로 운영하기 위한 필수 요소들을 모두 배웠습니다.

이제 다음 단계는 이 모든 것을 종합한 실전 아키텍처와 베스트 프랙티스를 배우는 것입니다.

실전 팁

💡 - kafka-ui를 Docker로 실행할 때 반드시 인증 설정을 활성화하세요

• 운영 환경에서는 읽기 전용 모드를 고려하여 실수로 인한 장애를 방지하세요
• 다음 카드뉴스에서는 "카프카 실전 아키텍처와 베스트 프랙티스"를 다룹니다
• 이 카드뉴스는 "Apache Kafka 완전 정복" 코스의 14/15편입니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!