Java Agent 설치

1. 모듈 설명​

exem-java-agent는 Java VM 기반 프로세스에서 실행되는 WAS의 트랜잭션, SQL, 예외, 리소스 사용량을 수집하여 ExemONE 수집 서버(Receiver)로 전송하는 모니터링 에이전트입니다.

2. 지원 환경​

3. 통신 포트​

4. 설치 방법​

환경에 따라 3가지 설치 방식을 지원합니다.

4-1. On-Premise 설치​

1. 패키지 압축 해제​

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

2. Receiver 연결 설정​

{설치 경로}/exem/java/cfg/agent/java.conf 파일의 RECEIVER_ADDR에 ExemONE 수집 서버 주소를 입력합니다.

RECEIVER_ADDR=<수집서버 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=tomcat_agent -Dexem.bid=$(hostname) -javaagent:/home/exem/java/lib/exem-java-agent.jar"

JVM 옵션 설명:

JDK 9 이상 필수 추가 옵션:

JDK 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

JDK 9 이상 전체 예시:

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

4-2. InitContainer 방식 (Kubernetes)​

애플리케이션을 재빌드하지 않고 Pod의 initContainer로 에이전트를 설치하는 방법입니다.

사전 조건:

• kubectl 명령어를 실행할 수 있는 환경이 필요합니다.
• 설치 대상 Deployment YAML에 ExemONE 환경변수를 추가해야 합니다.

설치 패키지 구성:

1. ConfigMap 생성​

아래 두 개의 ConfigMap을 생성합니다.

exem-java-agent-env (JVM 옵션 환경변수):

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 (에이전트 설정파일):

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: |
    !javax/servlet/http/HttpServlet.*

2. Deployment YAML 수정​

기존 Deployment YAML의 spec.template.spec에 아래 내용을 추가합니다.

spec:
  template:
    spec:
      volumes:
        - name: exem-volume
          emptyDir: {}
        - 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 지정}}"

환경변수 설명:

설정값 우선순위:

JVM 옵션, 환경변수, 설정 파일 3가지 방식으로 지정할 수 있으며 아래 순서로 우선합니다.

3. Tomcat 사용 시 (선택)​

제공된 exem-java-agent-env ConfigMap을 사용하여 CATALINA_OPTS에 에이전트 옵션을 적용합니다.

4-3. Dockerfile Rebuild 방식​

설치 대상 애플리케이션의 Dockerfile에 에이전트를 포함하여 이미지를 빌드하는 방식입니다.

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

이미지를 재빌드하는 서버에 패키지를 업로드한 후 압축을 해제합니다.

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

2. Dockerfile에 에이전트 설정 추가​

COPY {패키지_경로}/exem {애플리케이션내경로}/exem
ENV EXEM_GROUP_ID={group_id}
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=<수집서버 IP>:9010
ENV JAVA_OPTS="$JAVA_OPTS -Dexem.groupid=$EXEM_GROUP_ID -Dexem.agent.name=tomcat_agent -javaagent:/exem/java/lib/exem-java-agent.jar -Dexem.run.on.container=true"

3. Docker 이미지 빌드​

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

4. Deployment 적용​

Deployment YAML에 ExemONE 환경변수를 추가한 후 배포합니다.

kubectl apply -f app-deployment.yaml

5. 설치 확인​

5-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

5-2. ExemONE 화면 확인​

Application > WAS 화면에서 해당 WAS가 Active 상태인지 확인합니다.