Pinpoint 분석 #1

Pinpoint Build Onboarding Guide

이 문서는 Pinpoint 오픈소스를 처음 다루는 개발자가 "이 프로젝트는 무엇으로 빌드되고, 어떤 식으로 접근해야 하는가"를 빠르게 이해하도록 돕기 위한 가이드다.

1. 한눈에 보는 빌드 구조

• 루트 빌드 도구는 Maven Wrapper(./mvnw)다.
• 프로젝트는 pom.xml 기준의 멀티모듈 Maven 레포다.
• 백엔드 모듈은 주로 Java로 빌드된다.
• 웹 프론트엔드는 web-frontend 모듈에서 별도로 빌드되며, Maven 안에서 frontend-maven-plugin으로 Node/Yarn 작업을 실행한다.
• 일부 실행 모듈은 spring-boot-maven-plugin으로 실행 가능한 JAR를 만든다.
• 일부 모듈은 jib-maven-plugin 설정도 포함하고 있어 컨테이너 이미지 빌드 경로도 갖고 있다.

핵심적으로 보면 이 레포는 다음 두 축으로 빌드된다.

• Java 멀티모듈 빌드: ./mvnw
• Frontend 빌드: web-frontend 내부에서 Yarn 기반 빌드, 하지만 실행은 Maven이 제어

2. 빌드 기술 스택

백엔드

• Maven Wrapper: ./mvnw
• Maven 멀티모듈 reactor 빌드
• Java 8, 11, 17 환경 변수 요구
• Spring Boot 3 계열 사용 모듈 존재
• JUnit / Surefire / Failsafe 기반 테스트 실행

프론트엔드

• frontend-maven-plugin
• Node.js v22.13.1
• Yarn v1.22.22
• 프론트엔드 산출물은 web-frontend 빌드 과정에서 생성

3. 왜 Java 버전이 여러 개 필요한가

루트 pom.xml은 공통 기본값으로 JAVA_8_HOME을 사용하고, web, web-starter, collector-starter, batch 같은 일부 모듈은 별도로 JAVA_17_HOME을 사용한다. 따라서 이 레포는 "Java 하나만 있으면 되는" 구조가 아니다.

최초 빌드 전에 다음 환경 변수를 준비하는 것이 안전하다.

export JAVA_HOME=/path/to/jdk
export JAVA_8_HOME=/path/to/jdk8
export JAVA_11_HOME=/path/to/jdk11
export JAVA_17_HOME=/path/to/jdk17

실제로 루트 빌드에는 환경 변수 존재 여부를 검사하는 Maven Enforcer 설정이 들어 있으므로, 값이 없으면 validate 단계에서 바로 실패한다.

4. 주요 모듈 감각 잡기

처음 보면 모듈 수가 많아서 압도되기 쉬운데, 운영 관점에서 자주 보는 축은 대략 이렇다.

• collector-starter: 수집 서버 시작 모듈
• web-starter: 웹 서버 시작 모듈
• batch: 배치 실행 모듈
• web: 웹 백엔드 본체
• web-frontend: 웹 UI 정적 리소스 빌드
• collector: collector 본체
• agent-module: 에이전트 및 플러그인 계열
• commons*: 공통 라이브러리
• uristat, inspector-module, log, exceptiontrace, otlpmetric, otlptrace: 기능 확장 모듈

중요한 점은 web-starter, collector-starter, batch가 단독 실행점에 가깝고, 실제 구현은 내부의 여러 모듈에 분산돼 있다는 점이다.

5. Maven 생명주기에서 자주 쓰는 명령

package

• 컴파일하고 테스트를 거쳐 산출물을 target/ 아래에 만든다.
• 같은 reactor 안에서만 쓸 거라면 보통 이것으로 충분하다.

install

• package가 하는 일을 모두 수행한 뒤 결과물을 로컬 Maven 저장소(~/.m2/repository)에 설치한다.
• 다른 프로젝트가 이 산출물을 의존성으로 참조해야 할 때 필요하다.

clean

• 기존 target/ 결과물을 지운다.
• 필요할 때만 쓰는 것이 좋다.
• 반복 개발 중 매번 clean을 붙이면 빌드 시간이 크게 늘어난다.

6. 이 레포에서 빌드 시간이 길어지는 이유

처음 보는 개발자가 체감하는 "왜 이렇게 오래 걸리지?"의 원인은 보통 아래 조합 때문이다.

• 루트에서 전체 멀티모듈 reactor를 다 빌드함
• 테스트를 함께 실행함
• web-frontend에서 Node/Yarn 설치와 프론트 빌드까지 함께 수행함
• 매번 clean install을 사용함

즉, 가장 느린 패턴은 대개 이런 식이다.

./mvnw clean install -DskipTests

이 명령은 레포 전체 모듈, 전체 의존, 프론트 빌드, 로컬 저장소 설치까지 넓게 수행하게 된다.

7. 처음 빌드할 때의 추천 전략

옵션 A. 웹 UI까지 포함한 "안전한 최초 빌드"

웹 화면까지 실제로 올려볼 예정이라면 프론트엔드 빌드를 포함하는 편이 낫다.

./mvnw -pl web-starter,collector-starter,batch -am package -DskipTests -T 1C

이 방식의 장점:

• 필요한 실행 모듈만 대상으로 삼는다.
• 그 모듈이 필요로 하는 의존 모듈은 -am으로 함께 빌드한다.
• 전체 레포를 다 돌리는 것보다 빠르다.
• install 대신 package를 써서 로컬 저장소 설치 비용을 줄인다.

옵션 B. 웹 UI 없이 백엔드만 빨리 확인하는 최초 빌드

웹 화면은 아직 안 띄우고 collector/batch 또는 백엔드 컴파일만 먼저 보고 싶다면 프론트엔드 빌드를 생략할 수 있다.

./mvnw -pl collector-starter,batch -am package -DskipTests -Dbuild.frontend.skip=true -T 1C

주의:

• web-starter를 실제로 실행할 계획이면 최초 빌드에서 build.frontend.skip=true는 조심해야 한다.
• 프론트 산출물이 없으면 웹 UI 정적 리소스가 비어 있거나 오래된 결과물을 참조할 수 있다.

8. -pl과 -am은 꼭 알아두기

이 레포에서 빌드 시간을 줄일 때 가장 중요한 옵션이다.

-pl

• project list
• 어떤 모듈만 reactor 대상에 포함할지 지정

예:

./mvnw -pl web-starter,collector-starter,batch ...

-am

• also make
• -pl로 지정한 모듈이 의존하는 다른 내부 모듈도 같이 빌드

이 둘을 함께 쓰면 "필요한 실행 모듈만 선택하되, 그 모듈이 기대하는 내부 라이브러리는 Maven이 알아서 같이 올리는" 형태가 된다.

9. 프론트엔드 스킵 옵션의 의미

루트 pom.xml에는 build.frontend.skip 프로퍼티와 동일 이름의 profile이 있고, web-frontend/pom.xml에서는 이 값을 frontend-maven-plugin과 assembly 단계의 skip 플래그로 연결하고 있다.

즉 다음과 같은 의미다.

-Dbuild.frontend.skip=true

• Node 설치 스킵
• Yarn install 스킵
• Yarn build 스킵
• 프론트엔드 assembly 스킵

영향 범위:

• collector-starter: 거의 영향 없음
• batch: 대체로 영향 없음
• web-starter: UI를 실제로 사용할 예정이면 영향 있음

10. 개발 중 빠른 반복 빌드 팁

매번 clean 하지 않기

반복 개발 중에는 우선 이렇게 시작하는 편이 낫다.

./mvnw -pl web-starter,collector-starter,batch -am package -DskipTests -T 1C

정말 산출물 꼬임이 의심될 때만 clean을 붙인다.

install보다 package 우선 고려

레포 안에서만 확인할 때는 package로 충분한 경우가 많다.

모듈 단위로 더 좁혀서 빌드하기

./mvnw -pl collector-starter -am package -DskipTests -T 1C
./mvnw -pl batch -am package -DskipTests -T 1C
./mvnw -pl web-starter -am package -DskipTests -T 1C

웹 UI가 필요 없으면 프론트 빌드 끄기

./mvnw -pl web-starter -am package -DskipTests -Dbuild.frontend.skip=true -T 1C

단, 이 경우 웹 실행 품질은 보장되지 않을 수 있다.

11. 자주 헷갈리는 점

Q. skipTests와 maven.test.skip는 같은가

비슷하지만 완전히 같지는 않다.

• -DskipTests: 테스트 실행만 건너뜀
• -Dmaven.test.skip=true: 테스트 컴파일과 실행을 더 넓게 건너뛸 수 있음

일반적인 개발용 빠른 빌드에는 -DskipTests를 우선 고려하는 편이 읽기 쉽다.

Q. 최초 빌드인데 프론트엔드 스킵해도 되는가

• collector-starter, batch 중심이면 괜찮을 수 있다.
• web-starter를 실제 실행해서 UI까지 확인할 예정이면 권장하지 않는다.

Q. 왜 install이 더 느린가

• package 결과물을 로컬 Maven 저장소에 추가로 설치하기 때문이다.

12. 추천 명령 모음

전체 레포를 정말 전부 빌드해야 할 때

./mvnw clean install -DskipTests

실무적으로 더 자주 쓸 가능성이 높은 명령

필요한 실행 모듈만:

./mvnw -pl web-starter,collector-starter,batch -am package -DskipTests -T 1C

collector + batch만 빠르게:

./mvnw -pl collector-starter,batch -am package -DskipTests -Dbuild.frontend.skip=true -T 1C

웹만 별도로:

./mvnw -pl web-starter -am package -DskipTests -T 1C

웹 백엔드만 대충 컴파일 확인:

./mvnw -pl web-starter -am package -DskipTests -Dbuild.frontend.skip=true -T 1C

13. 처음 들어온 개발자에게 추천하는 작업 순서

1. JAVA_HOME, JAVA_8_HOME, JAVA_11_HOME, JAVA_17_HOME를 먼저 맞춘다.
2. 루트 pom.xml의 모듈 목록을 보고 큰 구조를 이해한다.
3. 자신이 실제로 다룰 실행점이 web-starter, collector-starter, batch 중 무엇인지 정한다.
4. 전체 빌드 대신 -pl과 -am으로 필요한 부분만 빌드한다.
5. 웹 UI가 필요할 때만 프론트엔드 빌드를 포함한다.
6. 반복 개발에서는 clean install 대신 package 중심으로 짧게 돈다.

14. 문서만으로 판단하기 어려운 부분

이 레포는 빌드 자체와 실행 준비가 완전히 같은 문제는 아니다. 빌드는 성공해도 실제 구동에는 별도 인프라 설정이 추가로 필요할 수 있다.

예를 들면:

• Zookeeper 주소
• HBase/Pinot 같은 저장소 구성
• Spring profile 및 외부 설정 파일
• 로컬/개발용 데이터 소스 구성

따라서 "빌드 성공"과 "서비스 로컬 실행 성공"은 분리해서 보는 것이 좋다.

15. 가장 짧은 요약

• 이 프로젝트는 Maven 멀티모듈 + Java + Yarn 프론트엔드 혼합 빌드다.
• Java 8/11/17 환경 변수를 모두 준비하는 편이 안전하다.
• 전체 clean install은 느리다.
• -pl + -am + package가 개발 생산성을 크게 올린다.
• web-starter를 실제로 쓸 때는 프론트엔드 스킵 여부를 신중히 결정해야 한다.