03. MVP Scope

MVP 단계는 종료되었다. 이 문서는 최초 프로토타입이 다룬 범위의 역사적 기록으로 남겨둔다. 지금 무엇이 구현되어 있는지(현재 상태)는 docs/00-status.md를 참고한다.

목적

최초 프로토타입에서 "무엇을 구현했고, 무엇을 의도적으로 제외했는지"를 명확히 한다.

범위

Java Agent, Collector, Storage, REST API, Console을 end-to-end로 동작하는 수준까지 구현한다.

설계

포함된 것

1. Java Agent (agent/java-agent)
   • -javaagent로 주입, premain 진입점
   • Servlet 요청(HttpServlet#service) 단위로 Trace 생성
   • Trace ID 생성, Method/URI/Status/소요시간/예외 여부/요청 IP 수집
   • 요청/응답 헤더 수집 (옵트인, 민감 헤더 블랙리스트 redaction)
   • 내부 Queue + 백그라운드 sender thread + shutdown hook을 통한 비동기 전송
   • Collector 장애/타임아웃 시 애플리케이션에 영향 없음 (드롭 정책)
2. Collector (collector)
   • POST /api/v1/ingest/traces ingest API
   • 요청 검증 (jakarta.validation)
   • H2(파일 모드) 저장, Repository/Adapter로 storage 구현 분리
   • 조회 API: 서비스 목록, 서비스 요약(트래픽/평균 응답시간/에러율), URI별 통계, Trace 목록/상세
3. 예제 애플리케이션 (examples/example-app)
   • Agent를 실제로 붙여서 확인할 수 있는 최소 Spring Boot 앱
4. Console (console)
   • React + TypeScript + Vite, read-only 조회 화면 4종(서비스 목록/요약/URI 통계/Trace 목록·상세)
   • MVP에서는 독립 dev 서버로만 실행, Collector REST API를 CORS로 직접 호출

진행 중 (MVP 확장)

• 분산 트레이싱(Span 구조): common 모듈의 @ApmxTrace 어노테이션을 붙인 메서드만 opt-in으로 계측한다 (자동 전수 계측 아님 - AGENTS.md 13.2 "상용 APM 수준 복잡 기능 금지" 준수). 계측된 메서드는 현재 활성화된 HTTP Trace 아래 자식 Span으로 기록되며, 인자값은 안전한 타입(String/Number/Boolean/Character)만 값으로, 그 외 객체는 클래스명만 기록한다 (docs/04-agent-design.md "메서드 호출 스택(Span) 계측" 참고).

제외된 것 (다음 단계 TODO)

• Console 정적 빌드 배포 (Collector 등에 통합) - MVP는 독립 dev 서버만 지원
• PostgreSQL 실제 연동 검증 (구조만 준비, MVP 기본값은 H2)
• Python/Node.js Agent
• Batch(다건) ingest API - 현재는 Trace 1건당 1 HTTP 요청 (단, 하나의 Trace에 속한 여러 Span은 같은 요청에 함께 포함된다)
• 재시도 로직, Circuit Breaker

예시

로컬 실행 결과 예시

curl http://localhost:8080/api/v1/services
# ["example-app"]

curl http://localhost:8080/api/v1/services/example-app/summary
# {"serviceName":"example-app","totalCount":4,"avgDurationMs":51.25,"errorCount":2,"errorRate":0.5}

TODO

• Console 정적 빌드 배포 옵션 검토 (docs/08-console-design.md)
• Batch ingest API 추가 여부 검토
• PostgreSQL 프로파일로 실제 구동 검증