본문으로 건너뛰기

Docker Java 설치

관리 > 에이전트 설치 > 하단의 애플리케이션 설치 클릭 > 설치 안내 중 Docker Java 탭 선택

Docker 컨테이너 기반으로 실행하는 Java 애플리케이션의 JVM Option에 에이전트 적용을 위한 설정을 추가하고 컨테이너 이미지를 패키징하는 과정을 다음과 같이 안내합니다.

노트

  • EKS Fargate는 지원 예정입니다.

  • Java 애플리케이션 연동 과정에 대한 이해를 돕고자 Git 예시 코드를 제공합니다. 다음 문서를 참조하세요.

에이전트 다운로드​

와탭 애플리케이션 에이전트 설치를 위해 whatap.conf 파일을 생성하세요. {YOUR_PROJECT_ROOT}는 에이전트를 설치하려는 프로젝트의 최상위 경로로 변경하세요.

cat >{YOUR_PROJECT_ROOT}/whatap.conf <<EOL
whatap.server.host={proxyServer}
EOL

쿠버네티스 내부 애플리케이션 에이전트 옵션 설정​

쿠버네티스 내부 애플리케이션 에이전트에 필요한 설정을 whatap.conf 파일에 작성하거나 또는 에이전트 배포 시 컨테이너 env 필드를 통해 설정할 수 있습니다.

  • whatap.conf 파일 내 옵션이 컨테이너 env 필드에 설정된 옵션보다 높은 우선순위를 가집니다.

  • whatap.conf 또는 컨테이너 env에 설정된 값이 없는 경우 기본값이 사용됩니다.

  • license 및 whatap.server.host 옵션의 경우 컨테이너 환경변수 설정을 활용하세요. 자세한 내용은 다음 문서를 확인하세요.

설정 파일의 내용이 변경되거나 중요한 설정 항목이 소실될 경우 정상적으로 동작하지 않을 가능성이 있기에 쿠버네티스 환경 내 컨테이너 환경변수 설정을 권장합니다. 그외 에이전트 기능 제어 옵션에 대한 자세한 내용은 다음 문서를 참조하세요.

노트

쿠버네티스 환경 내 사용 불가 옵션

  • whatap.name: 수집 서버가 에이전트를 식별하는 고유한 이름입니다. 해당 이름은 에이전트가 실행 중인 오브젝트 정보를 기반으로 생성됩니다. 사용자 임의 지정 시 에이전트 식별에 문제가 생길 수 있습니다.

  • whatap.onode: 기본값으로 쿠버네티스 클러스터 노드 이름이 설정됩니다. 에이전트가 속한 노드 정보를 제공받기 위해 사용됩니다. 사용자 임의 지정 시 정확한 노드 식별이 어려워질 수 있습니다.

노트

애플리케이션의 whatap.server.host 설정 확인 ​

일부 컨테이너 이미지에서는 whatap.server.host와 같이 .이 포함된 환경변수를 직접 설정할 수 없습니다. 이로 인해 애플리케이션 에이전트가 정상적으로 기동되지 않는 경우, whatap.conf 파일을 직접 수정하여 whatap.server.host 값을 설정해야 합니다. 애플리케이션의 whatap.server.host 설정 확인 방법은 다음과 같습니다.

  1. 와탭 애플리케이션 컨테이너에 진입하세요.

  2. 다음 명령어를 실행하여 whatap.server.host 값이 포함되어 있는지 확인하세요.

    $ env | grep whatap.server.host

값이 출력되지 않을 경우 해당 컨테이너 이미지가 .이 포함된 환경변수 설정을 지원하지 않는 것입니다. 이 경우 환경변수가 아닌 설정 파일을 활용해야 합니다. whatap.conf 파일을 열고 다음과 같이 whatap.server.host 값을 수동으로 설정하세요.

whatap.server.host={와탭 수집 서버 IP}

최신 버전 에이전트를 애플리케이션 이미지에 포함시킬 수 있도록 안내합니다.

  1. 아래 표를 참고하여 각 kube_mon 버전에 포함된 Java APM 에이전트 버전을 확인하세요.

    2025년 7월 2일 기준 Java APM 버전 정보
    whatap/kube_mon 버전Java APM 버전
    latest2.2.61
    1.8.72.2.61
    1.8.62.2.55
    1.8.52.2.52
    1.8.42.2.50
    1.8.32.2.50
    1.8.22.2.48
    1.8.12.2.47
    1.8.02.2.42
    1.7.162.2.41
    1.7.152.2.39
    1.7.142.2.39
    1.7.132.2.39
    1.7.122.2.38
    1.7.112.2.38
    1.7.102.2.38
    1.7.92.2.38
    1.7.82.2.36
    1.7.72.2.35
    1.7.62.2.35
    1.7.52.2.34
    1.7.42.2.33
    1.7.32.2.33
    1.7.22.2.33
    1.7.12.2.32
    1.7.02.2.32
    1.6.12.2.32
    1.6.02.2.31
    1.5.92.2.31
    1.5.82.2.30
    1.5.72.2.28
    1.5.62.2.27
    1.5.52.2.27
    1.5.42.2.26
    1.5.32.2.26
    1.5.22.2.26
    1.5.12.2.26
    1.5.02.2.26
    1.4.92.2.25

  2. 애플리케이션 이미지에 와탭 에이전트를 포함시키려면 먼저 Dockrfile 최종 이미지 빌드 단계에서 다음 내용을 추가하세요. {YOUR_PROJECT_ROOT}를 에이전트를 설치하려는 프로젝트의 최상위 경로로 변경하세요.

    # 와탭 에이전트용 디렉터리를 사용자 컨테이너에 생성
    RUN mkdir -p /whatap

    # 와탭 Java 에이전트를 사용자 컨테이너에 복사
    COPY --from=whatap/kube_mon /data/agent/micro/whatap.agent.kube.jar /whatap

    # 생성한 whatap.conf 설정 파일을 사용자 컨테이너에 복사
    COPY {YOUR_PROJECT_ROOT}/whatap.conf /whatap/

  3. Dockerfile의 시작 명령어에 다음 내용을 추가하세요.

    -javaagent:/whatap/whatap.agent.kube.jar -Dwhatap.micro.enabled=true

    다음 Dockerfile의 정의 예시를 참고하세요.

    Dockerfile
    FROM openjdk:8-jdk-slim
    RUN mkdir -p /app && mkdir /whatap
    WORKDIR /app
    COPY --from=whatap/kube_mon /data/agent/micro/whatap.agent.kube.jar /whatap
    COPY ./whatap.conf /whatap
    COPY ./target/myApp.jar /app/
    CMD ["java","-javaagent:/whatap/whatap.agent.kube.jar","-Dwhatap.micro.enabled=true","-jar","/app/myApp.jar"]
    EXPOSE 8080

  4. Docker를 빌드하세요. {YOUR_DOCKERFILE_DIR}를 Dockerfile이 위치한 경로로 변경하세요.

    cd {YOUR_DOCKERFILE_DIR}
    docker build -t {IMAGE_NAME} .
팁

Java 17 버전 이상의 경우 reflection 관련 --add-opens=java.base/java.lang=ALL-UNNAMED 옵션을 추가하세요.

보안키 설정하기​

SQL 변수, HTTP 쿼리를 조회하거나 Thread 중지 기능 이용하려면 보안키를 설정하세요.

  • Java 에이전트 2.2.2 버전 이상

    $WHATAP_HOME 경로에 security.conf 파일을 생성한 후 다음과 같이 6자리 영어, 숫자로 구성된 암호를 입력하세요.

    security.conf
    paramkey=ABCDEF # SQL 변수 및 HTTP 쿼리 조회
    threadkill=ABCDEF # Thread 중지 기능

  • Java 에이전트 2.2.2 버전 미만

    $WHATAP_HOME 경로에 paramkey.txt 파일을 생성한 후 다음과 같이 6자리 영어, 숫자로 구성된 암호를 입력하세요.

    paramkey.txt
    ABCDEF # SQL 변수 및 HTTP 쿼리 조회, Thread 중지 기능
팁

Java 에이전트 2.2.2 버전 미만에서 2.2.2 버전으로 업데이트하는 경우 기존 paramkey.txt 파일의 키값은 seuciry.conf 파일의 키값으로 자동 적용됩니다. 예를 들어, paramkey.txt에 FEDCBA를 사용한 상태에서 2.2.2 버전으로 업데이트했다면, security.conf 파일에는 다음과 같이 적용됩니다.

paramkey=FEDCBA
threadkill=FEDCBA

paramkey.txt 파일이 존재하지 않을 경우 security.conf 파일의 키값은 WHATAP이라는 키값으로 자동 생성됩니다.

노트

  • SQL 파라미터 정보 기록과 관련한 에이전트 설정은 다음 문서를 참조하세요.

  • HTTP 파라미터 정보 기록과 관련한 에이전트 설정은 다음 문서를 참조하세요.

컨테이너 환경변수 설정​

Docker 빌드 후 쿠버네티스 환경 내 컨테이너 환경변수를 설정하세요. 애플리케이션 배포 yaml 파일에 다음 내용을 추가하세요.

env:
- name: NODE_IP
  valueFrom: {fieldRef: {fieldPath: status.hostIP}}
- name: NODE_NAME
  valueFrom: {fieldRef: {fieldPath: spec.nodeName}}
- name: POD_NAME
  valueFrom: {fieldRef: {fieldPath: metadata.name}}
- name: OKIND
  value: {YOUR_OKIND_NAME}
- name: license
  value: {licenseKey}
- name: whatap.server.host
  value: {proxyServer}
- name: whatap.micro.enabled
  value: "true"

다음 예시를 참조하세요.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: #DeploymentName
  labels:
    app: #AppLabel
spec:
  replicas: 3
  selector:
    matchLabels:
      app: #AppLabel
  template:
    metadata:
      labels:
        app: #AppLabel
    spec:
      containers:
      - name: #ContainerName
        image: nginx
        ports:
        - containerPort: 80
        env:
        - name: NODE_IP
          valueFrom: {fieldRef: {fieldPath: "status.hostIP"}}
        - name: NODE_NAME
          valueFrom: {fieldRef: {fieldPath: "spec.nodeName"}}
        - name: POD_NAME
          valueFrom: {fieldRef: {fieldPath: "metadata.name "}}
        - name: OKIND
          value: #DeploymentName
        - name: license
          value: #licenseKey
        - name: whatap.server.host
          value: #proxyServer
        - name: whatap.micro.enabled
          value: "true"
노트

환경변수 역할

  • NODE_IP: 현재 Pod가 호스팅된 노드(Node)의 IP 주소를 수집합니다.

  • NODE_NAME: 현재 Pod가 실행 중인 노드의 이름을 수집합니다.

  • POD_NAME: 현재 Pod의 이름을 수집합니다.

  • OKIND(선택사항): Pod에 해당하는 애플리케이션들을 그룹화합니다. 디플로이먼트(Deployment) 이름으로 설정하면 해당하는 Pod들을 하나로 그룹화합니다.

  • license: 에이전트 인증 확인을 위한 키입니다.

  • whatap.server.host: 와탭 수집 서버 호스트 IP입니다.

  • whatap.micro.enabled: 컨테이너와의 연동을 활성화합니다.

에이전트 설치 확인​

  • 에이전트를 제대로 설치했는지 확인하려면 대시보드 > 애플리케이션 서비스 대시보드 메뉴로 이동하세요.

  • 다운로드한 파일을 직접 설치한 다음 대시보드 메뉴에서 에이전트를 확인할 수 없다면 다음 사항을 확인하세요.

    • 컨테이너에서 ps -ef | grep whatap 명령어를 실행해 에이전트 옵션을 적용했는지 확인하세요.

    • 컨테이너의 /whatap/logs 경로의 내용을 확인하세요. 에이전트 로그는 logs/{whatap 설정파일명}-yyyymmdd.log 형식의 파일명으로 출력됩니다.

최종 수정: 에