본문으로 건너뛰기

Java Helper

Java Helper는 애플리케이션의 라이브러리를 자동으로 분석하여 최적의 weaving 설정을 생성하는 CLI 도구입니다. Java 애플리케이션에서 사용하는 프레임워크나 오픈소스 라이브러리를 와탭 에이전트가 추적하려면 weaving 설정이 필요합니다. Java Helper는 에이전트 패키지에 whatap.javahelper.jar로 포함되어 있으며, JDK 8 이상에서 동작합니다.

weaving 옵션을 직접 지정하려면 수동 설정 문서를 참조하세요.

지원 포맷​

JAR, Spring Boot Fat JAR, Maven Shade JAR, WAR 포맷을 지원합니다. EAR은 루트 레벨 JAR 모듈까지 분석합니다.

Java Helper 명령어​

java -jar whatap.javahelper.jar conf generate <입력> [옵션]

입력​

InputDescriptionExample
<JAR 경로>JAR 파일을 직접 지정하여 분석/app/myapp.jar
--pid <PID>실행 중인 Java 프로세스의 PID로 분석--pid 12345

JAR 경로와 --pid 중 하나는 반드시 지정해야 합니다.

Options​

OptionDescriptionDefault
-o <파일>매칭 결과를 whatap.conf 파일로 저장미지정 시 화면 출력만
-v분석 과정의 상세 로그 출력 (verbose)off

사용 시나리오​

신규 에이전트 설치​

JAR 파일 경로를 지정하여 whatap.conf를 바로 만듭니다.

java -jar whatap.javahelper.jar conf generate /app/myapp.jar -o whatap.conf

생성된 whatap.conf 예시:

whatap.conf
weaving=spring-boot-3.2,tomcat10,mongodb-4.8

# 추천 모듈 (필요시 주석 해제)
#weaving+=,reactor-kafka-1.3
#weaving+=,resilience4j

만든 파일에 라이선스 키와 서버 정보를 추가하면 설치가 완료됩니다.

운영 중 설정 점검​

실행 중인 프로세스를 PID로 분석하여 매칭 결과를 확인합니다.

java -jar whatap.javahelper.jar conf generate --pid 12345

출력 예시:

==========================================
  WhaTap Weaving Module 매칭 결과
==========================================

  탐지된 라이브러리: 25개
  매칭된 모듈:      8개
  버전 불일치:      1개
  자동 포함:        3개

  LIBRARY                   VERSION   WEAVING MODULE        STATUS
  spring-boot               3.2.5     spring-boot-3.2       MATCHED
  mongodb-driver-sync       4.11.1    mongodb-4.8           MATCHED
  lettuce-core              6.3.2     lettuce-6.1           AUTO
  ...

현재 whatap.conf와 비교하여 빠진 모듈이 있는지 확인할 수 있습니다. 설정 파일로 저장하려면 -o 옵션을 추가하세요.

라이브러리 업그레이드 후​

Spring Boot 버전 업그레이드 등 라이브러리 변경 시, 업그레이드한 JAR로 다시 분석하면 새 weaving 설정을 받을 수 있습니다.

java -jar whatap.javahelper.jar conf generate /app/myapp-upgraded.jar

매칭 상태​

StatusDescriptionAction
MATCHEDartifactId, groupId, version 모두 일치하여 weaving 모듈 적용 가능자동 적용
AUTO자동 포함 대상 모듈 (weaving 설정 없이 기본 적용)자동 적용
VERSION_MISMATCH라이브러리는 탐지되었으나 버전이 weaving 모듈 지원 범위 밖에이전트 업데이트 확인
NO_MATCHweaving 레지스트리에 해당하는 모듈이 없음해당 없음

참고​

의존성 분석 방식​

JAR 파일에서 라이브러리 버전을 확인하는 과정은 3단계 우선순위로 동작합니다. 상위 단계에서 추출한 정보는 하위 단계에서 덮어쓰지 않습니다.

  1. Maven pom.properties: JAR 내부의 META-INF/maven/{groupId}/{artifactId}/pom.properties에서 groupId, artifactId, version을 추출합니다. 가장 정확한 방법입니다.

  2. MANIFEST.MF: pom.properties가 없으면 META-INF/MANIFEST.MF에서 Implementation-Title, Implementation-Version 등 표준 속성을 읽습니다.

  3. 파일명 파싱: 위 두 방법이 실패하면 JAR 파일명에서 추론합니다. (예: jackson-databind-2.14.0.jar → version="2.14.0")

최종 수정: