Java Agent 설치

모든 관련 문서를 확인했습니다. 이제 상세한 답변을 작성합니다.

---

exemONE Java Agent 설치 방법 및 설정 상세 가이드

참고 문서:

• Java Agent 지원 환경
• Java Agent 필요 Port
• Java Agent On-Premise 설치
• Java Agent InitContainer 방식
• Java Agent Dockerfile Rebuild 방식
• 특정 클래스/메서드 필터링 가이드 (local.advice)
• 특정 메서드 호출 기반 트랜잭션 수집 설정 (ext.jar)
• EtoE/트랜잭션 시작점 수집 설정 (x.advice)
• Call Tree 타임바 모니터링
• Java CPU 사용량 계산 방법
• Tomcat shutdown 시 hang 현상
• 모듈별 사용 Port

---

1. 모듈 설명

exemONE Java Agent(exem-java-agent)는 Java VM 기반의 프로세스에 agent 형태로 구동하여 JVM 프로세스에서 실행되는 Application(WAS)을 추적하여 Receiver로 전송하는 모니터링 에이전트입니다.

수집 데이터: 트랜잭션, SQL, Call Tree, Exception, Active Session, WAS CPU/Memory 사용량 등

---

2. 지원 환경

2-1. Java 버전

항목	지원 버전
JDK	8 이상, 23 이하

2-2. 애플리케이션 서버

WAS	지원 버전
Tmaxsoft JEUS	7.x 이상
Oracle WebLogic	12.x 이상
Apache Jakarta Tomcat	8.x 이상
IBM WebSphere	8.5.x 이상
Red Hat JBoss	7.x 이상
Undertow	지원

2-3. 지원 데이터베이스 (SQL 추적)

DB 종류
Oracle Database
PostgreSQL
MySQL
MariaDB
Microsoft SQL Server
DB2
Informix
Sybase
SAP HANA
Altibase
PPAS
CUBRID
Tibero
MongoDB
Apache Cassandra
ClickHouse

---

3. 통신 포트

출발지	도착지	Type	Port	내용
모니터링 대상 장비 (WAS)	exemONE 수집 서버 (Receiver)	TCP	9010	범용 TCP 요청 및 응답

exem-java-agent는 TCP를 이용하여 Receiver와 통신합니다. 모니터링 대상 서버에서 수집 서버 방향으로 9010 포트가 반드시 개방되어 있어야 합니다.

---

4. 설치 방법 (3가지)

exemONE Java Agent는 환경에 따라 3가지 설치 방식을 제공합니다.

설치 방식	적합 환경	특징
On-Premise 설치	물리 서버, VM 환경	tar.gz 압축 해제 + JVM 옵션 설정
InitContainer 방식	Kubernetes 환경	Application 재빌드 없이 Pod initContainer로 설치
Dockerfile Rebuild 방식	Kubernetes / Docker 환경	Dockerfile에 agent 포함하여 이미지 빌드

---

4-1. On-Premise 설치 (물리 서버 / VM 환경)

단계 1. 패키지 압축 해제

tar xvzf EXEM-JAVA-AGENT-[version].tar.gz

단계 2. Receiver 연결 설정

/home/exem/java/cfg/agent/java.conf 파일에서 receiver_addr을 exemONE 수집 서버 IP:9010으로 설정합니다.

단계 3. JVM 옵션 설정

WAS 시작 스크립트에 아래 JVM 옵션을 추가합니다. WAS 재기동 후 적용됩니다.

Tomcat 예시 ($CATALINA_HOME/bin/catalina.sh 또는 setenv.sh):

JAVA_OPTS="$JAVA_OPTS -Dexem.groupid=default -Dexem.agent.name=tomcat8_test -Dexem.bid=$(hostname) -javaagent:/home/exem/java/lib/exem-java-agent.jar"

JVM 옵션 상세 설명

JVM 옵션	설명	비고
-Dexem.groupid	exemONE 화면 > 환경설정 > 애플리케이션 > WAS 그룹의 이름
-Dexem.agent.name	모니터링 할 WAS 이름 (exemONE 화면에 표시되는 이름)
-Dexem.bid	exem-host-agent와 연결 key (리소스 수집용, 보통 hostname)
-javaagent	exem-java-agent.jar 파일의 절대 경로	필수

JDK 9 이상 추가 옵션 (필수)

JDK 1.9 이상 버전부터 Java 모듈화로 인해 CPU/Memory 사용량 수집을 위해 아래 옵션 추가가 필요합니다:

--add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED

HTTP 외부호출 데이터 수집 추가 옵션 (선택)

Java 기본 패키지를 이용한 HTTP 외부호출 데이터 수집이 필요한 경우:

--add-opens=java.base/sun.net.www.http=ALL-UNNAMED
--add-opens=java.base/sun.net.www.protocol.http=ALL-UNNAMED
--add-exports=java.base/sun.net.www=ALL-UNNAMED

전체 JVM 옵션 예시 (JDK 9+ 환경)

JAVA_OPTS="$JAVA_OPTS -Dexem.groupid=default -Dexem.agent.name=tomcat8_test -Dexem.bid=$(hostname) -javaagent:/home/exem/java/lib/exem-java-agent.jar --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED"

---

4-2. Kubernetes InitContainer 방식

Application을 재빌드하지 않고, Pod initContainer 방식으로 agent를 설치하는 방법입니다.

사전 조건

• kubectl 명령어를 수행할 수 있는 환경 접속 필요
• 설치 대상 application deployment.yaml 파일에 exemone 환경변수 추가 필요

설치 패키지 구성

• exem-java-agent-inst_x.x.x.x.tgz : initContainer용 Docker 이미지
• configmap.yml : 환경변수(exem-java-agent-env) 및 설정파일(exem-java-agent-config) 정의

단계 1. ConfigMap 생성

exem-java-agent-env (환경변수 ConfigMap):

apiVersion: v1
kind: ConfigMap
metadata:
  name: exem-java-agent-env
  namespace: {{namespace 지정}}
data:
  startup_opt: "-javaagent:/exem/java/lib/exem-java-agent.jar -Dexem.run.on.container=true"

exem-java-agent-config (설정파일 ConfigMap):

apiVersion: v1
kind: ConfigMap
metadata:
  name: exem-java-agent-config
  namespace: {{namespace 지정}}
data:
  java.conf: |
    RECEIVER_ADDR={{수집서버 주소 지정}}
  db.alias: |
    # ip.port.databasename=alias
  local.advice: |
    ### 작성방법
    # 패키지 및 클래스 구분자는 slash(/)이며 클래스와 메소드는 dot(.)으로 구분한다.
    # 강제포함은 exclamation mark(!), 제외는 dash(-)를 접두사로 붙여 표기한다.
    !javax/servlet/http/HttpServlet.*

단계 2. Deployment YAML에 exem-java-agent 설정 추가

기존 application deployment.yaml에 아래 하이라이트 부분을 추가합니다:

spec:
  template:
    spec:
      volumes:
        # ... (기존 볼륨)
        # exem java agent 설치 대상 볼륨
        - name: exem-volume
          emptyDir: {}
        # java agent 설정 파일 볼륨
        - name: config-volume-java-agent
          configMap:
            name: exem-java-agent-config
      
      initContainers:
        - name: install-exem-java-agent
          image: exem-java-agent-inst:x.x.x
          imagePullPolicy: IfNotPresent
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
            - name: config-volume-java-agent
              mountPath: "/exem-config"
              readOnly: true
      
      containers:
        - name: # application name
          # ... (기존 설정)
          volumeMounts:
            - name: exem-volume
              mountPath: /exem
          env:
            - name: EXEM_GROUP_ID
              value: "{{group id 지정}}"
            - name: EXEM_RUN_ON_CONTAINER
              value: "true"
            - name: EXEMWID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.uid
            - name: EXEM_JAVA_AGENT_NAME
              value: "{{agent name 지정}}"

환경변수 설명

환경변수	설명	비고
EXEM_GROUP_ID	WAS Group ID	미설정 시 "default"로 설정
EXEM_RUN_ON_CONTAINER	컨테이너 환경 동작 여부	컨테이너 환경: true, On-premise: false(기본값)
EXEMWID	컨테이너 연계를 위한 key	EXEM_RUN_ON_CONTAINER=true 설정 시에만 적용
EXEM_JAVA_AGENT_NAME	WAS name	v3.0.24.16부터 환경변수/config 파일 입력 지원
EXEM_RECEIVER_ADDR	수집서버(receiver) 주소 (ip:port)	v3.0.24.16부터 환경변수 입력 지원

환경변수 우선순위

각 설정은 JVM 옵션, 환경변수, config 파일 3가지로 설정 가능하며, 우선순위는 다음과 같습니다:

설정	우선순위 (높음 → 낮음)
GROUP_ID	-Dexem.groupid= > EXEM_GROUP_ID (환경변수) > config 파일
RUN_ON_CONTAINER	-Dexem.run.on.container= > EXEM_RUN_ON_CONTAINER (환경변수) > config 파일
AGENT_NAME	-Dexem.agent.name= > EXEM_JAVA_AGENT_NAME (환경변수) > config 파일(EXEM_AGENT_NAME)
RECEIVER_ADDR	-Dexem.receiver.addr= > EXEM_RECEIVER_ADDR (환경변수) > config 파일(RECEIVER_ADDR)

단계 3. Tomcat 사용 시 (Optional)

제공된 exem-java-agent-env 파일을 이용하여 CATALINA_OPTS에 java agent 옵션을 적용합니다.

---

4-3. Dockerfile Rebuild 방식

설치 대상 Application Build Dockerfile에 exemONE agent 옵션을 넣고 함께 빌드하여 배포하는 방식입니다.

단계 1. 패키지 업로드 및 압축 해제

Application 이미지를 재빌드하는 서버에 패키지를 업로드합니다.

tar -xvzf /EXEM-JAVA-AGENT-3.x.x.tar.gz

단계 2. 압축 파일 삭제

rm -f EXEM-JAVA-AGENT-3.x.x.tar.gz

단계 3. Dockerfile에 exemONE 관련 명령어 & 환경변수 추가

COPY {패키지_경로}/exem {애플리케이션내경로}/exem
ENV EXEM_GROUP_ID={default}
ENV EXEM_RECEIVER_ADDR={IP:PORT}
ENV JAVA_OPTS={JAVA_OPTS}

예시:

COPY /home/exemone/exem /home/exem
ENV EXEM_GROUP_ID=default
ENV EXEM_RECEIVER_ADDR=10.10.40.120:9010
ENV JAVA_OPTS="$JAVA_OPTS -Dexem.groupid=$EXEM_GROUP_ID -Dexem.agent.name=tomcat_test -javaagent:/exem/java/lib/exem-java-agent.jar -Dexem.run.on.container=true"

단계 4. Dockerfile 빌드

docker build --tag {docker user id}/{docker repository name}

단계 5. Deployment YAML에 exemONE 환경변수 추가

단계 6. Deployment 적용

kubectl apply -f app-deployment.yaml

---

5. 설정 파일 (java.conf) 상세

5-1. 파일 위치

{설치 경로}/exem/java/cfg/agent/java.conf

5-2. 주요 설정 항목

설정 항목	설명	예시
RECEIVER_ADDR	exemONE 수집 서버 주소 (IP:Port)	10.10.40.120:9010

5-3. 부가 설정 파일

파일	위치	용도
java.conf	/exem/java/cfg/agent/java.conf	Receiver 연결 및 기본 설정
local.advice	/exem/java/cfg/local.advice	특정 클래스/메서드 필터링 (수집 대상 포함/제외)
x.advice	/exem/java/cfg/x.advice	EtoE 또는 트랜잭션 시작점 수집을 위한 method weave 정보 설정
db.alias	/exem/java/cfg/agent/db.alias	DB alias 설정
cfg.reload	/exem/java/cfg/agent/cfg.reload	설정 동적 적용 트리거 파일

---

6. 주요 설정 파일 활용 가이드

6-1. local.advice — 특정 클래스/메서드 필터링

특정 클래스나 메서드를 수집 대상에 포함 또는 제외하기 위한 파일입니다.

작성 규칙:

• 패키지 및 클래스 구분자는 slash(/)이며 클래스와 메소드는 dot(.)으로 구분
• 강제포함: exclamation mark(!) 접두사
• 제외: dash(-) 접두사
• 포함: 접두사 없음
• 우선순위: 강제포함 > 제외 > 포함
• 와일드카드 문자(*)를 포함해 startWith, endWith 연산 수행 가능

작성 예시:

### 작성예시
# com/inzent.*
# -com/inzent/igate.*
# !com/inzent/igate/util.*

!javax/servlet/http/HttpServlet.*
!test_InterMax/MultipleSQL.*

동적 적용 방법:

설정 변경 후 WAS 재기동 없이 적용하려면 cfg.reload 파일을 touch합니다:

touch /exem/java/cfg/agent/cfg.reload

단, 로드된 전체 클래스를 대상으로 한 설정은 안정성 문제로 인해 동적 적용되지 않습니다.

6-2. x.advice — EtoE/트랜잭션 시작점 수집 설정

EtoE 또는 트랜잭션 시작점을 수집하기 위한 method weave 정보를 설정하는 파일입니다.

적용 방법:

/exem/java/cfg/ 폴더 안에 x.advice 파일을 편집하여 class 경로와 method 정보를 추가합니다.

예시 (Spring HTTP 외부 호출 추적):

httpCall=org/springframework/http/client/AbstractClientHttpRequest.execute()Lorg/springframework/http/client/ClientHttpResponse;

---

7. exemONE 웹 UI에서 WAS 그룹 설정

Java Agent 설치 후 exemONE 화면에서 WAS 그룹을 확인/설정합니다.

7-1. Call Tree 타임바 설정 (Optional)

트랜잭션의 콜트리 리스트를 타임라인으로 시각화할 수 있습니다.

설정 경로: Setting > Application > Edit WAS Group > Config

USE_METHOD_SEQ = true로 설정

모니터링: Application > WAS Detail > Transaction Detail > Call Tree 탭

---

8. WAS CPU Usage 수집 스펙

Java JMX API를 활용하여 현재 JVM 프로세스가 점유하고 있는 CPU 사용률을 계산합니다.

수집 방법:

1. Java JMX API를 통해 OperatingSystemMXBean 객체 호출
2. getProcessCpuLoad() 메서드로 JVM 프로세스의 CPU 사용률(0.0 ~ 1.0) 획득
3. 반환값에 100을 곱하여 백분율(%) 형태로 변환
4. CPU 전체 코어(Core) 100% 기준으로 계산

JDK 9 이상에서는 --add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED 옵션이 필수입니다.

---

9. 설치 확인

9-1. Agent 로그 확인

tail -f {설치경로}/exem/java/logs/exem-java-agent[버전].log

정상 기동 시 아래와 같은 로그가 출력됩니다:

[INFO ] [main] LOAD [com.exemone.ext.XM_BOUND_X]
[INFO ] [main] LOAD [com.exemone.ext.XM_RT]
[INFO ] [main] EXEM AGENT EXT [...]
[INFO ] [main] 3.0.23

9-2. exemONE 웹 UI 확인

• Application > WAS 기본 뷰에서 해당 WAS가 Active 상태인지 확인

Active가 아닌 경우: 수집서버 ↔ WAS 서버 간 네트워크 및 포트(9010) 방화벽 확인 필요

---

10. 주의사항 및 알려진 이슈

10-1. Tomcat shutdown 시 hang 현상

• 현상: tomcat shutdown.sh 실행 시 exem-java-agent.jar가 JAVA_OPTS에 설정되어 있으면 hang 발생
• 원인: exemONE 모듈간 통신 라이브러리 클래스 초기화 시 logging manager에 대한 lock 경합
• 해결 방법:
  1. java-agent v3.0.24.16 이상으로 패치 (기본 옵션으로 수정됨)
  2. 패치가 어려울 경우 JAVA_OPTS 대신 CATALINA_OPTS로 agent 옵션 추가

10-2. JDK 9+ 필수 옵션 누락

JDK 9 이상에서 --add-opens 옵션을 추가하지 않으면 CPU/Memory 사용량 수집이 불가합니다. 반드시 아래 옵션을 추가하세요:

--add-opens jdk.management/com.sun.management.internal=ALL-UNNAMED

10-3. 콜트리 미수집

트랜잭션은 수집되나 콜트리가 미수집되는 경우, 지원하지 않는 프레임워크 사용이 원인일 수 있습니다. 제품기술팀에 문의하세요.

10-4. 컨테이너 환경 필수 설정

Kubernetes/Docker 환경에서는 반드시 아래 설정이 필요합니다:

• -Dexem.run.on.container=true 또는 EXEM_RUN_ON_CONTAINER=true
• EXEMWID 환경변수 설정 (Pod UID)

10-5. 패키지 파일 준비

설치 파일(EXEM-JAVA-AGENT-[version].tar.gz)은 제품기술팀에 문의하여 준비합니다.