Java 애플리케이션을 코드 수정 없이 관측하는 오픈소스 APM 플랫폼
Seeker는 JVM에 Java Agent를 부착해 분산 trace, span event, JVM/시스템 metric을 수집하고,
Kafka와 ClickHouse 기반 파이프라인을 통해 서비스 토폴로지와 성능 지표를 대시보드에서 확인할 수 있게 만드는 APM 프로젝트입니다.
Seeker는 분산 환경에서 실행되는 Java 애플리케이션의 요청 흐름을 추적하고,
어느 서비스에서 지연이나 오류가 발생했는지 빠르게 파악하기 위한 Application Performance Monitoring 시스템입니다.
대상 애플리케이션에는 -javaagent 옵션만 추가하면 됩니다.
애플리케이션 코드를 직접 수정하지 않고도 HTTP 요청, 외부 호출, JDBC 쿼리, 서비스 메서드 실행 흐름을 수집합니다.
-
비침투 Java Agent
- JVM에
-javaagent로 부착 - Byte Buddy 기반 바이트코드 계측
- 애플리케이션 코드 수정 없이 trace 수집
- JVM에
-
분산 추적
- W3C Trace Context 기반 trace 전파
- 서비스 간 호출에서 동일 trace 유지
- root span, child span, span event 구조로 요청 흐름 표현
-
실시간 수집 파이프라인
- Agent가 gRPC로 Collector에 데이터 전송
- Collector가 Kafka topic으로 trace 이벤트 발행
- ClickHouse가 Kafka Engine과 Materialized View로 분석 테이블 적재
-
대시보드
- 서비스 토폴로지 시각화
- TPS, 평균 지연, 오류율 조회
- p90, p95, p99 latency 지표 제공
flowchart LR
App[Java Application] -->|javaagent| Agent[seeker-agent]
Agent -->|gRPC| Collector[seeker-collector]
OTel[OpenTelemetry / Envoy] -->|OTLP gRPC| Collector
Collector -->|trace-data / agent-events| Kafka[(Kafka)]
Kafka -->|Kafka Engine| ClickHouse[(ClickHouse)]
ClickHouse -->|JDBC| Web[seeker-web]
Web -->|REST API| Client[seeker-client]
Seeker는 역할별로 분리된 seeker-* 레포 패턴으로 구성되어 있습니다.
| Repository | 역할 | 설명 |
|---|---|---|
seeker-agent |
Java Agent | JVM에 부착되어 Tomcat, HttpClient, JDBC, 서비스 메서드 등을 추적하고 Collector로 데이터를 전송합니다. |
seeker-collector |
Collector | Agent와 OTLP 클라이언트에서 trace 데이터를 수신하고 Kafka로 발행합니다. |
seeker-clickhouse |
Storage Schema | Kafka 이벤트를 ClickHouse 분석 테이블로 적재하기 위한 테이블, Kafka Engine, Materialized View SQL을 관리합니다. |
seeker-web |
Dashboard API | ClickHouse를 조회해 topology, latency, error rate 등 대시보드 데이터를 REST API로 제공합니다. |
seeker-client |
Web UI | React 기반 대시보드로 서비스 토폴로지와 성능 지표를 시각화합니다. |
- Java 애플리케이션에
seeker-agent를-javaagent로 부착합니다. - Agent가 요청 진입점에서 trace와 root span을 생성합니다.
- 내부 메서드, JDBC, 외부 HTTP 호출을 span event로 기록합니다.
- 외부 HTTP 호출에는 W3C trace header를 주입해 다음 서비스로 trace를 전파합니다.
- Agent는 수집한 데이터를 gRPC로
seeker-collector에 전송합니다. - Collector는 trace, span, span event, agent lifecycle 이벤트를 Kafka로 발행합니다.
- ClickHouse는 Kafka topic을 소비해 분석용 테이블에 데이터를 적재합니다.
- Web API와 Client가 이 데이터를 조회해 대시보드로 보여줍니다.
| 영역 | 기술 |
|---|---|
| Agent | Java 17, Gradle, Byte Buddy, gRPC |
| Collector | Java 17, Spring Boot WebFlux, gRPC, Kafka |
| Storage | Kafka |
| API Server | Spring Boot, JDBC, ClickHouse JDBC |
| Client | React, TypeScript, Vite, TanStack Query, Tailwind CSS |
- HTTP 요청 단위 root span 생성
- 서비스 간 trace context 전파
- span, span event 기반 상세 호출 흐름 기록
- Tomcat request
- Apache HttpClient 외부 호출
- JDBC PreparedStatement
- 설정한 base package 하위 service method
- JVM/시스템 metric 수집 구조
- Kafka topic 기반 이벤트 스트리밍
- ClickHouse Kafka Engine으로 topic 직접 소비
- Materialized View로 event type별 테이블 분기
- 시간 범위 기반 topology, latency, error query
- 서비스 토폴로지 그래프
- agent별 요청 수, 오류 수, 오류율
- 평균 지연 시간
- p90, p95, p99 latency
- trace, error, report, alert 화면 확장 구조