Java Agent Guide

제목 : Java Agent Guide
작성자 : WhaTap Support
이메일 : support@whatap.io
날짜 : 2019-04-12
버전 : 1.0.2

설명 : 본 문서는 WhaTap Java 에이전트에 대해 설명합니다.

1. 지원 환경

Web Application Server (WAS), 데몬 및 배치 애플리케이션 등 JVM에서 동작하는 모든 어플리케이션에 적용 할 수 있습니다.
Java1.4 이하, Java11 이상 버전은 support@whatap.io 로 별도 문의 주시기를 부탁 드립니다.

Table 1. 제품 지원 환경
제품 환경 OS JVM 버전

APM Agent

Java

JVM이 구동되는 모든 OS

Java6 이상
Java10 이하

2. 설치

에이전트 설치부터 실행, 업데이트 및 제거에 대해 설명합니다. 이 과정에서 발생하는 문제 해결에 대해 설명합니다.

2.1. 에이전트 설치 개요

일반적인 환경에서의 설치는 JVM 옵션 추가 후 Java 프로세스 재기동으로 적용하는 javaagent 방식을 사용합니다.
제한된 환경이라면 어플리케이션 재시작 없이 적용할 수 있는 attach 형태의 적용 방식을 사용 할 수 있습니다.

javaagent 적용법

애플리케이션 실행 스크립트에 JVM 옵션인 -javaagent 를 사용해 Tracer의 파일 경로를 추가합니다.
애플리케이션 기동 시 Tracer가 성능 수집 코드를 주입합니다.

Tracer: 성능 데이터 수집을 위한 모듈

210
Figure 1. javaagent 방식

와탭 에이전트는 운영중인 어플리케이션 재시작 없이도 적용할 수 있는 방법을 제공합니다. 이는 재기동에 민감한 환경에 APM 모니터링을 적용할 경우 유용한 방식입니다.

attach 적용법

에이전트 설치파일에 제공되는 attach.sh가 일회성으로 애플리케이션 서버 프로세스를 식별하고 Tracer를 활성화 합니다.

200
Figure 2. javaagent + onetime attach 방식
attach 형태로 적용 후 “javaagent” 옵션을 실행 스크립트에 추가하면 애플리케이션 서버 재기동 후에도 모니터링이 유지됩니다.

2.1.1. 구성 파일

와탭 모니터링 에이전트는 모니터링 정보를 수집하여 서버에 전송하기 위한 Tracer와 “attach” 방식으로 적용하기 위한 Watcher, 에이전트를 디버깅하기 위한 쉘 스크립트 파일로 구성됩니다.

와탭 모니터링 에이전트를 구성하는 각 파일의 역할은 다음과 같습니다.

공통 구성 파일
파일명 설명

whatap.agent.tracer-#.#.#.jar

Tracer - 웹 애플리케이션 서버 프로세스에 Attach되어 정보를 수집/서버로 전송하는 프로그램

whatap.conf

애플리케이션 서버의 데이터를 수집하는 수집서버의 주소와 서버의 프로젝트 라이센스 키가 입력되는 파일

attach 실행 파일
파일명 설명

attach.sh(bat)

실행 중인 애플리케이션 서버에 일회성으로 Tracer를 적용하기 위한 스크립트

유틸리티 구성 파일
파일명 설명

javaproc.sh(bat)

실행중인 자바 프로세스들의 PID와 JVM 옵션을 확인하는 스크립트

resmon.sh(bat)

CPU/Memory/Disk 정보 추출을 위한 스크립트

proxy.conf

소프트웨어 프록시 설정 파일

proxy.sh(bat)

소프트웨어 프록시 실행을 위한 스크립트

ping.sh(bat)

수집서버와의 통신 확인을 위한 스크립트

2.2. 표준 설치

와탭 APM 모니터링 서비스를 사용하기 위해서는 모니터링 프로젝트를 구성하고 대상 애플리케이션 서버에 모니터링 에이전트를 설치해야 합니다.

2.2.1. 사전 점검

방화벽 확인

와탭 에이전트는 수집서버의 TCP 6600 포트에 접속 가능해야 합니다.

출발지 목적지 목적지 IP 포트

와탭 에이전트

와탭 수집서버

52.78.209.94 52.78.224.235

TCP 6600

접속 여부는 telnet 명령으로 확인 할 수 있습니다.

telnet 52.78.209.94 6600
telnet 52.78.224.235 6600

접속에 문제가 없다면 "Connected to <IP> " 가 나타납니다.

Trying 52.78.209.94...
Connected to 52.78.209.94.
Escape character is '^]'.
방화벽을 오픈 할 수 없는 상황이라면 와탭 에이전트에서 제공하는 소프트웨어 프록시 사용을 검토 할 수 있습니다.

2.2.2. 설치 절차

프로젝트 생성

모니터링 프로젝트를 생성하기 위해 프로젝트 생성 버튼을 선택합니다. 화면 가운데 + 아이콘을 클릭 할 수도 있습니다.

220
Figure 3. 첫 로그인

Java 아이콘을 선택합니다. 프로젝트명과 데이터 서버 지역(Region), 그룹을 선택한 뒤 저장 버튼을 클릭합니다.

230
Figure 4. 프로젝트 생성 팝업
라이센스 발급

설치 안내 페이지에서 라이센스를 발급 받습니다. 라이센스는 프로젝트단위로 고유한 값을 가집니다.

240
Figure 5. 설치 안내 페이지 - 1
에이전트 다운로드

라이센스를 발급 받은 후에 ‘에이전트 파일 다운로드’ 버튼이 활성화 됩니다. 해당 버튼을 눌러 와탭 에이전트 파일을 다운로드 받습니다.

250
Figure 6. 설치 안내 페이지 - 2

모니터링 대상 서버에서 wget 을 사용해 직접 다운로드 받을 수도 있습니다.

wget https://service.whatap.io/agent/whatap.agent.java.tar.gz

모니터링 대상 서버에 적절한 위치를 정하고 에이전트 파일의 압축을 해제합니다. 이 위치를 $WHATAP_HOME 으로 설명합니다.

$WHATAP_HOME/whatap.conf 파일 내용에 라이선스키와 데이터 수집 서버 주소가 정상적으로 들어가 있는지를 확인합니다.

whatap.conf
license={라이센스 키}
whatap.server.host={수집서버 IP}
UI를 통해 다운로드 받은 경우 whatap.conf 에 설정값이 들어가 있습니다.
wget으로 직접 다운 받았다면 설치안내 페이지에서 보여지는 라이센스키와 수집 서버 주소를 별도 입력해야 합니다.
자원 수집 가능 여부 확인

$WHATAP_HOME 경로로 이동하여 resmon.sh 을 실행합니다. CPU/Memory/Disk 정보 수집 여부를 확인합니다.

$ ./resmon.sh
_      ____           ______
| | /| / / /  ___ /_  __/__ ____
| |/ |/ / _ \/ _ `// / / _ `/ _ \
|__/|__/_//_/\_,_//_/  \_,_/ .__/
                                  /_/
Just Tap, Always Monitoring
WhaTap Agent version 0.3.7 20161107
cpu      pcpu        mem         disk
120322 14.06        0.0     42.0        85.0
120325 14.06        0.0     42.0        85.0

이후 절차는 각각의 설치 방식에 따라 진행하면 됩니다.

2.2.3. javaagent 방식

시작 스크립트에 JVM 옵션 적용 후 재기동 이후 적용되는 일반적인 방식입니다.

JVM 옵션에 -javaagent 설정이 추가 됩니다.

JVM_OPTS
-javaagent:$WHATAP_HOME/whatap.agent.tracer-#.#.#.jar

각각의 환경에 따른 세부 설정 위치는 ‘애플리케이션 서버 별 적용 절차’에서 확인할 수 있습니다.

Tomcat – Linux 계열

catalina.sh 상단에 JAVA_OPTS 를 추가 합니다.

catalina.sh
#   JAVA_OPTS           (Optional) Java runtime options used when any command
#             is executed.
#             Include here and not in CATALINA_OPTS all options, that
#             should be used by Tomcat and also by the stop process,
#             the version command etc.
#             Most options should go into CATALINA_OPTS.
########## WHATAP ############
JAVA_OPTS="${JAVA_OPTS} -javaagent:/whatap/whatap.agent.tracer-0.4.2.jar "
########## WHATAP ############

향후 catalina.sh 변경 없이 에이전트 업데이트 기능을 사용하고자 한다면 다음과 같이 옵션을 적용 합니다.

catalina.sh
WHATAP_HOME=/whatap
########## WHATAP ############
WHATAP_JAR=`ls ${WHATAP_HOME}/whatap.agent.tracer-*.jar | sort | tail -1`
JAVA_OPTS="${JAVA_OPTS} -javaagent:${WHATAP_JAR} "
########## WHATAP ############
Tomcat – Windows 계열

catalina.bat 상단에 JAVA_OPTS 를 추가 합니다.

catalina.bat
rem   JAVA_OPTS           (Optional) Java runtime options used when any command
rem             is executed.
rem             Include here and not in CATALINA_OPTS all options, that
rem             should be used by Tomcat and also by the stop process,
rem             the version command etc.
rem             Most options should go into CATALINA_OPTS.
rem ########## WHATAP ############
if x%JAVA_OPTS:whatap=%==x%JAVA_OPTS% (
  set JAVA_OPTS=%JAVA_OPTS% -javaagent:C:\whatap\whatap.agent.tracer-0.4.2.jar
)
rem ########## WHATAP ############

향후 catalina.bat 변경 없이 에이전트 업데이트 기능을 사용하고자 한다면 다음과 같이 옵션을 적용 합니다.

catalina.bat
rem ########## WHATAP ############
set WHATAP_HOME=C:\whatap
for /f %%f in ('dir /b /on %WHATAP_HOME%\whatap.agent.tracer-*.jar') do set last=%%f
set WHATAP_JAR=%last%
if x%JAVA_OPTS:whatap=%==x%JAVA_OPTS% (
  set JAVA_OPTS=%JAVA_OPTS% -javaagent:%WHATAP_HOME%\%WHATAP_JAR%
)
rem ########## WHATAP ############
WAS 재기동

애플리케이션 서버를 기동 또는 재기동 하고, 애플리케이션 서버 로그와 에이전트 로그를 확인하여 정상 기동 여부를 확인합니다.

Nov 16, 2016 3:06:40 AM org.apache.catalina.startup.HostConfig deployDirectory
INFO: Deployment of web application directory /var/lib/tomcat7/webapps/ROOT has finished in 577 ms
Nov 16, 2016 3:06:40 AM org.apache.coyote.AbstractProtocol start
INFO: Starting ProtocolHandler ["http-bio-8080"]
Nov 16, 2016 3:06:40 AM org.apache.catalina.startup.Catalina start
INFO: Server startup in 3984 ms
_           ____       ______
| | /| / / /  ___ /_  __/__ ____
| |/ |/ / _ \/ _ `// / / _ `/ _ \
|__/|__/_//_/\_,_//_/  \_,_/ .__/
                             /_/
Just Tap, Always Monitoring
WhaTap Agent version 0.3.9 20161115

WhaTap 캐릭터 로그를 확인한 뒤, 콘솔에 정상적으로 등록되어 있는 여부를 확인하기 위해 해당 프로젝트의 ‘서버’ 메뉴에 올라온 해당 애플리케이션 서버의 명칭을 확인합니다.

260
Figure 7. 서버
  • 애플리케이션명은 {type}-{ip2}-{ip3}-{port] 의 형태의 식별ID가 부여됩니다. 마지막 요소가 {port}가 아닌 {pid}인 경우 애플리케이션 서버의 서비스 포트가 인식되지 않은 것으로 애플리케이션의 마지막 항목에 표시되는 PID(프로세스 ID)를 참조하여 설치 문제에 대응합니다.

2.2.4. attach 방식

실행 중 애플리케이션 서버의 재기동이 어려운 경우 attach 방식을 사용 할 수 있습니다.

Attach 방식 제약 사항
1. IBM Java 에서는 동작하지 않습니다.
2. SQL 쿼리 모니터링이 기능이 동작하지 않습니다.

attach.sh(bat) 파일을 실행하여 적용하며, 실행 파라미터로 PID(프로세스 ID)를 사용합니다.

자바 프로세스 확인

Linux 계열의 경우 ps 명령을, Windows 계열의 경우 작업관리자를 통해 실행 중인 애플리케이션의 프로세스ID (PID)를 확인합니다.

Tomcat - pid
$ ps -ef | grep tomcat | grep -v 'grep'
ec2-user  3058     1  1 06:11 pts/0        00:00:02 /home/ec2-user/jdk1.8.0_111/bin/java -Djava.util.logging.config.file=/home/ec2-user/apache-tomcat-7.0.72/conf/logging.properties -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager -Djdk.tls.ephemeralDHKeySize=2048 -Djava.endorsed.dirs=/home/ec2-user/apache-tomcat-7.0.72/endorsed -classpath /home/ec2-user/apache-tomcat-7.0.72/bin/bootstrap.jar:/home/ec2-user/apache-tomcat-7.0.72/bin/tomcat-juli.jar -Dcatalina.base=/home/ec2-user/apache-tomcat-7.0.72 -Dcatalina.home=/home/ec2-user/apache-tomcat-7.0.72 -Djava.io.tmpdir=/home/ec2-user/apache-tomcat-7.0.72/temp org.apache.catalina.startup.Bootstrap start
attach 실행

$WHATAP_HOME/attach.sh(bat) 를 실행합니다. 에이전트 정상 동작 확인 절차는 “javaagent” 방식과 동일합니다.

$ ./attach.sh 3058
JAVA_HOME=/jdk1.8.0_111
_      ____           ______
| | /| / / /  ___ /_  __/__ ____
| |/ |/ / _ \/ _ `// / / _ `/ _ \
|__/|__/_//_/\_,_//_/  \_,_/ .__/
                             /_/
Just Tap, Always Monitoring
WhaTap Agent version 0.4.2 20161123
Admin: ec2-user
PID: 3128
Java Path: /jdk1.8.0_111/jre
Java Version: 1.8.0_111
AttachAgent Success :  [3058] org.apache.catalina.startup.Bootstrap start

2.2.5. attach + javaagent 혼용

서비스 재시작이 제한된 환경에서는 최초 적용시 attach 를 사용해 적용합니다. 재시작 이후에도 모니터링을 지속하기 위해 javaagent 방식 설치도 함께 적용합니다.

에이전트 업데이트

관리 | 에이전트 업데이트 메뉴를 선택 후 다운로드 또는 모든 서버에 다운로드 버튼을 클릭합니다.

다운로드 된 에이전트는 어플리케이션 재시작시 자동 적용됩니다.

agent update
Figure 8. 관리 - 에이전트 업데이트
에이전트 삭제 방법

애플리케이션 서버 JVM 옵션의 -javaagent 설정을 삭제 후 애플리케이션 서버를 재기동 합니다. 이후 $WHATAP_HOME 을 삭제 합니다.

2.3. 에이전트 네이밍

모니터링 대상을 식별하기 위해서는 이를 구분해야 할 필요가 있으며 와탭은 오브젝트 이름과 오브젝트 아이디를 통해서 대상을 구분합니다.

오브젝트(에이전트)이름은 프로젝트 단위로 고유해야 합니다.
오브젝트 아이디/이름이 바뀌면 이전 데이터와 연결되지 않습니다

와탭 모니터링 서비스에서는 모니터링 대상을 오브젝트 또는 에이전트로 혼용해서 사용합니다.

2.3.1. 이름 결정 방식

추가적인 설정이 없는 경우 오브젝트 이름은 자동으로 결정 됩니다.

예) IP 주소가 10.11.12.13 인 서버에서 Tomcat 이 8080 포트로 기동된 경우 TC-12-13-8080 이라는 오브젝트 이름으로 자동 부여됩니다.
whatap.oname 설정이 없는 경우 (기본값)
1. whatap.type을 식별한다.
2. whatap.type이 서블릿 컨테이너면 어플리케이션이 사용하는 포트를 식별 한다.
3. 포트가 식별되지 않는 경우라면 pid 를 검색 한다.
4. 식별된 정보에 IPv4 주소 3,4번째를 추가하여 최종 이름을 결정한다.

결과 : {type}-{ip2}-{ip3}-{port}

이와같은 이름 결정 방식을 사용하는 이유는 서비스 중지, 네트워크 단절 후 재 접속된 에이전트와 기존 에이전트로 부터 수신된 데이터의 연속성을 유지하기 위해서 입니다.

2.3.2. 이름 변수

와탭은 이름으로 사용할 수 있는 변수를 다음과 같이 제공 합니다.

오브젝트 이름 패턴에 사용할 수 있는 변수 종류
문자열

지정한 문자열을 사용합니다.

{type}

컨테이너 타입을 자동 식별해 부여 합니다. 자동 식별 대상은 다음과 같습니다.
JAVA, TOMCAT, JBOSS, RESIN, SPRINGBOOT, JETTY, JEUS, WEBLOGIC, WEBSPHERE, UNDERTOW, PLAY

{ip0}

IPv4 주소 중 첫번째 수를 사용합니다.

{ip1}

IPv4 주소 중 두번째 수를 사용합니다.

{ip2}

IPv4 주소 중 세번째 수를 사용합니다.

{ip3}

IPv4 주소 중 네번째 수를 사용합니다.

{pid}

Java Process 의 pid 를 사용합니다.

{port}

어플리케이션이 Listen 하는 포트를 사용합니다.

2.3.3. 이름 지정

자동으로 부여된 이름 대신 직접 이름을 정할수도 있습니다.

우선순위

옵션

설정위치

설명

1

-Dwhatap.name

JVM Option

어플리케이션명 패턴을 지정합니다.

default : {type}-{ip2}-{ip3}-{port}

2

-Dwhatap.oname

JVM Option

어플리케이션명을 고정값으로 지정합니다.

오브젝트 이름의 자동부여

클라우드 환경에서 Scale Out환경에서는 VM이 복사되어 사용될 수 있기 때문에 오브젝트 이름이 자동 부여되는 것이 중요합니다.

동일 프라이빗 IP를 사용하는 환경에서 오브젝트 이름 자동 부여

만약 2개의 VPC환경을 만들고 동일한 private IP 를 사용하도록 네트웍을 구성한경우 두개의 VPC는 별도의 프로젝트로 분리하거나 -Dwhatap.name을 서로 다른 패턴으로 지정하여 중복되지 않도록 해야 합니다.

오브젝트 이름을 명시적으로 지정할때는

java 실행 옵션에 지정할 수 있습니다.

-Dwhatap.oname=tomcat1
오브젝트 이름을 패턴으로 지정하고 싶을때

문자열과 변수를 조합해 사용할 수 있습니다.

-Dwhatap.name=front-{ip3}-{port}

2.3.4. MSA 업무 그룹 구분

Auto Scale Out 환경에서 자동 등록된 에이전트의 IP / Port / Pid 정보만을 가지고 업무 단위의 정보를 인지하기 어려운 경우가 있습니다.

이 경우 okind 속성을 부여하면 쉽게 식별이 가능합니다.

전형적인 Docker 환경의 모습입니다.
  • 각 에이전트는 잘게 쪼개어 놓은 MSA (Micro Service Architecture) 구성 요소 입니다.

  • 에이전트들은 자동으로 Scale In/Out 됩니다.

  • 어떤 IP를 가진 서버에서 어떤 pid 로 어플리케이션이 기동 될 지는 예측 할 수 없습니다.

이 경우 이름과 더불어 업무를 식별 할 수 있는 whatap.okind 옵션을 사용해 okind 속성을 추가 합니다.

JVM 옵션에 추가 할 수 있습니다.

JAVA_OPTS
-Dwhatap.okind=mobile_ui

설정 파일에 추가 할 수도 있습니다.

whatap.conf
whatap.okind=common_api
MSA 환경이라면 okind 속성을 추가해야만 와탭이 제공하는 다양한 기능을 활용 할 수 있습니다.

2.3.5. Scale In 에서 에이전트 자동 삭제

에이전트 이름을 자동부여하는 것은 Scale Out 시 운영자의 개입 없이 시스템을 자동으로 확장하기 위함입니다
그런데 Auto Scale 환경에서 Scale In이 발생하는 경우 정상적인 Shutdown으로 인식하는 것이 필요합니다.

자동 삭제를 위해서는 서버에서 에이전트로 부터 자동 삭제에 대한 메세지를 받아야 합니다. ${WHATAP_HOME}에 톰켓 프로세스의 {process id}.shutdown 파일이 나타나면 5초 이내에 에이전트는 서버에 “SILENT_SHUTDOWN” 이벤트를 전송합니다.

SILENT_SHUTDOWN 이벤트가 전송되고 1분 이내에 에이전트가 셧다운되면 와탭서버는 해당 에이전트를 곧바로 목록에서 제거하고 inactive이벤트도 발생키지 않습니다.

$TOMCAT_HOME/bin/shutdown.sh
touch $WHATAP_HOME/$CATALINA_PID.shutdown

2.4. 애플리케이션 서버 별 적용절차

2.4.1. 애플리케이션 서버 별 JVM 옵션 설정 위치

애플리케이션 서버 설정 위치

SpringBoot

java -javaagent:{whatap.agent.tracer-x.x.x.jar의 full path} -jar {application jar}

Tomcat

$CATALINA_HOME/bin/catalina.sh(bat)

JBoss 5.0 이하

$JBOSS_HOME/bin/run.conf

JBoss 7.0 이상 EAP 6.0이상

$JBOSS_HOME/bin/standalone.conf(domain.conf)

WebLogic

$WEBLOGIC_HOME/user_projects/domains/사용자도메인/bin/startWebLogic.sh(bat)

WebSphere

admin console 통해
1. Server > Server Types > WebSphere application servers > 서버 선택
2. 서버 Configuration탭 > Server Infrastructure의 Java and Process Management > Process definition 선택
3. Additional Properties의 Java Virtual Machine 선택
4. Generic JVM arguments 편집

Jeus7

$JEUS_HOME/domains/jeus_domain/config.xml

Jeus6

$JEUS_HOME/config/$hostname/JEUSMain.xml

Jetty

watch_jetty.sh(bat)

play2

$PLAY_HOME/framework/build

Liberty

${server.config.dir}/jvm.options

2.4.2. SpringBoot

jar 형태로 패키징하여 실행하는 경우 jvm 옵션에 -javaagent를 추가합니다.

java -javaagent:{whatap.agent.tracer-x.x.x.jar의 full path} -jar {application jar}

2.4.3. Tomcat on Windows Service

Windows 계열 OS에 binary로 설치하여 SYSTEM 계정으로 실행한 경우, ‘javaagent’ 방식으로 Tomcat을 실행합니다.

  • “Configure Tomcat” 프로그램을 실행하여 Java 탭 선택 > Java Options에 -javaagent 옵션을 지정합니다.

270
Figure 9. Configure Tomcat - Java

2.4.4. JBoss

JVM 옵션에 -javaagent 및 -Djboss.modules.system.pkgs에 설정을 추가합니다.

애플리케이션 서버 버전 JVM 옵션

공통

JVM 옵션의 -javaagent에 Tracer 설정

JBOSS 7.0 이상 EAP 6.0이상

JVM 옵션의 -Djboss.modules.system.pkgs 환경 변수에 “whatap” prefix 추가

standalone.sh
#!/bin/sh
########## WHATAP ############
WHATAP_HOME=/home/ec2-user/whatap
WHATAP_JAR=`ls ${WHATAP_HOME}/whatap.agent.tracer-*.jar | sort | tail -1`
JAVA_OPTS="${JAVA_OPTS} -javaagent:${WHATAP_JAR} -Djboss.modules.system.pkgs=whatap "
########## WHATAP ############
“-Djboss.modules.system.pkgs=whatap” 미설정 시 에러 메세지
11:38:46,148 ERROR [org.apache.catalina.core.ContainerBase.[jboss.web].[default-host].[/].[default]] (http--0.0.0.0-8080-1) Servlet.service() for servlet default threw exception: java.lang.ClassNotFoundException: whatap.agent.trace.TraceMain from [Module "javax.servlet.api:main" from local module loader @67d7d474 (roots: /jboss-as-7.1.1.Final/modules)]

2.4.5. WebLogic

설정 위치

$WEBLOGIC_HOME/user_projects/domains/사용자도메인/bin/startWebLogic.sh(bat)

  • javaagent 프로퍼티 설정을 추가합니다.

280
Figure 10. startWebLogic.sh

2.4.6. WebSphere

  1. 먼저 웹브라우저를 통해 admin console에 로그인 합니다.

290
  1. Servers > Server Type > WebSphere application servers 메뉴를 통해 에이전트를 설치할 서버를 선택합니다.

300
  1. 선택된 서버 Configuration 탭에 Server Infrastructure의 Java and Process Management > Process definition 메뉴를 선택합니다.

310
  1. Additional Properties의 Java Virtual Machine 메뉴를 선택합니다.

320
  1. WEBSHERE의 서비스 포트를 확인합니다.

330
  1. Configuration 탭의 Generic JVM arguments에 -javaagent와 -Dwhatap.port를 추가합니다.

340

2.4.7. Jeus

  1. Jeus 설정 파일에서 JVM 옵션을 설정합니다

설정 파일 위치

Jeus7

$JEUS_HOME/domains/jeus_domain/config.xml 에서 jvm-option에 -javaagent 옵션을 추가합니다.

Jeus6

$JEUS_HOME/config/$hostname/JEUSMain.xml 에서 command-option에 -javaagent 옵션을 추가합니다.

Jeus 7 - config.xml
<domain>
   <servers>
       <server>
           <name>server1</name>
           <jvm-config>
               <jvm-option>
                   -Xmx1024m -XX:MaxPermSize=128m
                   -javaagent:/whatap/whatap.agent.tracer-0.8.1.jar
               </jvm-option>
           </jvm-config>
       </server>
   </servers>
</domain>
350
Figure 11. Jeus 6 - JEUSMain.xml
  1. 애플리케이션 서버를 재시작 합니다.

jdown && jboot
  1. 애플리케이션 서버 로그와 에이전트 로그를 통해 에이전트가 정상적으로 기동하였는지, 에러가 발생하지 않았는지 확인합니다.

로그 파일 위치

에이전트

$WHATAP_HOME/logs/whatap-{SERVER_NAME}-{DATE}.log

JEUS6

$JEUS_HOME/logs/$NODE_NAME/JeusServer.log

JEUS7

$JEUS_HOME/domains/$HOST_NAME/servers/$NODE_NAME/logs/JeusServer.log

JEUS7
$JEUS_HOME/domains/$HOST_NAME/servers/$NODE_NAME/logs/JeusServer.log
370
  1. 에이전트가 애플리케이션 서버의 종류와 애플리케이션 서버의 서비스 container명을 인식했는지 확인합니다.

    와탭 사이트에서 whatap.name과 whatap.type을 확인합니다.
    service.whatap.io 로그인 > 프로젝트 선택 > 서버 메뉴 선택 > 더보기 > Boot Environment 메뉴 선택을 통해 확인합니다.

whatap.type에는 애플리케이션 서버의 종류가 명시되어야 하며, whatap.name의 마지막 요소가 container이름 이어야 합니다.

380
Figure 12. Boot Environment

2.4.8. Jetty

JVM 옵션에 -javaagent와 -Dwhatap.port를 추가합니다.

$JETTY_HOME/bin/jetty.sh 파일에 JVM 파일 옵션을 추가합니다.

390
Figure 13. jetty.sh

또는, 옵션을 적용하여 Jetty를 기동합니다.

Start Jetty without startup shell
$ java -javaagent:/home/vagrant/whatap/whatap.agent.tracer-0.3.0.jar -Dwhatap.port=8080 -jar start.jar &

2.4.9. Resin

  1. Resin 설정 파일에서 JVM 옵션을 설정합니다.

설정 파일 위치

Resin 4.x

$RESIN_HOME/conf/resin.properties 에서 jvm-arg를 추가하여 -javaagent 옵션을 설정합니다.

Resin4.x
(중략)
<resin xmlns="http://caucho.com/ns/resin">
   <cluster id="web-tier">
       <server-default>
           <jvm-arg>-Xmx1024m -XX:MaxPermSize=128m -javaagent:/whatap/whatap.agent.tracer-#.#.#.jar</jvm-arg>
       </server-default>
       ...
   </cluster>
</resin>
(중략)
  1. 애플리케이션 서버를 재기동 시킵니다.

  2. 애플리케이션 서버 로그와 에이전트 로그를 통해 에이전트가 정상적으로 기동 되었는지 에러가 발생하지 않았는지 확인합니다.

로그 파일 위치

에이전트

$WHATAP_HOME/logs/whatap-{SERVER_NAME}-{DATE}.log

RESIN4.x

$RESIN_HOME/log/jvm-app-#.log

2.4.10. Play

$PLAY_HOME/framework/build 에 에이전트 옵션을 설정합니다. 별도 사용하는 시작/중지 스크립트가 있다면 그곳에 적용합니다.

$PLAY_HOME/framework/build
#! /usr/bin/env sh
​
########## WHATAP START ############
WHATAP_HOME=/apps/whatap
WHATAP_JAR=`ls ${WHATAP_HOME}/whatap.agent.tracer-*.jar | sort | tail -1`
JAVA_OPTS="${JAVA_OPTS} -Dwhatap.play2=2.2.6 -javaagent:${WHATAP_JAR} " (1)
########## WHATAP END ############
​
if [ -z "${PLAY_VERSION}" ]; then
  PLAY_VERSION="2.2.6"
​
(중략)
1 Play는 기본 설정 이외 -Dwhatap.play2=2.2.6 옵션이 추가되어야 합니다.

2.4.11. Liberty

${server.config.dir}/jvm.options 에 에이전트 옵션을 설정합니다. 파일이 없는 경우 신규로 생성 합니다.

/wasliberty/usr/servers/defaultServer/jvm.options
-javaagent:/app/whatap/whatap.agent.tracer-1.6.2.jar
-Dorg.osgi.framework.bootdelegation=whatap.* (1)
1 OSGI 프레임워크를 사용하므로 이를 위한 설정을 추가 합니다.

2.5. 설치 에러 해결

2.5.1. 방화벽 설정 확인

와탭 서버에 대한 TCP 아웃바운드 방화벽이 설정되어 있으면 모니터링 정보를 서버로 전송 할 수 없으므로 방화벽 차단을 해제해야 합니다.

telnet 명령을 사용해 " Connected to <IP> " 를 확인 해야 합니다.

telnet
$ telnet 52.193.60.176 6600
Trying 52.193.60.176...
Connected to 52.193.60.176.
Escape character is '^]'.
  • 수집 서버 IP 정보는 와탭 웹사이트에서 해당 프로젝트의 관리 > 에이전트 설치 메뉴에서 확인할 수 있습니다.

2.5.2. 애플리케이션 서비스 포트가 감지되지 않는 경우

어플리케이션 기동에 1분 이상 소요되거나 일반적이지 않은 구조에서 포트 감지에 실패하는 경우, 에이전트는 포트 대신 PID(프로세스 ID)를 전송합니다.

포트는 고정값인 반면 PID는 재기동시 달라지므로 이 겨우 어플리케이션의 연속성 식별이 어려울 수 있습니다.

이 경우 실행스크립트내 JVM 옵션에 whatap.port 속성을 추가 후 애플리케이션 서버를 재기동합니다.

JAVA_OPTS
JAVA_OPTS="${JAVA_OPTS} -Dwhatap.port=8080 "
애플리케이션 서버 별 JVM 옵션 설정 파일은 ‘애플리케이션 서버 별 적용절차’에서 확인할 수 있습니다.

2.5.3. 애플리케이션 서버가 OSGi 프레임워크를 사용하는 경우

OSGI 프레임워크 구조의 애플리케이션 서버인 경우 JVM 옵션에 에이전트 패키지 prefix(whatap)를 등록해야 합니다.

Jboss EAP 6.0 이상
Jboss AS 7.0 이상
Wildfly 8.0 이상
IBM WebSphere AS 7.0 이상
등이 해당됩니다.
JBoss AS, Wildfly, JBoss EAP 6.0 이상

$JBOSS_HOME/bin/standalone.conf(domain.conf)파일에 prefix를 등록합니다.

-Djboss.modules.system.pkgs=whatap
410
Figure 14. JBOSS .EAP 7.0 예시
WebSphere
-Dcom.ibm.ws.classloader.server.alwaysAllowedPackages=whatap
  • Default로 ‘*’로 지정되어 있는 경우는 별도의 설정을 필요로 하지 않습니다.

  • 설정 위치는 ‘WebSphere‘를 참조합니다.

security.policy 권한 추가

$WEBSPHERE_HOME/properties/server.policy 또는 $WEBSPHERE_PROFILE_HOME/properties/server.policy
grant codeBase "file:$WHATAP_HOME/-"
{
   permission java.security.AllPermission;
};

2.5.4. 히트맵에 트랜잭션이 표시되지 않는 경우

IBM JDK의 경우 “watcher” 방식으로 에이전트를 실행시킬 경우 트랜잭션 정보가 수집되지 않으므로 ‘javaagent’ 방식으로 에이전트를 설치해야 합니다.

2.5.5. logmanager 관련 에러가 발생하는 경우

JBoss AS 7.0이상, JBoss EAP 6.0 이상 에서 logmanager 관련 에러가 발생한다면 JVM 옵션을 추가합니다.

-Djava.util.logging.manager에 LogManager package명 설정
-Xbootclassloader에 JBoss log manager JAR file 설정
420
Figure 15. 설정 추가 예

2.5.6. MBeanServerBuilder 에러가 발생하는 경우

JBoss 5.0 이하에서 MBeanServerBuilder 관련 에러가 출력된 경우 JVM 옵션 추가 합니다.

-Djboss.platform.mbeanserver를 true로 설정합니다.
430
Figure 16. 설정 추가 예

2.5.7. permission 오류가 발생하는 경우

Java Security Policy 관련 오류가 발생하는 경우, $JAVA_HOME/jre/lib/security/java.policy 파일에 권한 설정을 추가합니다.

모든 권한을 일괄 적용하고자 하는 경우, {JAVA_HOME}/jre/lib/security/java.policy 파일에 하기의 설정을 추가합니다.

grant {
   permission java.security.AllPermission;
};
java.io.FilePermission 오류가 발생하는 경우