Kafka Agent 설치

모든 핵심 참고 문서를 확인했습니다. 이제 상세한 답변을 작성합니다.

---

exemONE Kafka Agent 설치 방법 및 설정 상세 가이드

참고 문서:

• Kafka Agent 설치 가이드
• Kafka Agent 지원 환경
• Kafka Agent On-Premise 설치
• Kafka Agent Docker 설치
• Kafka 데이터 수집 옵션
• Kafka 특정 레벨 로그 수집 옵션
• Kafka 메세지 수집 관련 디버그 로그 설정
• Kafka Topic Message 조회 시 Timeout 에러 발생
• Message Queue 설정 화면
• Message Queue Device 추가
• Message Queue Group 추가
• 모듈별 사용 Port

---

1. 모듈 설명

exemONE Kafka Agent(exem-kafka-agent)는 Kafka 클러스터의 Broker, Topic, Consumer Group 등 메트릭 데이터를 수집하여 exemONE 수집 서버(Receiver)로 전송하는 모니터링 에이전트입니다.

---

2. 지원 환경

항목	요구사항
Java	Java 17 이상
OS	Linux 환경

---

3. 사전 설정

• 사전 설정은 없음
• 단, 메트릭 수집 방식에 따라 사전 준비가 필요합니다 (아래 메트릭 수집 방법 참조)

---

4. 메트릭 수집 방법

메트릭 수집 방식에 따라 수집 가능한 데이터가 상이합니다.

4-1. JMX 방식

JMX(Java Management Extensions)는 Java 애플리케이션의 모니터링과 관리를 위한 표준화 기술입니다. Kafka 프로세스에 JMX를 활성화하여 실시간 모니터링 및 세밀한 메트릭 수집이 가능합니다.

요구 사항:

• Kafka 프로세스에 JMX 활성화 필요
• Kafka Server 또는 Java로 서비스되는 Kafka Consumer/Producer에 아래 옵션 적용

-Dcom.sun.management.jmxremote=true
-Djava.rmi.server.hostname={jmx_ip}
-Dcom.sun.management.jmxremote.port={jmx_port(local connect)}
-Dcom.sun.management.jmxremote.rmi.port={jmx_port(remote connect)}
-Dcom.sun.management.jmxremote.authenticate=false  (선택)
-Dcom.sun.management.jmxremote.ssl=false

위 옵션은 KAFKA_JMX_OPTS 환경 변수에 등록하여 사용할 수 있습니다:

export KAFKA_JMX_OPTS="-Dcom.sun.management.jmxremote=true \
                       -Djava.rmi.server.hostname={jmx_ip} \
                       -Dcom.sun.management.jmxremote.port={jmx_port(local connect)} \
                       -Dcom.sun.management.jmxremote.rmi.port={jmx_port(remote connect)} \
                       -Dcom.sun.management.jmxremote.authenticate=false \
                       -Dcom.sun.management.jmxremote.ssl=false"

4-2. Admin Client 방식

Kafka 라이브러리가 제공하는 Admin Client API를 이용하여, 토픽, 파티션, 브로커 등 클러스터 메타데이터 및 상태 메트릭을 수집합니다.

요구 사항:

• bootstrap server 정보가 필요합니다
• 해당 서버에 연결하여 데이터를 수집합니다

---

5. 설치 방법 (2가지)

exemONE Kafka Agent는 환경에 따라 2가지 설치 방식을 제공합니다.

설치 방식	적합 환경	특징
On-Premise (프로세스)	물리 서버, VM 환경	tar.gz 압축 해제 후 java -jar로 실행
Docker Container	Docker 환경 (exemONE 도커 패키지)	Docker 이미지 로드 후 docker-compose로 실행

---

5-1. On-Premise 설치 (프로세스로 실행)

단계 1. 패키지 다운로드

고객사 설치 시는 제품기술팀에 문의하여 패치 파일을 준비합니다.

단계 2. 패키지 압축 해제

tar -zxvf EXEM-KAFKA-AGENT-{VERSION}.tar.gz

단계 3. 설정 파일 수정

파일 위치: exem/kafka/cfg/kafka.conf

RECEIVER_ADDR에 수집서버 IP:PORT 정보를 입력합니다. (필수)

단계 4. 에이전트 실행

java -jar {패키지_경로}/exem/kafka/lib/exem-kafka-agent.jar

---

5-2. Docker 설치 (Docker Container로 실행)

사전 설정

1. 설정 파일 준비

• EXEM-KAFKA-AGENT~.tar.gz 파일을 압축 해제하여 확인합니다.

2. Dockerfile 준비

3. EXEM KAFKA AGENT 이미지 준비

설치 절차

단계 1. exemone-kafka-agent 폴더 생성

$EXEMONE_HOME/containers에 exemone-kafka-agent 폴더를 생성합니다.

단계 2. 하위 폴더 생성

exemone-kafka-agent 아래에 cfg, log 두 개의 폴더를 생성합니다.

단계 3. cfg 폴더에 설정 파일 배치

cfg 폴더에 kafka.conf, cfg.reload 파일을 넣어줍니다.

kafka.conf에 Receiver 정보를 Port 정보까지 입력합니다.

Receiver 정보를 IP로 했을 때 receiver와 붙지 않는다면 exemone-receiver:9009로 입력합니다.

단계 4. Dockerfile 배치

$EXEMONE_HOME/dockerfile/kafka-agent 폴더를 생성 후 Dockerfile을 넣어줍니다.

단계 5. kafka-agent 이미지 로드

docker load -i <kafka-agent-이미지>.tar.gz

단계 6. .env 파일에 kafka-agent 버전 추가

vi .env

KAFKA_AGENT_IMAGE=maxgauge/exemone-kafka-agent ##new
KAFKA_AGENT_VERSION=3.0.12                      ##new

단계 7. docker-compose.yml에 kafka-agent 추가

vi docker-compose.yml

  kafka-agent:
    labels:
      io.exem: true
      io.exem.prod: exemone
      io.exem.one.type: application
      io.exem.one.app: kafka-agent
    container_name: exemone-kafka-agent
    build:
      context: ${EXEMONE_HOME}/dockerfile/kafka-agent
      args:
        KAFKA_AGENT_IMAGE: ${KAFKA_AGENT_IMAGE}
        KAFKA_AGENT_VERSION: ${KAFKA_AGENT_VERSION}
        EXEMONE_USER_UID: ${EXEMONE_USER_UID}
        EXEMONE_USER_GID: ${EXEMONE_USER_GID}
    volumes:
      - /etc/localhost:/etc/localhost:ro
      - $EXEMONE_HOME/containers/exemone-kafka-agent/cfg:/home/exemone/kafka/cfg
      - $EXEMONE_HOME/containers/exemone-kafka-agent/log:/home/exemone/kafka/log
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4g
    environment:
      HOST_UID: ${EXEMONE_USER_UID}
      HOST_GID: ${EXEMONE_USER_GID}
    networks:
      - exemone_network
    depends_on:
      receiver:
        condition: service_started
    restart: unless-stopped
    logging: *logging
    security_opt:
      - no-new-privileges

단계 8. kafka-agent 실행

scripts/restart.sh kafka-agent

---

6. 설정 파일 (kafka.conf) 상세

6-1. 파일 위치

${exemon-kafka-agent-home}/cfg/kafka.conf

6-2. 기본 설정 항목

설정 항목	설명	필수 여부
RECEIVER_ADDR	exemONE 수집 서버 주소 (IP:PORT)	필수

6-3. 데이터 수집 옵션

Topic 필터링 옵션

옵션	설명	기본값	지원 버전
TARGET_TOPIC_REGEX	특정 문자열이 포함된 토픽을 수집하거나 미수집하도록 설정. 값이 없으면 모든 Topic 수집	(없음 = 전체 수집)	v3.0.5+
TRACE_INTERNAL_TOPIC	내부 토픽(__consumer_offsets 등)의 수집 여부	false (미수집)	v3.0.5+

TARGET_TOPIC_REGEX 설정 예시:

# 특정 문자열 포함 토픽만 수집 (예: "broker" 포함)
TARGET_TOPIC_REGEX=.*(broker).*

# 특정 문자열 포함 토픽 제외 (예: "_" 또는 "-" 포함 시 제외)
TARGET_TOPIC_REGEX=^(?!.*(_|-)).*$

TRACE_INTERNAL_TOPIC 설정 예시:

TRACE_INTERNAL_TOPIC=true   # 내부 토픽 수집
TRACE_INTERNAL_TOPIC=false  # 내부 토픽 미수집 (기본값)

Consumer Group 필터링 옵션

옵션	설명	기본값	지원 버전
TARGET_CONSUMER_GROUP_REGEX	특정 문자열이 포함된 컨슈머 그룹을 수집하거나 미수집하도록 설정. 값이 없으면 모든 Consumer Group 수집	(없음 = 전체 수집)	v3.0.18+
TRACE_CONSUMER_GROUP_WHEN_EMPTY	Empty 상태의 Consumer Group 수집 여부	true (수집)	v3.0.18+
TRACE_CONSUMER_GROUP_WHEN_NO_TOPIC	할당된 Topic이 없는 Consumer Group 수집 여부	false (미수집)	v3.0.18+

TARGET_CONSUMER_GROUP_REGEX 설정 예시:

# 특정 문자열 포함 컨슈머 그룹만 수집 (예: "test" 또는 "exem" 포함)
TARGET_CONSUMER_REGEX=.*(test|exem).*

# 특정 문자열 포함 컨슈머 그룹 제외 (예: "_" 또는 "-" 포함 시 제외)
TARGET_CONSUMER_REGEX=^(?!.*(_|-)).*$

TRACE_CONSUMER_GROUP_WHEN_EMPTY 설정 예시:

TRACE_CONSUMER_GROUP_WHEN_EMPTY=true   # Empty 상태의 Consumer Group 수집 (기본값)
TRACE_CONSUMER_GROUP_WHEN_EMPTY=false  # Empty 상태의 Consumer Group 미수집

TRACE_CONSUMER_GROUP_WHEN_NO_TOPIC 설정 예시:

TRACE_CONSUMER_GROUP_WHEN_NO_TOPIC=true   # 할당된 Topic이 없는 Consumer Group 수집
TRACE_CONSUMER_GROUP_WHEN_NO_TOPIC=false  # 할당된 Topic이 없는 Consumer Group 미수집 (기본값)

6-4. 로그 설정 옵션

옵션	설명	기본값	지원 버전
FILE_LOG_LEVEL	로그 수집 레벨 설정 (DEBUG, INFO, WARN, ERROR 등)	-	v3.0.18+
LOG_LEVEL_SPECIFIC_ONLY	FILE_LOG_LEVEL에 해당하는 레벨의 로그만 출력할지 여부	(없음 = 하위 레벨까지 수집)	v3.0.18+

로그 설정 예시:

# DEBUG 레벨만 수집
FILE_LOG_LEVEL=DEBUG
LOG_LEVEL_SPECIFIC_ONLY=true

# DEBUG 레벨 이상 모든 로그 수집
FILE_LOG_LEVEL=DEBUG
LOG_LEVEL_SPECIFIC_ONLY=false

6-5. Timeout 옵션

옵션	설명
TOPIC_CONSUMER_REQUEST_TIMEOUT	Topic Message 조회 시 Consumer 요청 타임아웃 설정

6-6. 설정 동적 적용 (cfg.reload)

일부 설정은 kafka-agent 재시작 없이 cfg.reload 파일을 touch하여 동적으로 적용할 수 있습니다:

touch ${exemon-kafka-agent-home}/cfg/cfg.reload

단, 대부분의 데이터 수집 옵션 변경 후에는 kafka-agent를 재시작해야 합니다.

---

7. exemONE 웹 UI에서 Kafka 인스턴스 등록

Kafka Agent 설치 후 exemONE 웹 화면에서 Message Queue 인스턴스를 등록해야 모니터링이 가능합니다.

단계 1. Message Queue 그룹 추가

경로: Setting > Platform > Infrastructure > Message Queue

Message Queue Group에서 그룹 추가 버튼을 클릭합니다.

항목	설명
Group Name	그룹 이름 (최대 50자, 중복 불가)
Message Queue Type	Kafka 선택
Description	그룹에 대한 설명

단계 2. Message Queue Device 추가

Message Queue List에서 디바이스 추가 버튼을 클릭합니다.

항목	설명
Message Queue Type	메세지 큐 타입
Message Queue Group	소속될 메세지 큐 그룹
Agent	에이전트 선택
Instance Name	인스턴스 이름
Alias	사용자 지정 이름
Instance Type	Cluster: 카프카 클러스터를 구성하는 모든 브로커 연결 정보 / Cluster(Zookeeper): 클러스터로 구성된 여러 개의 주키퍼 서버 연결 정보
Connection Info	연결 정보 (bootstrap server 주소)
ID / Password	인증 정보 (필요 시)
Connection Test	연결 테스트 버튼
Broker List	리스트 가져오기 버튼 클릭 시 클러스터를 구성하는 브로커 목록 조회

단계 3. 연결 테스트 확인

Connection Test 버튼을 클릭하여 Kafka 클러스터와의 연결이 정상인지 확인합니다.

---

8. 모니터링 화면 확인

설치 및 등록 완료 후, exemONE 웹 화면의 Message Queue > Kafka 메뉴에서 모니터링할 수 있습니다.

• Kafka Map: Kafka 클러스터 전체 토폴로지 뷰
• Kafka List: Kafka 클러스터 목록
• Kafka Card: Kafka 클러스터 카드 뷰
• Cluster Detail Slide: Metric, Brokers, Topic, Consumer Groups, Information, Alert 정보 확인
• Broker Detail Slide: Metric, Topic, Consumer Groups, Information, Alert 정보 확인

Topic 필터링 적용 확인

TARGET_TOPIC_REGEX 옵션 적용 시:

• 대시보드에서 Target이 Topic인 지표(예: Cluster Topic Total Lag)에서 필터링 됩니다.

• Cluster Detail / Broker Detail > Topic 탭 리스트에서 필터링 됩니다.

Consumer Group 필터링 적용 확인

TARGET_CONSUMER_GROUP_REGEX 옵션 적용 시:

• 대시보드에서 Target이 Consumer Group인 지표(예: Cluster Consumer Total Lag)에서 필터링 됩니다.

• Cluster Detail / Broker Detail > Consumer Group 탭 리스트에서 필터링 됩니다.

---

9. 수집 로그 확인 방법

9-1. Topic 필터링 로그

로그 레벨이 DEBUG일 경우 출력됩니다:

• Topic 필터링에 의해 제외되는 경우:

No target topics are assigned to this consumer group. consumer group=> , topics=>

9-2. Consumer Group 필터링 로그

• TARGET_CONSUMER_GROUP_REGEX에 의해 수집 제외된 경우:

This consumer group is not trace target. consumer group=>

• TRACE_CONSUMER_GROUP_WHEN_EMPTY에 의해 Empty 상태여서 수집 제외된 경우:

This consumer group is currently 'empty'. consumer group=>

9-3. Cluster 메타데이터 수집 카운트 로그 (v3.0.18+)

• 클러스터 메타데이터 갱신 시:

it took 66 ms to update cluster metadata. topic count : 99, consumer group count : 4

• 수집된 컨슈머 그룹 정보:

consumer group=> , total lag=> , member count=>

9-4. 메세지 수집 디버그 로그 (v3.0.21+)

로그 레벨 DEBUG, 키워드 [PARTITION_MESSAGES]로 확인 가능합니다.

정상 수집 시 로그 흐름:

1. [PARTITION_MESSAGES] requestId=>..., topic=>..., partition=>... — 사용자 요청 정보
2. [PARTITION_MESSAGES] fetching current offset info... — metadata(offset) 조회 시작
3. [PARTITION_MESSAGES] metadata completed. — metadata(offset) 조회 완료
4. [PARTITION_MESSAGES] converting timestamps to offsets... — timestamp → offset 변환 시작
5. [PARTITION_MESSAGES] timestamp conversion completed. — 변환 완료
6. [PARTITION_MESSAGES] TopicPartition=>..., fromOffset=>..., toOffset=>... — 실제 조회 범위
7. [PARTITION_MESSAGES] seek completed. — consumer 준비 완료
8. [PARTITION_MESSAGES] fetched ... records. — poll 레코드 수
9. [PARTITION_MESSAGES] reached toOffset, breaking loop — 목표 offset 도달
10. [PARTITION_MESSAGES] partition [...] completed. ... records in queue. — partition 처리 완료
11. [PARTITION_MESSAGES] partition message count=>..., elapseTime=>... — 총 수집 메시지 및 소요 시간

예외 상황 로그:

• [PARTITION_MESSAGES] consumer is not initialized. — consumer 설정 오류
• [PARTITION_MESSAGES] cannot find partition list for topic [...] — partition 목록 조회 실패
• [PARTITION_MESSAGES] from-offset (...) is greater than to-offset (...). Skipping. — 조회 범위 오류
• [PARTITION_MESSAGES] timeout exceeded. — 처리 시간 초과 (현재까지 수집된 메시지만 전송)

---

10. 문제 해결 (Troubleshooting)

10-1. Topic Message 조회 시 Timeout 에러 발생

CASE 1. API Timeout 옵션 수정

확인 사항: Kafka > Topic Detail > Message 조회 시 Timeout 발생

원인: 통신 지연으로 인한 데이터 수집 지연

조치 방법:

1. API Timeout 옵션 시간 설정

수정 파일: exemone/installer/exemone/containers/exemone-api/configs/application.yml

timeout:
  connection:
    os:
    ...
    messagequeue:
      kafka:
        connect: 60
        testv2: 60
        broker: 60

2. API 재구동하여 설정 적용:

exemone/installer/exemone/scripts/restart.sh api

3. Topic Message 정상 출력 확인

CASE 2. TOPIC_CONSUMER_REQUEST_TIMEOUT 옵션 수정

확인 사항: kafka-agent에서 Timeout Error 로그 발생

원인: 통신 지연으로 인한 데이터 수집 지연

조치 방법:

1. TOPIC_CONSUMER_REQUEST_TIMEOUT 옵션 시간 설정

수정 파일: exemone/installer/exemone/containers/exemone-kafka-agent/cfg/kafka.conf

2. 설정 적용 (재시작 없이):

touch exemone/installer/exemone/containers/exemone-kafka-agent/cfg/cfg.reload

3. Topic Message 정상 출력 확인

---

11. kafka.conf 전체 옵션 요약

옵션	설명	기본값	지원 버전
RECEIVER_ADDR	수집 서버 주소 (IP:PORT)	(필수 입력)	전 버전
TARGET_TOPIC_REGEX	Topic 정규식 필터링	없음 (전체 수집)	v3.0.5+
TRACE_INTERNAL_TOPIC	내부 토픽 수집 여부	false	v3.0.5+
TARGET_CONSUMER_GROUP_REGEX	Consumer Group 정규식 필터링	없음 (전체 수집)	v3.0.18+
TRACE_CONSUMER_GROUP_WHEN_EMPTY	Empty 상태 Consumer Group 수집 여부	true	v3.0.18+
TRACE_CONSUMER_GROUP_WHEN_NO_TOPIC	할당된 Topic 없는 Consumer Group 수집 여부	false	v3.0.18+
FILE_LOG_LEVEL	로그 수집 레벨	-	v3.0.18+
LOG_LEVEL_SPECIFIC_ONLY	설정 레벨 로그만 출력 여부	(없음 = 하위 레벨까지)	v3.0.18+
TOPIC_CONSUMER_REQUEST_TIMEOUT	Topic Message 조회 타임아웃	-	-

---

12. 주의사항

1. Java 17 이상 필수: Kafka Agent 실행을 위해 Java 17 이상이 설치되어 있어야 합니다.
2. Linux 환경만 지원: Windows 및 Unix 환경은 지원하지 않습니다.
3. RECEIVER_ADDR 필수 설정: kafka.conf에서 수집 서버 주소를 반드시 설정해야 합니다.
4. Docker 환경에서 Receiver 연결 불가 시: IP로 설정 시 receiver와 연결되지 않는다면 exemone-receiver:9009로 입력하세요.
5. JMX 메트릭 수집 시: Kafka 프로세스에 JMX 옵션이 사전에 활성화되어 있어야 합니다.
6. 데이터 수집 옵션 변경 후 재시작: 대부분의 kafka.conf 옵션 변경 후에는 kafka-agent를 재시작해야 합니다. 단, TOPIC_CONSUMER_REQUEST_TIMEOUT은 cfg.reload touch로 동적 적용 가능합니다.
7. 패키지 파일 준비: 설치 파일은 제품기술팀에 문의하여 준비합니다.