시간정원
← Blog

dev · 2026-07-22

데스크톱 Kafka 클라이언트, KafkaPilot 만든 이야기

왜 만들었나

AKHQ, Kafka UI, RedPanda Console 같은 웹 기반 Kafka UI는 기능은 좋은데, 토픽 하나 열어보려고 해도 Docker 띄우고 서버 배포부터 해야 한다. 반대로 Offset Explorer처럼 설치형 프로그램은 설정 없이 바로 켜지지만 기능이 아쉽다. 매번 "이번엔 뭘로 열어볼까" 고민하다가, 그냥 내가 쓸 도구를 만들기로 했다.

내가 필요했던 건 클러스터 운영자용 대시보드가 아니라, Kafka 연동 코드를 짜는 개발자가 토픽을 까보고 테스트하는 용도의 가벼운 클라이언트였다. 그래서 설치형 데스크톱 앱으로 KafkaPilot을 만들었다.

특히 실시간 위치 데이터(자율주행, 스마트시티, BIS, C-ITS 쪽)를 다루다 보면, 웹 대시보드가 준비되기 전에 "좌표 데이터가 제대로 들어오고 있나"부터 눈으로 확인해야 할 때가 많다. 그 순간을 위해 지도 뷰어를 아예 기본 기능으로 넣었다.

어떤 도구인가

만들면서 방향이 조금씩 분명해졌다. KafkaPilot은 단순 조회 도구가 아니라, 운영 이슈 재현 · 메시지 분석 · 테스트 데이터 생성 · 좌표 데이터 디버깅을 한 곳에서 처리하는 로컬 데스크톱 워크벤치를 목표로 하고 있다. 지금(2.0.x) 기준으로 아래 축들이 이미 핵심 흐름에 들어와 있다.

  • Consume: Offset/Time/Live 모드, 대량 그리드 가상화, Value Columns, CSV Export, Live Record
  • Message Replay: 단건/배치 Replay, 동적 필드 치환, 진행률 표시가 있는 백그라운드 Job
  • Produce: 단건/Interval 발행, 동적 템플릿, 발행 전 Preview, 토픽별 템플릿 저장
  • Consumer Groups: Lag 상세 조회, Offset Reset 미리보기, 활성 그룹 보호
  • Map Viewer: 독립 지도 창, 좌표 필드 매핑, 좌표계 변환, 차량 마커·Trail·Follow 모드
  • Avro: Schema Registry 기반 Confluent wire-format 디코딩, 수동 스키마 등록/인코딩
  • Workspace: Split Pane, Quick Search, 한/영 UI, 단축키 커스터마이징

주요 기능

Split Pane — 토픽 두 개를 나란히 열어서 각각 독립적으로 consume/produce할 수 있다. 요청 토픽과 응답 토픽을 동시에 보거나, DLQ를 메인 토픽 옆에 띄워두고 지켜볼 때 유용하다.

Split Pane

Map Viewer — GPS/좌표가 담긴 페이로드를 실시간 지도로 시각화한다. 토픽별로 위도/경도/heading/속도 같은 JSON 경로를 매핑할 수 있고, WGS84·한국 TM(EPSG:5186)·UTM 52N 좌표계 변환도 지원한다. 차량 마커는 진행 방향에 맞춰 회전하고, 최근 이동 경로(trail)도 그려준다. 좌표가 튀는 이상치(outlier)를 설정하고 화면에 따로 표시할 수도 있어서, 실제 GPS 노이즈인지 파싱 버그인지 구분하기 편하다.

Map Viewer

Value Columns — Message Inspector 트리에서 vehicleId, status, latitude 같은 특정 JSON 경로를 클릭 한 번으로 Consume 그리드의 전용 컬럼으로 고정할 수 있다. 선택은 토픽별로 유지되고 CSV export에도 그대로 포함된다.

Value Columns

Message Replay — 소비한 메시지를 다른 서버/토픽으로 그대로 재전송한다. 단일 메시지는 페이로드를 직접 수정해서 보낼 수 있고, 배치 재전송은 ${uuid}, ${seq:1..100} 같은 동적 토큰으로 필드를 덮어쓸 수 있다. 운영 이슈를 개발 환경에서 재현하거나 클러스터 간 메시지를 옮길 때 쓴다.

Message Replay

Consumer Group Offset Reset — 파티션 선택 → 미리보기(대상 오프셋과 차이 확인) → RESET을 직접 타이핑해서 확인하는 3단계 안전장치를 거친다. 컨슈머 그룹에 활성 멤버가 있으면 실행 자체가 막힌다.

Avro / Schema Registry — Confluent wire-format으로 인코딩된 메시지를 Schema Registry에서 스키마를 받아와 자동으로 디코딩한다. 레지스트리에 등록 안 된 토픽은 수동으로 스키마를 지정해서 디코딩·인코딩 둘 다 가능하다.

설치 방법

Windows/macOS용 데스크톱 앱이라 서버나 Docker가 필요 없다. GitHub 릴리즈에서 받아서 설치하면 끝.

직접 빌드하려면:

npm ci
npm run release:win   # Windows
npm run release:mac   # macOS (맥에서만 빌드 가능)

사용법

먼저 Server Profile에 브로커 주소를 등록한다. SSL/TLS, SASL/OAUTHBEARER, Schema Registry는 전부 선택 사항이고, 저장 전에 Test 버튼으로 Kafka Admin 연결을 미리 확인할 수 있다.

Consume은 세 가지 모드를 지원한다 — 특정 오프셋부터 읽는 Offset, 시간 범위로 조회하는 Time, 그리고 커밋된 그룹 오프셋을 건드리지 않고 최신부터 스트리밍하는 Live. 1만 건이 넘어가면 자동으로 페이지네이션되고, Key/Value는 Text·JSON·Hex·Base64로 바꿔가며 볼 수 있다. 고처리량 토픽을 오래 관찰해야 할 땐 Live Record로 전체 데이터를 메모리에 안 올리고 JSONL 파일로 바로 스트리밍해서 기록한다.

Produce는 단일 메시지 발행과 Count/Duration 조건의 Interval 발행을 지원하고, Key/Header/Value 어디에든 동적 필드 토큰(${uuid}, ${random:1..100}, ${date:yyyy-MM-dd HH:mm:ss} 등)을 쓸 수 있다. 보내기 전에 Produce Preview로 전체 페이로드를 미리 렌더링해서, 문법이 잘못됐으면 Interval 작업이 아예 시작되지 않도록 막아준다.

앞으로

지금은 다음 순서로 고도화를 생각하고 있다.

  1. Saved Consume Presets — 서버/토픽별로 자주 쓰는 Consume 조건(모드, 필터, Value Columns, Map 필드 매핑까지)을 통째로 저장했다가 한 번에 복원
  2. Field Statistics — 소비한 메시지 샘플에서 필드별 출현율, 타입 분포, null 비율 같은 통계를 뽑아서 Value Columns 후보를 추천
  3. Schema Registry Browser — 등록된 스키마 목록/버전을 UI에서 바로 탐색
  4. 그다음으로 Produce Scenario Runner, Map Viewer Playback(차량 이동 재생), Topic/Group Health Dashboard 순으로 검토 중이다.

혼자 쓰려고 만든 도구인데 GitHub에 올려두니 스타도 몇 개 달렸다. 비슷한 고민 하는 사람이 있다면 레포에서 바로 받아볼 수 있다.

#kafka#electron#desktop-app

댓글