WhaTap APM 모니터링 설치 가이드



개정 이력
버전 제품버전 비고
1.0 0.3.9 2016.09.26 WhaTap APM 모니터링 설치 가이드 초안
2.0 0.4.0 2016.11.01 각 어플리케이션 서버 별 설치 가이드 별도의 파일로 분리, 스크린샷 추가, 설치 상담시 고객이 많이 겪었던 문제 실행 스텝에 추가
2.1 0.4.5 2016.11.08 목차 개정, 개요 및 다이어그램 개정
2.2 0.4.6 2016.12.19 권장 설치 방식 변경
2.3 0.5.3 2017.01.10 Agent AES 256 암호화 방식 추가

문서 목적

이 문서는 와탭 APM 서비스 사용자가 에이전트 설치를 돕기 위해 작성된 문서 입니다.
이 문서는 와탭 랩스의 고유한 자산으로 재배포 또는 사용을 위해서는 와탭랩스(support@whatap.io) 에 연락 주시기 바랍니다.

목차

1. 모니터링 서비스 개요

WhaTap APM 모니터링은 SaaS(Software as a Service) 방식의 웹 어플리케이션 서버 모니터링 서비스를 제공합니다.

1.1 모니터링 서비스 구성

WhaTap APM 모니터링은 서버와 에이전트로 구성됩니다.

구성요소 설명
서버 에이전트가 수집한 어플리케이션 성능 데이타를 수집,저장 및 통계 정보 추출하고 이를 사용자에 효율적인 방법으로 제공
whatap.io 사이트에서 해당 서비스를 제공
에이전트 웹 어플리케이션 서버에 설치되어, 어플리케이션 성능 데이타를 수집하여 서버로 전송

1.2 모니터링 서비스 개요

WhaTap은 모니터링 서버를 SaaS형으로 제공하므로 사용자는 모니터링 서버의 설치 없이, 모니터링 대상 어플리케이션에 에이전트를 설치하는 것만으로, Java 6,7,8 기반 어플리케이션 서버의 성능 모니터링을 수행 할 수 있습니다.

모니터링 정보의 수집과 사용자가 원하는 정보의 추출은 WhaTap 서버가 수행하게 되며, 사용자는 브라우저를 통해 어플리케이션의 성능 정보를 활용할 수 있습니다.

WhaTap APM 모니터링 서비스는 프로젝트 단위로 서버를 관리 할 수 있는 기능을 제공하므로, 프로젝트 단위로 그룹핑 된 성능 정보를 단일 화면에서 확인 할 수 있습니다.

1.3 어플리케이션 서버 식별

WhaTap은 모니터링 정보 수집 대상인 어플리케이션 서버 식별을 위한 정보로 기본적으로 어플리케이션 서버로 부터 수집한 정보를 활용합니다. 기본적으로 활용하는 정보는 어플리케이션 서버 종류, 어플리케이션 서버의 IP, 서비스 포트를 조합하여 어플리케이션 서버를 고유 식별자로 사용하게 되며 필요에 따라 사용자가 지정한 명칭을 사용하거나 패턴을 변경하여 사용하는 것도 가능합니다.

어플리케이션 서버로부터 추출한 정보를 활용하는 이유는 어플리케이션 서버 정지, 네트워크 단절 또는 에이전트 문제로 인한 수집 서버와 에이전트의 통신 단절 상태가 복구되었을 경우, 재접속 된 에이전트로 부터 송신되는 정보가 기존 에이전트로 부터 송신된 정보와의 연속성을 유지하기 위해서 입니다.

WhaTap이 어플리케이션 서버를 식별하기 위해 사용하는 기본 패턴은 다음과 같습니다.

						
							# default pattern
          {type}-{ip2}-{ip3}-{port}
          
					

Tomcat 서버를 사용하고, IP가 192.168.0.1, 사용포트가 8080인 경우, TC-0-1-8080과 같이 어플리케이션 명을 부여하여 식별합니다.

자동으로 부여된 이름 대신 직접 어플리케이션 서버 별로 이름을 부여하고 싶은 경우, 옵션 설정을 통해 패턴을 지정하거나, 정적으로 어플리케이션 명을 지정 할 수도 있습니다.

패턴 옵션 설명 비고
type 어플리케이션 서버 유형 TC:Tomcat
SB:SpringBoot
JB:JBoss
WL:WebLogic
WS:Websphere
JU:Jeus
JT:Jetty
AP:Application
ipN ip address의 N 번째 자리
port 어플리케이션 서비스 포트
pid 어플리케이션 프로세스 ID 어플리케이션 서버 포트 식별 불가 시 활용
cmdN java 명령을 통해 전달된 N번째 파라메타 어플리케이션 서버가 파라메타를 전달받는 경우에 사용가능

어플리케이션 명을 위와 같이 패턴화하여 지정하는 이유는 프로젝트 하위의 어플리케이션 서버 각각에 고유한 명칭을 부여하여 관리하기 위함입니다. 제한된 개수의 어플리케이션을 사용하는 경우를 제외하고 동일한 이름을 정적으로 지정하여 사용해서는 안됩니다. 클라우드 환경의 복수 Region을 활용하는 경우와 같이 네트워크 환경의 내부 IP 대역을 지정하여 사용하는 경우 서버 IP가 중복 가능성을 확인하여야 하며 어플리케이션 서버명을 그룹 단위로 패턴화하여 적용해야 합니다.

패턴 예시

						
							# group A
          -Dwhatap.name=groupA-{type}-{ip2}-{ip3}-{port}
          # group B
          -Dwhatap.name=groupB-{type}-{ip2}-{ip3}-{port}
          
					

2. 모니터링 에이전트 개요

2.1 에이전트 설치 방식

WhaTap은 사용자 편의를 위해 3가지 방식의 에이전트 설치 방식을 제공합니다.
사용자 어플리케이션 환경에 따라 “javaagent”, “javaagent+onetime attach”, “watcher” 방식 중 택일하여 에이전트를 설치 할 수 있습니다.

WhaTap은 어플리케이션 서버 기동 상태에서 최초 설치 시에는 attach 방식을 활용하고 재기동 이후 “javaagent” 방식을 활용하는 “javaagent+onetime attach” 방식을 권장합니다.

IBM JDK의 경우 “watcher” 방식으로 에이전트를 실행시킬 경우 트랜잭션 정보가 수집되지 않으므로 “javaagent” 방식으로 에이전트를 실행해야 하는 제약이 있습니다.

2.1.1 “javaagent+onetime attach” 방식

어플리케이션 서버 부팅 시에 성능 데이타 수집을 위한 모듈을 주입하는 방식과 실행 중인 어플리케이션 서버에 모듈을 주입하는 방식을 혼용하는 방식입니다.
“javaagent” 방식과 동일한 설정을 실행중인 어플리케이션 서버의 실행 스크립트에 추가하여 어플리케이션 서버 재기동 시에도 모니터링 기능이 유지되도록 설정함과 동시에, 실행 중인 어플리케이션 서버에도 모니터링 기능을 활성화 합니다. attach.sh가 일회성으로 어플리케이션 서버 프로세스를 식별하고 Tracer를 활성화 합니다.

어플리케이션 서버 재기동에 민감한 환경에 APM 모니터링을 적용할 경우 유용한 방식이며, 어플리케이션 서버 재기동 이후에는 WhaTap의 권장 방식으로 모니터링이 수행되는 방식입니다.

  1. 어플리케이션 서버 실행 스크립트에 JVM 옵션으로 -javaagent 옵션에 Tracer의 파일 경로를 추가합니다.
  2. attach.sh를 실행하여 실행중인 어플리케이션 서버에 Tracer를 활성화 시킵니다.

2.1.2 “javaagent” 방식

어플리케이션 서버 부팅 시에 성능 데이타 수집을 위한 모듈을 주입하는 방식입니다.

  1. 어플리케이션 서버 실행 스크립트에 JVM 옵션으로 -javaagent 옵션에 Tracer의 파일 경로를 추가합니다.
    * Tracer : 성능 데이터 수집을 위한 모듈
  2. 어플리케이션 서버를 재기동 시 Tracer가 어플리케이션 서버의 하위 프로세스로 실행되어 성능 수집 코드를 주입합니다.

2.1.3 “watcher” 방식

Watcher가 별도 프로세스로 실행되어 실행중인 어플리케이션 서버 프로세스를 식별하고 최신 버전의 Tracer를 활성화 시키는 방식입니다. Watcher는 background에서 실행하며, Tracer의 최신 버전이 반영될 경우 이를 감지하여 최신 버전의 Tracer를 활성화 합니다.

본 방식은 backgound에서 실행되는 Watcher가 Tracer의 활성화를 관장하므로, 어플리케이션 서버의 재기동을 필요로 하지 않으므로 어플리케이션 서버 재기동에 민감한 환경에 유용합니다.

Watcher는 Tracer의 식별과 어플리케이션 서버에의 attach 기능을 수행합니다.

  1. Whatcher를 실행합니다.
    Watcher가 어플리케이션 서버 프로세스와 최신 버전의 Tracer를 식별하여 활성화 합니다.
    어플리케이션 서버 재기동 후에도 backgound에서 실행중인 Watcher가 Tracer를 감지하여 활성화 합니다.

“watcher” 방식의 WhaTap APM 모니터링 에이전트는 자체 업데이트 기능을 지원합니다.

  1. whatap.io 사이트의 Management > Agent 설치 메뉴를 통해 신규 버전의 에이전트를 다운로드 하고 압축 패키지 내의 Tracer를 에이전트 설치 경로에 이동합니다. 이후 업데이트 작업은 Watcher가 수행합니다.
    Watcher가 백그라운드에서 WhaTap APM 모니터링 에이전트 폴더 하위에 기존 버전의 Tracer를 신규 버전의 Tracer로 교체하여 활성화 합니다.

“watcher” 방식의 WhaTap APM 모니터링 에이전트 제거를 위해서는 Watcher의 중지, 어플리케이션 서버의 중지, 에이전트 삭제, 어플리케이션 서버 재기동을 필요로 합니다.

에이전트의 코드 인젝션 특성으로 인해 Tracer가 어플리케이션 서버 프로세스로 실행되므로, Watcher 프로세스 중지와 무관하게 모니터링이 수행되기 때문에 에이전트의 중지를 위해서는 어플리케이션 서버의 재기동을 필요로 합니다.

  1. 백그라운드에서 실행 중인 Watcher 프로세스를 중지합니다.
    Tracer 감지 기능이 중지되며, 어플리케이션 서버 재기동 시의 모니터링 활성화 기능도 중단됩니다.
    단, 이미 활성화 되어 있는 Tracer의 모니터링 기능은 영향을 받지 않습니다.
  2. 어플리케이션 서버를 재시작합니다.
    어플리케이션 서버가 모니터링 기능 미탑재 상태로 실행됩니다.

2.2 구성 파일

WhaTap 모니터링 에이전트는 모니터링 정보를 수집하여 서버에 전송하기 위한 Tracer와 “watcher” 방식 활용 시 Tracer를 어플리케이션에 attach하기 위한 Watcher 및 에이전트를 디버깅하기 위한 쉘 스크립트 파일로 구성됩니다.

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

2.2.1 공통 구성 파일

파일명 설명
whatap.agent.tracer-#.#.#.jar Tracer - 웹 어플리케이션 서버 프로세스에 Attach되어 정보를 수집하고 수집된 정보를 서버로 전송하는 프로그램
whatap.conf 어플리케이션 서버의 데이타를 수집하는 수집서버의 주소와 서버의 프로젝트 라이센스 키가 입력되는 파일

2.2.2 “javaagent+onetime attach” 방식 실행 파일

파일명 설명
attach.sh(bat) 실행 중인 어플리케이션 서버에 일회성으로 Tracer를 적용하기 위한 리눅스(Windows)계열 OS용 실행 쉘스크립트

2.2.3 어플리케이션 서버 별 Watcher 실행 파일

파일명 설명
whatap.agent.watcher-#.#.#.jar Watcher - 주기적으로 Java 프로세스를 감시해 어플리케이션 서버 프로세스를 찾아 tracer 프로그램을 어플리케이션 서버 프로세스에 attach 시키고, 새로운 버전의 tracer 설치를 감시해 업데이트된 버전의 tracer를 어플리케이션 서버 프로세스에 attach 시키는 프로그램
watch_tomcat.sh(bat) 실행중인 톰켓을 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
scripts/
watch_springboot.sh(bat)
springboot를 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
실행 파라미터로 모니터링 대상 명시가 필요
scripts/
watch_jboss.sh(bat)
JBoss 6 및 이전 버전의 JBoss를 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
scripts/
watch_jboss_standalone.sh(bat)
JBoss 7 이상 버전의 standalone 실행모드 JBoss를 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
scripts/
watch_jboss_domain.sh(bat)
JBoss 7 이상 버전의 domain 실행모드 JBoss를 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
scripts/
watch_websphere.sh(bat)
WebSphere를 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
scripts/
watch_weblogic.sh(bat)
WebLogic을 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
scripts/
watch_jeus#.sh(bat)
Jeus를 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
#은 jeus 버전
scripts/
watch_jetty.sh(bat)
Jetty를 모니터링 하기 위한 리눅스(Windows) 계열 OS용 Watcher 실행 쉘스크립트
실행 파라미터로 모니터링 대상 명시가 필요
scripts/
watch_app.sh(bat)
실행 파라미터로 주어진 모니터링 대상명을 모니터링 하기 위한 리눅스(Windows) 계열 OS용Watcher 실행 쉘스크립트

2.2.4 유틸리티 구성 파일

파일명 설명
javaproc.sh(bat) 실행중인 자바 프로세스들의 PID와 JVM 옵션을 확인하는 리눅스(Windows)계열 OS용 실행 쉘스크립트
resmon.sh(bat) CPU/Memory/Disk 정보 추출을 위한 리눅스(Windows)계열 OS용 실행 쉘스크립트
proxy.conf 소프트웨어 프록시 설정 파일
proxy.sh(bat) 소프트웨어 프록시 실행을 위한 리눅스(Windows)계열 OS용 실행 쉘스크립트
ping.sh(bat) 서버와의 통신 확인을 위한 위한 리눅스(Windows)계열 OS용 실행 쉘스크립트

2.3 에이전트 실행 및 모니터링 개요

1) Sign-up, Create projects

사용자는 whatap.io 사이트에서 계정을 생성하고 로그인 하여 프로젝트를 생성합니다.
프로젝트 생성 시 WhaTap 에이전트에 설정할 라이센스를 발급받고, 해당 라이센스가 탑재된 에이전트 파일을 다운로드 받습니다.

2) Install Agent

입수한 에이전트 파일을 모니터링 대상 어플리케이션에 설치합니다.
기존 라이센스 설정을 적용한 agent 파일을 재활용 할 경우에 한하여 새로 발급받은 라이센스로 설정을 변경합니다.
WhaTap이 제공하는 2가지 에이전트 실행 방법 중, 적용하고자 하는 방법을 사용하여 에이전트를 실행합니다.

WhaTap은 Java Agent와 Java Attach를 활용하는 2가지 실행 방식을 제공합니다.

3) Transfer Performance Data

실행된 WhaTap 에이전트는 WhaTap 서버로 수집된 어플리케이션 성능 정보를 전송합니다.

4) Analyze Data

WhaTap 서버는 전송된 정보를 저장하고 통계 정보를 추출합니다.

5) Statistics/Reporting

WhaTap은 사용자에 분석된 통계 정보와 보고서를 제공합니다.

3. 에이전트 설치/실행/업데이트/종료

WhaTap APM 모니터링 서비스를 사용하기 위해서는 모니터링 대상 어플리케이션 서버에 WhaTap APM 모니터링 에이전트를 설치해야 합니다.
WhaTap APM 모니터링 에이전트 설치 방법은 whatap.io 사이트에서 압축된 에이전트 파일을 다운로드 받아 서버 임의의 위치에 압축을 풀어 실행하는 것만으로 설치가 완료됩니다.

3.1 공통

  1. 브라우저를 통해 whatap.io 사이트에 방문합니다.

  2. 계정을 생성하고 로그인합니다.

  3. APM 제품을 선택합니다.

  4. 프로젝트를 생성합니다. 1번 아이콘을 클릭하면 2번 팝업이 뜹니다. 프로젝트 이름과 수집 서버 위치를 선택 후 확인 버튼을 클릭합니다.

    프로젝트명에는 공백 문자를 사용할 수 없습니다.

  5. 프로젝트의 Setup 버튼을 클릭하여 관리 화면에 진입합니다.

    프로젝트 Setup 완료 후에는 하기 경로를 통해 접근 할 수 있습니다.

    • whatap.io 사이트에 로그인 > “APM” 제품 선택 > 프로젝트의 Management > Agent 설치 서브 메뉴 선택

  6. 프로젝트 관리화면에서 라이센스를 발급 받습니다.

  7. 프로젝트 관리화면에서 에이전트 파일을 다운로드 받습니다.

  8. 어플리케이션 서버가 설치된 서버에 접속하고, 다운로드 받은 에이전트 파일을 업로드 및 압축 해제 합니다.

    (주의) 어플리케이션 서버의 에이전트 모듈 다운로드 패스상에 공백은 사용하지 않도록 합니다.
    $WHATAP_HOME 은 WhaTap APM 모니터링 에이전트의 설치 경로를 가리키며, 이후 본 문서에서 이와 같이 기술합니다.

  9. $WHATAP_HOME/whatap.conf 파일에 서비스 페이지에서 발급받은 라이센스 키와 수집 서버 주소가 설정되어 있는지 확인합니다.

    (주의) 에이전트는 수집 서버 주소로 어플리케이션 서버의 성능 정보를 전송합니다. 그러므로 방화벽에 수집 서버 IP로의 TCP Outbound Port(6600)가 차단되어 있으면 안됩니다.

    (주의) wget으로 터미널에서 에이전트 모듈을 다운로드 받거나, 에이전트 모듈을 복제하여 사용하는 경우, 서비스 페이지에서 발급받은 라이센스 키와 서버 주소를 설정 파일(whatap.conf)에 직접 추가해야 합니다.

  10. $WHATAP_HOME/scripts 디렉토리에서 실행스크립트 파일(watch_xxxx.sh(bat))을 $WHATAP_HOME 디렉토리에 복사합니다.

    “watcher” 방식으로 구동하는 경우에만 필요한 절차입니다.

    linux 계열의 경우, 실행스크립트 파일에 실행 권한을 부여합니다.

    									chmod +x watch_xxxx.sh
              
    								
  11. $WHATAP_HOME 경로로 이동하여 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
              
    							

이후 절차는 에이전트의 구동 방식에 따라 절차가 상이하므로 주의가 필요하겠습니다.

3.2 “javaagent+onetime attach” 방식

실행 중 어플리케이션 서버에는 attach 방식으로 모니터링 기능을 적용하고, 어플리케이션 서버의 재기동 시점에 “javaagent” 방식을 적용합니다. 실행 상태의 어플리케이션 서버를 재기동 하지 않고 모니터링을 수행하고, 어플리케이션 서버 재기동 시에는 권장 설치 방식으로 모니터링 기능을 적용합니다.

본 방식은 attach.sh(bat) 파일을 실행하여 적용하며, 실행 파라메타로 PID(프로세스 ID)를 사용합니다.
최초 실행 시 attach.sh(bat)를 실행하는 과정을 제외하고 설치/실행/업데이트/종료 절차는 “javaagent” 방식과 동일합니다.

3.2.1 사전 확인

linux 계열의 경우 ps 명령을, windows 계열의 경우 작업관리자를 통해 실행 중인 어플리케이션 서버의 PID를 확인합니다.

Tomcat 예시(linux 계열)

						$ 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
          
					

3.2.2 설치

3.3 “javaagent” 방식3.3.1 설치와 동일하게 어플리케이션 서버 JVM 옵션에 -javaagent 설정을 추가합니다.

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

3.2.3 실행

$WHATAP_HOME 경로 하위에서 3.2.1 사전 확인에서 확인한 PID를 파라메타로 부여하여 attach.sh(bat)를 실행합니다.
에이전트 정상 동작 확인 절차는 “javaagent” 방식 및 “watcher” 방식과 동일합니다.

						$ ./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
          
					

3.3 “javaagent” 방식

어플리케이션 서버의 재부팅을 필요로 합니다.

3.3.1 설치

어플리케이션 서버 JVM 옵션에 -javaagent 설정을 추가합니다.

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

-javaagent 프로퍼티 값은 $WHATAP_HOME/whatap.agent.tracer-#.#.#.jar의 full file path 입니다.
어플리케이션 서버에 따라 별도의 프로퍼티를 추가해야 하는 경우가 있으며, 5. 어플리케이션 서버 별 적용절차에 제시합니다.

Tomcat 예시(linux 계열)

						
							#   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 ############
          export JAVA_OPTS=" -javaagent:/whatap/whatap.agent.tracer-0.4.2.jar "
          ########## WHATAP ############
          
					

항상 $WHATAP_HOME 하위에 설치된 최상위 버전의 agent로 기동하고자 하는 경우, 하기의 스크립트를 참조하여 적용합니다.

							
								########## WHATAP ############
          WHATAP_HOME=/whatap
          WHATAP_JAR=`ls ${WHATAP_HOME}/whatap.agent.tracer-*.jar | sort | tail -1`
          JAVA_OPTS=" -javaagent:${WHATAP_JAR} "
          ########## WHATAP ############
          
						

Tomcat 예시(Windows 계열)

						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 ############
          set JAVA_OPTS= -javaagent:C:\whatap\whatap.agent.tracer-0.4.2.jar 
          rem ########## WHATAP ############
          
					

항상 $WHATAP_HOME 하위에 설치된 최상위 버전의 agent로 기동하고자 하는 경우, 하기의 스크립트를 참조하여 적용합니다.

							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%
          setlocal
          set JAVA_OPTS= -javaagent:%WHATAP_HOME%\%WHATAP_JAR% 
          rem ########## WHATAP ############
          
						

3.3.2 실행

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

Tomcat 예시

						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.io 사이트에 로그인 > “APM” 제품 선택 > JVMP 메뉴 선택 > More의 Boot Environment 메뉴를 선택하고 whatap.name과 whatap.type을 확인합니다.

whatap.name - JVMP 메뉴 선택 시 표시되는 Application Server List의 Application에 표시되는 서버 식별용 명칭 포맷입니다. 마지막 요소가 {pid}인 경우 어플리케이션 서버의 서비스 포트가 인식되지 않은 것으로 Application의 마지막 항목에 표시되는 PID(프로세스 ID)를 참조하여 설치 문제에 대응합니다.

4.1. watch_xxx.sh(bat) 실행 시, “[WhaTap] Attach tracer to xxxx” 메세지를 확인할 수 없는 경우를 참조합니다.

whatap.type - 어플리케이션 서버 종류가 표시됩니다.

3.3.3 업데이트

에이전트 설치 파일을 다운로드 받아 압축을 풀고, whatap.agent.tracer-#.#.#.jar 파일을 $WHATAP_HOME폴더에 복사합니다.

어플리케이션 서버의 JVM 옵션의 -javaagent 설정을 새로 설치된 whatap.agent.tracer-#.#.#.jar로 수정하고, 어플리케이션 서버를 재기동 합니다.

어플리케이션 서버 재기동 시 항상 최상위 버전으로 적용하고자 하는 경우 3.3.1 설치에서 제시한 스크립트를 참조하여 적용합니다.
구 버전의 whatap.agent.tracer-#.#.#.jar 파일을 삭제하고자 하는 경우, 어플리케이션 서버 재기동 이후에 삭제합니다.

3.3.4 종료

어플리케이션 서버 JVM 옵션의 -javaagent 설정을 삭제하고, 어플리케이션 서버케이션 서버를 재기동 합니다.

에이전트를 삭제하고자 하는 경우, 어플리케이션 서버 재기동 이후에 삭제합니다.

3.4 “watcher” 방식

어플리케이션 서버의 재부팅을 필요로 하지 않습니다.

3.4.1 사전 확인

어플리케이션 서버의 실행 계정 및 JDK 정보를 확인합니다.

  • 윈도우즈 계열 OS

    TaskManager를 통해 어플리케이션 서버 프로세스를 찾고 프로세스가 어떤 USER 및 JDK로 실행되었는지 확인합니다.
    Windows OS 종류에 따라 TaskManager의 UI가 상이하며, 프로세스, 어플리케이션, USER정보를 확인 할 수 있습니다.

    Windows7 예시

    1. 어플리케이션 서버의 프로세스 확인
      TaskManager > 어플리케이션 서버 선택 > 마우스 오른쪽 클릭 > Go to Process 클릭

    2. TaskManager > Process 탭에서 어플리케이션 서버 프로세스의 실행 USER 및 JDK 정보를 확인합니다.


  • 리눅스 계열 OS

    “ps -ef” 명령어를 통해 UID(사용자 계정) 및 JDK 정보를 확인합니다.

    예시

    									$ ps -ef | grep java | grep -v "grep"
              ec2-user  2625     1  2 09:28 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
              
    								

    위 예시에서 실행 계정은 ec2-user, 프로세스 ID는 2625임을 확인 할 수 있습니다.

현재 로그인 계정이 어플리케이션 서버의 실행 계정과 다른 경우 어플리케이션 서버의 실행 계정으로 사용자를 전환합니다.

  • 윈도우즈 계열 OS

    윈도우즈 OS계열에서는 Sign out이나 사용자 전환 기능을 활용하여 로그아웃 후 어플리케이션 서버 실행 계정으로 로그인합니다.

  • 리눅스 계열 OS

    리눅스 OS계열에서는 “sudo su 전환 계정” 명령어를 실행하거나, 로그 아웃 후 어플리케이션 서버 실행 계정으로 다시 로그인합니다.

현재 JAVA_HOME 환경변수가 설정되어 있지 않거나 설정된 JAVA_HOME 환경변수가 어플리케이션 서버 실행 JDK와 다른 경우, JAVA_HOME 환경변수를 어플리케이션 서버 실행 JDK패스로 설정합니다.

  • 윈도우즈 계열 OS
    제어판 > 고급 시스템 설정 > 고급탭의 환경변수 > 시스템 변수에 JAVA_HOME 변수 추가

  • Linux 계열 OS

    								
    									export JAVA_HOME="/home/vagrant/jdk1.7.0_80"
              
    							

3.4.2 실행

$WHATAP_HOME 하위로 이동하여 watch_xxx.sh(bat)를 실행합니다.

  • 윈도우즈 계열 OS

    • foreground로 실행

      										watch_xxx.bat
                
      									
    • backgound로 실행
      watch_xxx.bat 파일의 java.exe를 javaw.exe로 수정하고 하기와 같이 실행합니다.

      										start /B watch_xxx.bat
                
      									
  • Linux 계열 OS

    								./watch_xxx.sh &
              
    							

$WHATAP_HOME/log 하위에 3개의 log 파일을 확인하여 에러 메세지 출력 되지 않았는지 확인하고, whatap-watcher-yyyymmdd.log 파일에 Tracer가 어플리케이션 서버 프로세스에 attach 되었다는 메세지의 출력 여부를 확인합니다.

Tomcat의 경우 하기 3개의 로그 파일이 생성됩니다.

  • whatap-boot-yyyymmdd.log - Watcher 기동과 관련된 로그가 출력됩니다. 출력 내용이 없으면 정상입니다.
  • whatap-TC-7-105-8080-yyyymmdd.log - Watcher가 서버와의 정상 handshake 수행 후에 출력되는 파일입니다. whatap.error 항목이 존재하지 않거나 해당 상목에 에러가 출력되지 않으면 정상입니다.
  • whatap-watcher-yyyymmdd.log - Watcher의 동작과 관련된 로그가 출력됩니다. Tracer를 어플리케이션 서버에 Attach 하였다는 메세지가 출력되면 정상입니다.

whatap.io 사이트에 로그인 > “APM” 제품 선택 > JVMP 메뉴 선택 > [More]의 [Boot Environment] 메뉴 선택에서 whatap.name과 whatap.type을 확인합니다.

whatap.name - JVMP 메뉴 선택 시 표시되는 Application Server List의 Application에 표시되는 서버 식별용 명칭 포맷입니다. 마지막 요소가 {pid}인 경우 어플리케이션 서버의 서비스 포트가 인식되지 않은 것으로 Application의 마지막 항목에 표시되는 PID(프로세스 ID)를 참조하여 설치 문제에 대응합니다.
JEUS의 경우에는 마지막 요소가 {container}이어야 합니다.

4.1. watch_xxx.sh(bat) 실행 시, “[WhaTap] Attach tracer to xxxx” 메세지를 확인할 수 없는 경우를 참조합니다.

whatap.type - 어플리케이션 서버 종류가 표시됩니다.

Watcher가 실행되면 $WHATAP_HOME 하위에 watcher-{pid}.whatap 형식의 파일이 생성되며, 본 파일은 Watcher를 중지 시에 활용합니다.

Windows 계열 예시

linux 계열 예시

3.4.3 업데이트

$WHATAP_HOME에 신규 버전의 Tracer를 추가합니다.

3.4.4 중지

$WHATAP_HOME 하위의 watcher-{pid}.whatap 파일을 삭제하여 Watcher를 중지합니다.

Watcher는 해당 파일을 감시하다가 파일이 삭제되면, 스스로 프로세스를 종료합니다.
어플리케이션 서버를 재기동 합니다.
에이전트의 코드 인젝션 특성으로 인해 Tracer가 어플리케이션 서버 프로세스로 실행되고 있어, Watcher 프로세스 중지와 무관하게 모니터링이 수행되므로 어플리케이션 서버의 재기동을 필요로 합니다.

$WHATAP_HOME을 삭제합니다.

4. 설치 에러 대응

4.1. watch_xxx.sh(bat) 실행 시, “[WhaTap] Attach tracer to xxxx” 메세지를 확인할 수 없는 경우

  • 어플리케이션 서버와 에이전트 프로세스의 실행 USER 확인, 실행 JDK 확인

  • JAVA_HOME 환경변수와 어플리케이션 서버 실행 JDK의 일치 여부 확인

    에이전트는 내부적으로 JAVA_HOME 환경 변수를 참조해서 라이브러리를 찾습니다. 또한 JAVA_HOME 환경변수에 잡힌 JDK로 실행된 어플리케이션 서버 프로세스를 찾습니다.

  • watch_xxx.sh(bat)스크립트에 명시된 모니터링 이름 확인

    $WHATAP_HOME/javaproc.sh(bat) 스크립트를 실행하여, 실행중인 Java 프로세스의 PID와 JVM 옵션을 확인합니다.

    Tomcat예시

    스크립트의 실행 결과에 어플리케이션 서버 프로세스가 보이지 않는다면, javaproc.sh을 실행시킨 USER와 JDK가 어플리케이션 서버를 실행시킨 USER와 JDK가 상이하기 때문입니다.
    Tomcat의 경우, Tomcat 임을 식별 가능한 catalina를 $WHATAP_HOME/watch_xxx.sh(bat) 파일의 -Dwhatap.monitor 옵션에 설정합니다.

    									JAVA_OPTS="${JAVA_OPTS} -Dwhatap.monitor=catalina "
              
    								

  • 방화벽 설정 확인

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

    수집서버 주소 정보는 whatap.io 사이트의 하기 경로를 통해 확인 할 수 있습니다.
    “APM” 제품 선택 > 프로젝트의 Dashboard 버튼 선택 > 프로젝트의 Management 메뉴 선택 > Agent 설치 서브 메뉴 선택

    방화벽 확인 방법 (telnet 서버IP 서버포트)
    telnet 명령 수행 시 하기와 같이 접속 관련 정보가 표시되어야 정상입니다.

    								$ telnet 52.193.60.176 6600
              Trying 52.193.60.176...
              Connected to 52.193.60.176.
              Escape character is '^]'.
              
    							

4.2. 어플리케이션 서버 서비스 포트가 감지되지 않는 경우

모니터링 대상은 인식하였으나 서비스 포트를 감지하지 못하는 경우, 에이전트는 WhaTap 서버로 포트 대신 PID(프로세스 ID)를 전송합니다. 이는 WhaTap 사이트의 모니터링 대상 서버 목록을 통해 포트가 감지되지 않은 서버를 PID로 식별하여 조치 할 수 있도록 하기 위함입니다.

서비스 포트 감지에 실패한 어플리케이션 서버 확인을 위하여 WhaTap 사이트의 하기 경로를 통해 어플리케이션 서버 정보를 확인합니다.

whatap.io 사이트에 로그인 > “APM” 제품 선택 > 프로젝트의 JVMP 메뉴 선택 > 해당 서버의 More 버튼 클릭 > Boot Environment 선택

Tomcat 예시

이런 경우 아래와 같이 어플리케이션 서버 실행스크립트에 명시된 JVM 옵션에 whatap.port 시스템 프로퍼티를 추가한 후 어플리케이션 서버를 재기동 합니다.

						JAVA_OPTS="${JAVA_OPTS} -Dwhatap.port=8080 "
          
					

어플리케이션 서버 별 JVM 옵션 설정 파일은 5. 어플리케이션 서버 별 적용절차에 제시합니다.

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

6.x 버전 이상의 JBOSS EAP, 7.0 이상 버전의 JBOSS AP, WEBSPHERE와 같이 OSGi프레임웍 구조의 어플리케이션 서버 실행 파일의 JVM 옵션에 에이전트 패키지 prefix(whatap)을 등록합니다.

OSGi 어플리케이션에서 에이전트 클래스 참조를 위해 추가하는 설정입니다.

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

WEBSHERE와 같이 Default로 * 가 설정되어 있는 경우는 별도의 설정이 필요하지 않습니다.

4.4. 서버명을 임의로 부여하여 관리하고 싶은 경우

에이전트는 어플리케이션 서버 종류와 어플리케이션 서버의 IP, 서비스 포트를 사용하여 자동으로 서버명을 부여 합니다.

자동으로 부여된 이름 대신 직접 어플리케이션 서버 별로 이름을 부여하고 싶은 경우, 아래와 같이 어플리케이션 서버 JVM 옵션으로 어플리케이션 서버명을 명시적으로 기입해 줍니다.

Jetty 예시
JVM 옵션에 -Dwhatap.name=sales1-192-168-111 를 지정한 예시입니다.

Jetty 및 에이전트 실행 후, WhaTap 사이트의 하기 경로에서 등록한 이름으로 서버가 등록된 것을 확인 할 수 있습니다.

whatap.io 사이트에 로그인 > “APM” 제품 선택 > 프로젝트의 JVMP 메뉴 선택

다만, 프로젝트에 등록된 어플리케이션 서버 별로 동일한 이름이 사용되면 안되므로 서버명을 고정으로 사용해서는 안됩니다. internal ip address로 인해 서버 ip가 중복되는 경우는 어플리케이션 서버명을 그룹 단위로 패턴화하여 적용합니다.

패턴 옵션 설명
type 어플리케이션 서버 유형
ipN ip address의 N 번째 자리
port 어플리케이션 서비스 포트
pid 어플리케이션 프로세스 ID

패턴 예시

						
							# default pattern
          -Dwhatap.name={type}-{ip2}-{ip3}-{port}
          # group A
          -Dwhatap.name=groupA-{type}-{ip2}-{ip3}-{port}
          # group B
          -Dwhatap.name=groupB-{type}-{ip2}-{ip3}-{port}
          
					

4.5. HITMAP 그래프에서 트랜잭션이 잡히지 않는 경우

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

어플리케이션 서버 JVM 옵션 설정을 GUI로 하는 예제는 5. 어플리케이션 서버 별 적용절차에 제시합니다.

4.6. 에이전트 실행 시 MBeanServerBuilder 에러가 발생하는 경우(JBoss 5.0 이하)

$WHATAP_HOME/logs/whatap-{SERVER_NAME}-{DATE}.log 파일의 whatap.error에 해당 에러가 출력된 경우 하기 JVM 옵션을 설정합니다.

  • -Djboss.platform.mbeanserver를 true로 설정합니다.

    설정 추가 예

4.7. 에이전트 실행 시 logmanager 관련 에러가 발생하는 경우(JBoss 7.0 이상, EAP 6.0이상)

$WHATAP_HOME/logs/whatap-{SERVER_NAME}-{DATE}.log 파일의 whatap.error에 해당 에러가 출력된 경우 하기 JVM 옵션을 설정합니다.

  • -Djava.util.logging.manager에 LogManager package명 설정
  • -Xbootclassloader에 JBoss log manager JAR file 설정

    설정 추가 예

4.8. “watcher” 방식으로 Watcher를 서비스로 등록하여 실행 시 에러가 발생하는 경우(Windows 계열)

Windows 계열 OS에서 “watcher” 방식으로 Watcher를 서비스로 등록하고 실행 시 다음과 같이 에러가 발생하므로 “javaagent” 방식을 사용합니다.

						C:\whatap>sc create watcher binPath=C:\whatap\watch_tomcat.bat depend=tomcat7
          [SC] CreateService 성공

          C:\whatap>sc start watcher
          [SC] StartService 실패 1053:

          서비스가 시작이나 제어 요청에 빠르게 응답하지 않았습니다.
          
					

5. 어플리케이션 서버 별 적용절차

5.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 편집
Jeus $JEUS_HOME/config/$hostname/JEUSMain.xml
Jetty watch_jetty.sh(bat)

5.2 어플리케이션 서버 별 Watcher 실행 스크립트 (“watcher” 방식)

“watcher” 방식으로 에이전트를 실행하는 경우에 해당합니다.

어플리케이션 서버 실행 스크립트
Tomcat $WHATAP_HOME/watch_tomcat.sh(bat)
SpringBoot $WHATAP_HOME/watch_springboot.sh(bat)
JBoss 5.0 이하 $WHATAP_HOME/watch_jboss.sh(bat)
JBoss AS 7.0 이상
EAP 6.0이상
standalone 모드
$WHATAP_HOME/watch_jboss_standalone.sh(bat)
JBoss AS 7.0 이상
EAP 6.0이상
domain 모드
$WHATAP_HOME/watch_jboss_domain.sh(bat)
WebLogic $WHATAP_HOME/watch_weblogic.sh(bat)
WebSphere N/A
“javaagent” 방식만 지원
Jeus $WHATAP_HOME/watch_jeusX.sh(bat)
X:Jeus 버전
Jetty $WHATAP_HOME/watch_jetty.sh(bat)

5.3 Tomcat on Windows Service (“javaagent” 방식)

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

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

5.4 Springboot (“javaagent” 방식)

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

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

5.5 JBoss

5.5.1 JBoss (“javaagent+onetime attach” 방식)

  • 1. 5.5.2 JBoss (“javaagent” 방식)과 동일하게 JVM 옵션을 추가합니다.

    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=" -javaagent:${WHATAP_JAR} -Djboss.modules.system.pkgs=whatap "
              ########## WHATAP ############
              
    							
  • 2. JBOSS의 PID(프로세스 ID)를 확인합니다.

    								$ ps -ef | grep jboss | grep -v 'grep'
              ec2-user 27757 27714 13 12:21 pts/2    00:00:03 /jdk1.7.0_79/bin/java -D[Standalone] -server -XX:+UseCompressedOops -XX:+TieredCompilation -Djboss.modules.system.pkgs=whatap -Dorg.jboss.boot.log.file=/jboss-as-7.1.1.Final/standalone/log/boot.log -Dlogging.configuration=file:/jboss-as-7.1.1.Final/standalone/configuration/logging.properties -jar /jboss-as-7.1.1.Final/jboss-modules.jar -mp /jboss-as-7.1.1.Final/modules -jaxpmodule javax.xml.jaxp-provider org.jboss.as.standalone -Djboss.home.dir=/jboss-as-7.1.1.Final
              
    							
  • 3. attach.sh 스크립트를 실행합니다.

    								$ ./attach.sh 27757
              JAVA_HOME=/jdk1.7.0_79
              _      ____       ______
              | | /| / / /  ___ /_  __/__ ____
              | |/ |/ / _ \/ _ `// / / _ `/ _ \
              |__/|__/_//_/\_,_//_/  \_,_/ .__/
                                    /_/
              Just Tap, Always Monitoring
              WhaTap Agent version 0.4.5 20161207
              Admin: ec2-user
              PID: 27848
              Java Path: /jdk1.7.0_79/jre
              Java Version: 1.7.0_79
              AttachAgent Success :  [27757] /jboss-as-7.1.1.Final/jboss-modules.jar -mp /jboss-as-7.1.1.Final/modules -jaxpmodule javax.xml.jaxp-provider org.jboss.as.standalone -Djboss.home.dir=/jboss-as-7.1.1.Final
              $
              
    							

5.5.2 JBoss (“javaagent” 방식)

  • 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=" -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)]
              
    							

5.5.3 JBoss (“watcher” 방식)

  • 1.JVM 옵션의 -Djboss.modules.system.pkgs에 설정을 추가합니다.

    어플리케이션 서버 버전 JVM 옵션
    JBOSS 7.0 이상
    EAP 6.0이상
    JVM 옵션의 -Djboss.modules.system.pkgs 환경 변수에 “whatap” prefix 추가

    standalone.sh 설정 추가 예

    								
    									#!/bin/sh
              ########## WHATAP ############
              JAVA_OPTS=" $JAVA_OPTS -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.Watcher를 실행합니다.

    								$ ./watch_jboss_standalone.sh &
              [1] 27133
              $ JAVA_HOME=/jdk1.7.0_79
              _      ____       ______ WATCHER
              | | /| / / /  ___ /_  __/__ ____
              | |/ |/ / _ \/ _ `// / / _ `/ _ \
              |__/|__/_//_/\_,_//_/  \_,_/ .__/
                                    /_/
              Just Tap, Always Monitoring
              WhaTap Watcher Agent version 0.4.5 20161207
              20161208 12:00:51 [WhaTap] Admin: ec2-user
              20161208 12:00:51 [WhaTap] PID: 27138
              20161208 12:00:51 [WhaTap] Java Path: /jdk1.7.0_79/jre
              20161208 12:00:51 [WhaTap] Java Version: 1.7.0_79
              20161208 12:00:51 [WhaTap] Target App: org.jboss.as.standalone
              20161208 12:00:51 [WHATAP-804] Whtatap Watcher Agent Started
                  -Dwhatap.server.host=[52.78.209.94, 52.78.224.235]
                  -Dwhatap.server.port=6600
              20161208 12:00:51 [WHATAP-812] OID : -740129336 ONAME: watcher-0-88-0
              20161208 12:00:51 [WHATAP-806] The license key is ok
              20161208 12:00:51 [WHATAP-807] New session is ready 52.78.209.94:6600
              20161208 12:00:51 [WhaTap] Attach tracer to [27050] /jboss-as-7.1.1.Final/jboss-modules.jar -mp /jboss-as-7.1.1.Final/modules -jaxpmodule javax.xml.jaxp-provider org.jboss.as.standalone -Djboss.home.dir=/jboss-as-7.1.1.Final
              
    							

5.5.4 에이전트 실행 에러 대응

에이전트 실행 시 $WHATAP_HOME/logs/whatap-{SERVER_NAME}-{DATE}.log 파일의 whatap.error에 에러가 출력된 경우 4.6. 에이전트 실행 시 MBeanServerBuilder 에러가 발생하는 경우(JBoss 5.0 이하)4.7. 에이전트 실행 시 logmanager 관련 에러가 발생하는 경우(JBoss 7.0 이상, EAP 6.0이상)을 참조하여 JVM 옵션을 추가합니다.

whatap.error 출력 예

5.6 Weblogic (“javaagent” 방식)

“javaagent” 방식 적용 시의 설정 예를 제시합니다.

설정 위치 : $WEBLOGIC_HOME/user_projects/domains/사용자도메인/bin/startWebLogic.sh(bat)
-javaagent 프로퍼티 설정을 추가합니다.

$WEBLOGIC_HOME은 WebLogic 설치 경로를 가리킵니다.

설정 예

5.7 WebSphere (“javaagent” 방식)

IBM JDK의 경우 제약사항으로 인해 “watcher” 방식으로 에이전트를 실행시킬 경우 트랜잭션 정보가 수집되지 않으므로 “javaagent” 방식만 지원하며, Web Console을 통한 설정 방법을 제시합니다.

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

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

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

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

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

    Environment > Virtual hosts 선택 > 서비스 호스트 선택 > Host Aliases 선택하여 서비스 포트를 확인합니다.

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

    리눅스 계열
    -javaagent:/home/wasadmin/whatap/whatap.agent.tracer-#.#.#.jar -Dwhatap.port=9443

    윈도우 계열
    -javaagent:C:\whatap\whatap.agent.tracer-#.#.#.jar -Dwhatap.port=9443

5.8 Jeus (“javaagent” 방식)

“javaagent” 방식을 적용하는 경우, 다음 절차를 통해 설치합니다.

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

    이후 본 문서에서 $JEUS_HOME은 JEUS 설치 경로를 가리킵니다.

  2. 어플리케이션 서버를 재기동시킵니다.

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

    로그 파일 위치
    에이전트 $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)

  4. 에이전트가 어플리케이션 서버의 종류와 어플리케이션 서버의 서비스 container명을 인식했는지 확인합니다.

    WhaTap 사이트에서 whatap.name과 whatap.type을 확인합니다.

    whatap.io 사이트에 로그인 > “APM” 제품 선택 > 프로젝트의 JVMP 메뉴 선택 > 설치한 JEUS 서버 > Boot Environment 메뉴 선택을 통해 확인합니다.

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

5.9 Jetty

JVM 옵션에 whatap.port를 설정해야 합니다.

5.9.1 Jetty (“javaagent” 방식)

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

  • Jetty 실행 스크립트
    $JETTY_HOME/bin/jetty.sh 파일에 JVM 옵션을 추가합니다.

    이후 본 문서에서 $JETTY_HOME은 Jetty 설치 경로를 가리킵니다.

  • java 실행 옵션에 설정
    $JETTY_HOME/bin 경로로 이동 후, 하기 옵션을 적용하여 Jetty를 기동합니다.

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

5.9.2 Jetty (“watcher” 방식)

JVM 옵션에 whatap.port를 추가합니다.

  • Jetty 실행 스크립트
    $JETTY_HOME/bin/jetty.sh 파일에 JVM 옵션을 추가합니다.

  • java 실행 옵션에 설정
    $JETTY_HOME/bin 경로로 이동 후, 하기 옵션을 적용하여 Jetty를 기동합니다.

    								$ java -jar start.jar -Dwhatap.port=8080 &
              
    							

6. 확장 기능

6.1. Plugin

WhaTap APM 모니터링은 에이전트 단의 프로파일 등의 추가적 기능을 제공하기 위하여 plugin 확장 기능을 제공합니다.
$WHATAP_HOME/plugin 하위에 .x 확장자를 가지는 스크립트 파일을 추가하고, 파일 내부에 java code를 작성하여 WhaTap APM 모니터링이 기본적으로 제공하는 기능에 부가적인 기능을 추가 할 수 있습니다.

.x 확장자 파일에 저장되는 코드는 bytecode instrumentation에 의해 주입되기 때문에 모니터링 대상의 성능 저하를 가져오지 않습니다.

사용예
모니터링 대상 서버에 HTTP 프로토콜을 통한 사용자 요청이 유입되는 타이밍에 테스트 문자열을 출력하기 위한 예시입니다.

WhaTap 에이전트가 구동된 이후, 어플리케이션 서버 재기동 없이 .x 확장자 파일을 추가하여 활용가능합니다.

위 예시에서 $ctx.profile(…)와 같이, 사용자 요청에 대한 프로파일 정보를 추가적으로 수집하여 서버에 전송하기 위한 기능도 제공합니다.
구체적인 활용법이 필요한 경우 WhaTap에 문의주시기 바랍니다.

6.2. Proxy

6.2.1 개요

모니터링 서버로 부터의 외부망에의 직접적인 접근을 차단하고 단일 채널을 통해 외부로의 접속을 허용하고자 하는 경우, TCP/UDP Proxy 서버를 구성하여 WhaTap 서버에 데이타를 전송 할 수 있습니다.
사용자가 직접 Proxy 서버를 구성하기 어려운 상황이라면, WhaTap이 제공하는 Software 기반의 WhaTap Proxy를 활용 할 수 있습니다.
이를 통해 사용자는 다수의 서버가 직접 외부망에 접속하지 직접 접속하지 않고, WhaTap Proxy를 경유하도록 제어 할 수 있습니다.

6.2.2 설치

설치 과정은 에이전트의 설치 과정과 동일합니다.
WhaTap Proxy를 설치할 서버에 다운로드 받은 에이전트 파일의 압축을 해제합니다.

이후 압축 해제 경로를 $WHATAP_HOME로 기술합니다.

6.2.3 설정

  • WhaTap Proxy의 설정은 $WHATAP_HOME 하위의 proxy.conf 파일을 생성하여 설정합니다.

    whatap.conf 설정의 whatap.server.host의 설정을 복사합니다.
    proxy의 리스닝 포트를 지정합니다.

    proxy.conf 예시

    								whatap.server.host=52.78.209.94/52.78.224.235
              listen_port=6600
              
    							
  • 어플리케이션 서버에 탑재된 에이전트 설정을 수정하여 WhaTap Proxy로 데이터를 전송할 수 있도록, whatap.conf 설정의 호스트와 포트 설정을 변경합니다.

    whatap.conf 예시

    								license=...
              whatap.server.host={WhaTap Proxy를 설치한 서버의 IP}
              whatap.server.port=6600
              
    							
  • WhaTap Proxy 실행 스크립트를 생성하고 실행 권한을 부여합니다.

    proxy.sh 예시

    								
    									#!/usr/bin/env bash
              EXE_JAR=`ls *.proxy* | sort | tail -1`
              ${JAVA_HOME}/bin/java  ${JAVA_OPTS} -jar $EXE_JAR
              
    							

    실행권한 부여

    								$ chmod +x proxy.sh
              
    							

6.2.4 실행

proxy.sh를 실행하고, {PID}.proxy.run 파일이 생성되는 것을 확인합니다.

						./proxy.sh &
          
					

$WHATAP_HOME/logs 하위의 로그 파일을 확인합니다.

						
							20161116 10:19:14 [WhaTap] LISTEN PORT: 6600
          
					

6.2.5 종료

{PID}.proxy.run 파일을 삭제합니다.

6.3. 에이전트 Ping

모니터링 기능을 적용하기에 앞서 Tracer와 서버 간의 통신에 문제가 없는지 확인하기 위한 기능을 제공합니다.
사용자는 ping.sh 를 실행하여 에이전트를 통해 가상의 모니터링 정보를 서버로 송신할 수 있으며, whatap.io 사이트에 정보가 정상 송신되는 지의 여부를 확인 할 수 있습니다.

6.3.1 실행

						$ ./ping.sh
          JAVA_HOME=/jdk1.8.0_111
           _      ____       ______
          | | /| / / /  ___ /_  __/__ ____
          | |/ |/ / _ \/ _ `// / / _ `/ _ \
          |__/|__/_//_/\_,_//_/  \_,_/ .__/
                                    /_/
          Just Tap, Always Monitoring
          WhaTap Agent version 0.4.5 20161207
          20161208 09:02:25.003 SEND PING DATA
          20161208 09:02:25.510 SEND PING DATA
          ...
          
					

6.3.2 확인

에이전트가 설치된 서버와 수집 서버 간의 통신이 정상적으로 수행되었다면 whatap.io 사이트에서 하기와 같은 화면을 확인 할 수 있습니다.

  • Dashboard
    가상의 액티브 트랜젝션 수가 30으로 나타납니다.

  • JVMP
    서버로 데이터를 송신중인 가상의 에이전트가 NET-PING-{PID}의 어플리케이션 명으로 등록되어 있는 것을 확인 할 수 있습니다.

6.4. AES 256 암호화 통신

WhaTap APM 에이전트는 수집된 데이터를 암호화 하여 서버로 전송합니다. 데이터의 중요도나 설정에 따라 이를 변경할수 있습니다. 기본적으로 XOR연산과 AES 알고리즘을 통한 함호화를 사용하며 평문을 128비트 단위로 나누어 암호화, 복호화를 수행하며, 사용자의 설정에 따라 256비트까지 확장할 수 있습니다.

6.4.1 Java JCE(Java Cryptography Extension) 패치

기본적으로 JCE는 128비트를 지원하고 있기 때문에 AES 256비트를 적용하기 위해서는 아래 패치를 통해 256비트까치 확장해서 사용할 수 있게 해야 합니다.

기본적인 환경에서 AES 256 적용시 다음과 같은 오류 발생

						Unsupported keysize or algorithm parameters.
          혹은,
          Illegal key size or default parameters.
          
					

JCE 다운로드 링크

6.4.2 WhaTap Agent에 설정 변경

WhaTap APM Agent가 설치된 디렉토리에서 whatap.conf 파일에 아래와 같은 설정을 추가 합니다.

cypher_level=256 설정을 추가 한 후 WAS를 재기동합니다.

						license=x41ld2345duj-x03nv02ne0fn40-zlfj923enfld
          whatap.server.host=52.78.209.94/52.78.224.235
          cypher_level=256
          
					

7. 제약 사항

  • whatap.io 사이트에서 프로젝트 생성 시, region은 중복 선택이 불가하며 복수의 region을 활용하는 경우 별도의 프로젝트를 생성해야 합니다.
  • Cloud 환경과 같이 복수의 region에 서버가 존재하는 경우, 네트워크 latency 등 성능 정보 수집 상의 제약 사항을 회피하기 위하여 region 단위로 수집 서버를 위치시켜야 합니다. WhaTap은 고객 요구 사항에 부응하기 위하여 region 별로 수집 서버를 구축합니다.
  • WhaTap APM 모니터링은 에이전트의 식별을 위한 용도로 에이전트의 IP Address와 Port 정보를 활용하기 때문에 사용자 환경의 모니터링 대상 어플리케이션 서버가 동일 IP, 동일 Port를 사용하는 경우 WhaTap 서버에서 해당 서버 인스턴스를 구분 할 수 없게 됩니다.

    서버 인스턴스가 동적으로 확장되는 환경이 아니라면, 4.4. 서버명을 임의로 부여하여 관리하고 싶은 경우를 참조하여 어플리케이션 식별을 위한 명칭을 직접 지정하는 방식을 통해 우회 할 수 있습니다.

    WhaTap에서는 현재 모니터링 대상 어플리케이션이 internal address 또는 네트워크 가상화로 인해 중복된 IP를 사용할 경우, 4.4. 서버명을 임의로 부여하여 관리하고 싶은 경우를 참고하여 별도의 어플리케이션명 패턴을 활용합니다.

  • IBM JDK의 경우 “watcher” 방식으로 에이전트를 실행시킬 경우 트랜잭션 정보가 수집되지 않으므로 “javaagent” 방식만을 지원합니다.

    JVM Optimization을 저해하여 성능 저하를 유발할 가능성으로 인해 코드 주입을 제한하고 있습니다.

8. 호환성 목록

호환성 목록은 링크 문서를 통해 제시합니다.