3. WAS 에이전트 설치
이 장에서 하는 일
WAS 에이전트는 Java 애플리케이션 안에서 일어나는 일을 수집합니다. 사용자 요청 한 건이 어떤 경로로 처리됐는지, 어느 SQL 이 느렸는지, 외부 API 호출이 얼마나 걸렸는지, 힙 메모리와 GC 가 어떤 상태인지를 봅니다.
왜 필요한가 — 서버 자원은 멀쩡한데 응답이 느린 경우가 많습니다. 그 원인은 대개 특정 SQL, 외부 연동 지연, 커넥션 풀 고갈처럼 애플리케이션 안쪽에 있습니다. 시스템 에이전트로는 보이지 않는 영역입니다.
어떻게 붙나 — 애플리케이션 코드는 고치지 않습니다. WAS 기동 옵션에
-javaagent:khan-agent.jar 한 줄을 넣으면, JVM 이 클래스를 적재할 때 에이전트가 측정 코드를
자동으로 끼워 넣습니다. 설치의 본질은 이 옵션을 넣고 WAS 를 재기동하는 것입니다.
어디에 설치하나 — 모니터링할 WAS 인스턴스마다 한 벌씩. 같은 서버에 WAS 가 여러 개면 인스턴스마다 설정 파일을 따로 둡니다.
설치를 마치면 — 콘솔에 해당 인스턴스가 나타나고 트랜잭션이 실시간으로 흐릅니다.
설치 흐름
| 단계 | 하는 일 | 왜 |
|---|---|---|
| 1 | 설치 파일 내려받기 | 사용하는 Java 버전에 맞는 에이전트를 받습니다 |
| 2 | WAS 서버에 압축 풀기 | WAS 가 읽을 수 있는 자리에 둡니다 |
| 3 | 접속 정보와 인스턴스 이름 설정 | 어느 APM 서버로 보낼지, 콘솔에 어떤 이름으로 보일지 정합니다 |
| 4 | 기동 옵션에 -javaagent 추가 | 이 한 줄이 에이전트를 JVM 에 붙입니다 |
| 5 | WAS 재기동 | 옵션은 기동 시점에만 적용됩니다 |
4단계에서 옵션을 어느 파일에 넣는지는 WAS 제품마다 다릅니다. 제품별 위치와 예제는 4. WAS 종류별 에이전트 설정 방법에 있습니다.
WAS 에이전트 다운로드
콘솔에서 설치 파일을 내려받습니다. 설치형과 클라우드는 내려받는 화면만 다르고, 파일을 받은 뒤 절차는 같습니다.
설정 > 가이드 & 다운로드
OPENMARU APM 콘솔에 로그인하여 설치에 사용할 파일을 다운로드합니다.

다운로드 또는 마우스 오른쪽 "링크 주소 복사"를 이용하여 클립보드에 복사합니다.
Java버전이 1.5라면 APM WAS Agent for Java 1.5 Install File - Ver. 5.1.0파일을 다운로드 받습니다.
설치 대상이 원격 Linux 서버라면, 복사한 링크 주소를 그 서버에서 wget 으로 바로 받는 편이
빠릅니다. 아래는 명령 형태의 예시이며, 주소는 방금 복사한 값을 씁니다.
- WAS 에이전트 다운로드
$ wget "<복사한 링크 주소>"
[클라우드 전용] 에이전트 설치 안내 > WAS AGENT 탭
클라우드 APM 을 쓰는 경우 내려받는 자리가 다릅니다.

WAS AGENT 탭의 "Download WAS Agent" 로 내려받거나 Copy 버튼으로 링크를 클립보드에 복사합니다. 파일을 받은 뒤부터는 위와 같습니다.
WAS 에이전트 설치
- 에이전트 설치파일 압축해제
$ unzip khan-agent-5.1.0.zip
- khan-agent.jar 심볼릭 링크 파일 생성
khan-agent 버전 업그레이드 작업이 용이하도록 아래와 같이 Symbolic Link 파일을 생성합니다.
WAS의 에이전트 설정에서 khan-agent.jar 파일을 사용하도록 하며, khan-agent 버전 업그레이드시 심볼릭 링크를 제거하고 새로운 버전의 파일로 새로 생성하면 됩니다.
$ ln -s khan-agent-5.1.0.jar khan-agent.jar
WAS 에이전트 설정
WAS 서버 인스턴스 이름 설정 방법
khan-agent.conf 파일 내 설정
# WAS Instance's ID
# Can use RANDOM string or IP ADDRESS
# ex: instanceid-${RANDOM:4} ==> instanceid-qfPb
# ex: instanceid-${RANDOM:4}-s ==> instanceid-qfPb-s
# ex: instanceid-${IPADDR:3} ==> instanceid-23-10 (ip=192.168.23.10)
# ex: instanceid-${HOSTNAME:-:2} ==> instanceid-apm (hostname=test-apm)
# ex: instanceid-${HOSTNAME:-:2}-${IPADDR:3}-${RANDOM:4}-s ==> instanceid-apm-23.10-afcg-s (hostname=test-apm, ip=192.168.23.10)
${RANDOM:4}: 알파벳 대문자/소문자 조합 무작위 4글자 생성${IPADDR:3}: IP 주소 중 3번째 자리 요소 추가${IPADDR:-1}: IP 주소 중 뒤에서 부터 첫번째 자리 요소 추가${HOSTNAME:-:2}HOSTNAME 중 -로 구분하여 두번째 자리에 있는 문자열 추가
WAS 에이전트 설정 파일
에이전트의 동작은 압축을 푼 디렉터리의 khan-agent.conf 한 파일이 정합니다.
설치 파일에 기본값이 채워진 상태로 들어 있으므로, 처음에는 아래 네 항목만 고치면 됩니다.
1) 꼭 고쳐야 하는 것
application.name=MyGroup # 콘솔에 표시할 애플리케이션 그룹 이름
khan.host=192.168.0.77 # APM 서버 주소
khan.port=80 # APM 서버 포트
instance.id=khan11 # 이 WAS 인스턴스의 이름 (그룹 안에서 구분됩니다)
application.name— 같은 이름을 쓴 인스턴스끼리 한 그룹으로 묶여 보입니다. 서비스 단위로 정하십시오.khan.host·khan.port— 에이전트가 데이터를 보낼 곳입니다. 값이 틀리면 WAS 는 정상 기동되지만 콘솔에 아무것도 나타나지 않습니다.instance.id— 콘솔에서 이 인스턴스를 가리키는 이름입니다. 같은 그룹 안에서 겹치지 않게 정하십시오. 자동으로 만들려면 앞 절의 WAS 서버 인스턴스 이름 설정 방법을 참고하십시오.
여기까지만 고치고 WAS 를 재기동하면 모니터링이 시작됩니다. 아래는 필요할 때 조정하는 것들입니다.
2) 무엇을 얼마나 수집할지 — 트랜잭션 Trace
느린 요청의 처리 경로를 남길지, 어느 정도부터 남길지를 정합니다.
transaction.trace.enabled=true # 상세 추적 사용 여부
transaction.trace.threshold=500 # 이 시간(ms)을 넘은 요청만 상세히 남긴다
transaction.trace.max.line=2000 # 한 요청에 남길 최대 줄 수
threshold 를 낮출수록 더 많이 남지만 저장 용량과 부하가 함께 늘어납니다. 기본값
500ms 로 시작해 필요할 때 조정하십시오.
3) SQL 을 어떻게 남길지
sql.capture.enabled=true # SQL 수집 여부
transaction.trace.sql.parameterize=false # 바인드 값을 그대로 남길지 여부
transaction.trace.sql.parameter.max.size=40 # 남길 파라미터 값의 최대 길이
parameterize=false 는 실제 바인드 값을 그대로 남깁니다. 주민등록번호·연락처 같은 값이
쿼리 파라미터로 들어간다면 true 로 두어 값을 감추십시오.
4) 무엇을 빼고 볼지 — URL 필터링
정적 파일이나 헬스 체크 요청까지 트랜잭션으로 세면 통계가 왜곡됩니다. 기본값에 이미 흔한 확장자와 헬스 체크 패턴이 들어 있습니다.
transaction.exclude.url.suffix=.gif,.css,.js,.png,… # 확장자로 제외
transaction.exclude.url.patterns= # 정규식으로 제외
transaction.exclude.user.agent.patterns=^openmaru-health-check$
5) 서비스 만족도 기준 — APDEX
apdex.threshold=3.0 # 이 시간(초) 안에 끝나면 "만족"으로 셉니다
이 값의 4배를 넘으면 "불만" 으로 셉니다. 서비스 성격에 맞춰 정하십시오 — 조회 위주 화면은 낮게, 배치성 요청이 섞이면 높게 잡습니다.
설정을 바꾼 뒤
대부분의 항목은 WAS 를 재기동해야 적용됩니다. 재기동 없이 반영되는 항목은 다음 절의 표에서 "즉시 적용" 열로 확인할 수 있습니다.
전체 항목과 기본값은 WAS 에이전트 설정 상세에 주제별로 정리되어
있습니다. 같은 값을 JVM 옵션(-D)이나 환경변수로도 줄 수 있으며, 우선순위는
JVM 옵션 > 환경변수 > khan-agent.conf 입니다.
khan-agent.conf 설정파일의 각 항목에 대한 설명은 다음 표를 참고하십시오.
WAS 에이전트 설정 상세
(JVM 환경변수(-D), 시스템 환경변수(export or set) 사용 시 괄호항목 사용)
설정 우선순위 : JVM OPTS > OS ENV > khan-agent.conf