5. 컨테이너·쿠버네티스에 설치
앞의 3장은 서버에 직접 설치한 WAS 에 에이전트를 붙이는 방법입니다. 이 장은 WAS 가 컨테이너로 도는 경우를 다룬다.
어느 방법을 고를 것인가
| 방법 | 무엇을 하나 | 언제 쓰나 |
|---|---|---|
| 이미지에 굽기 | 에이전트를 넣은 base 이미지를 만들어 두고 애플리케이션이 그것을 FROM 으로 쓴다 | 이미지 빌드를 직접 관리할 때 |
| S2I | 소스와 함께 에이전트 파일을 넣어 두면 빌드가 알아서 담는다 | 개발자가 소스만 올려 빌드할 때 |
| 자동 주입 (Operator) | 워크로드에 라벨만 붙이면 에이전트가 자동으로 들어갑니다. 이미지를 고치지 않는다 | 쿠버네티스·OpenShift 를 쓸 때 권장 |
자동 주입은 이 가이드가 아니라 OPENMARU APM Operator 사용자 가이드에서 다룬다. 이미지를 손대지 않아도 되고 업그레이드도 Operator 가 맡으므로, 쿠버네티스 환경이면 그쪽을 먼저 검토합니다. 아래 두 방법은 Operator 를 쓸 수 없거나 이미지를 직접 관리해야 하는 경우를 위한 것입니다.
1. 이미지에 에이전트 굽기
컨테이너로 운영되는 WAS 인스턴스를 모니터링하려면 에이전트를 담은 이미지를 빌드해 레지스트리에 등록해야 합니다. 다음에서 빌드하고 배포하는 절차를 설명합니다.
에이전트 파일 구성
레지스트리에 접속할 수 있고 Podman 이 설치된 리눅스 머신에서 아래 파일의 압축을 푼다.
$ wget https://cloud.openmaru.io/api/v1/projects/{SAAS_PROJECT_ID}/download/was-agent.zip
$ unzip khan-agent-5.1.0.zip
Dockerfile 구성
이미지를 만들 때 khan-agent-5.1.0.jar, khan-agent.conf, user-interceptor.conf 를 넣는다.
FROM registry.redhat.io/jboss-eap-7/eap74-openjdk8-openshift-rhel7
USER root
ENV JAVA_OPTS="-javaagent:/opt/eap/khan-apm/khan-agent-5.1.0.jar"
ENV JAVA_OPTS="-Dkhan.config.file=/opt/eap/khan-apm/khan-agent.conf"
ADD ./khan-agent-5.1.0.zip /opt/eap/
RUN unzip -q /opt/eap/khan-agent-5.1.0.zip -d /opt/eap/khan-apm && \
chmod -R 777 /opt/eap/khan-apm
ADD khan-agent.conf /opt/eap/khan-apm
ADD user-interceptor.conf /opt/eap/khan-apm
USER jboss
khan-agent.conf 의 설정 항목은 아래 4. Pod 에서 쓸 수 있는 환경변수를 참고합니다.
build.sh 구성
이미지를 빌드해 레지스트리에 push 하는 스크립트다. 레지스트리를 외부 서버에 두는지
컨테이너로 띄우는지에 따라 주소가 다르므로 REGISTRY_URL 을 환경에 맞게 바꾼다.
$ vi build.sh
#/bin/bash
# -------------------------------------------------------------
# OPENMARU APM https://www.openmaru.io/
# for OpenShift Container JBoss EAP 7.0 Image Monitoring
#
# contact : service@opennaru.com
# Copyright (c) 2026. OPENMARU, Inc. All Rights Reserved.
# -------------------------------------------------------------
#/bin/bash
export REGISTRY_URL=default-route-openshift-image-registry.apps.ocp.opennaru.com
TAG_NAME=eap74-test
VERSION=5.1.0-7.1.1
#
# registry login examples
#
#oc login
#docker login -u devadmin -p $(oc whoami -t) $REGISTRY_URL
#podman login -u $(oc whoami) -p $(oc whoami -t) $REGISTRY_URL
#sudo docker login -p <TOKEN_IN_OPENSHIFT_REGISTRY> -e unused -u unused $REGISTRY_URL
#oc login --token <TOKEN_IN_OPENSHIFT_REGISTRY> ocp-master1.ocp-dev.opennaru.com
podman build --rm --tag=$TAG_NAME .
podman tag $TAG_NAME $REGISTRY_URL/openshift/$TAG_NAME:$VERSION
#$podman push $REGISTRY_URL/openshift/$TAG_NAME:$VERSION
podman push --tls-verify=false $REGISTRY_URL/openshift/$TAG_NAME:$VERSION
이미지의 네임스페이스와 이미지 스트림 이름이 openshift/$TAG_NAME:$VERSION 으로
지정되어 있으니 원하는 이름으로 바꾸면 됩니다.
push 하려면 레지스트리에 로그인되어 있어야 합니다. 빌드 전에 oc login 이나
podman login 으로 미리 로그인합니다.
$ export REGISTRY_URL=default-route-openshift-image-registry.apps.ocp.opennaru.com
$ oc login
혹은 $ podman login -u devadmin -p $(oc whoami -t) $REGISTRY_URL
빌드 및 레지스트리 push
./build.sh 를 실행해 이미지를 빌드하고 push 합니다.
$ ./build.sh
빌드가 STEP 1 부터 차례로 지나간 뒤 push 가 이어집니다. 다음 세 가지만 확인하면 됩니다.
| 확인할 것 | 로그에 나오는 내용 |
|---|---|
| 에이전트가 이미지에 들어갔나 | ADD ./khan-agent-<버전>.zip · ADD khan-agent.conf 단계가 오류 없이 지나감 |
| 기동 옵션이 박혔나 | ENV JAVA_OPTS="-javaagent:…" · ENV JAVA_OPTS="-Dkhan.config.file=…" |
| 레지스트리에 올라갔나 | 마지막 Writing manifest to image destination · Storing signatures |
*/} Using cache … 는 이전 빌드 결과를 그대로 쓴다는 뜻으로 정상입니다. 에이전트 파일을
바꿨는데도 캐시를 쓴다면 podman build --no-cache 로 다시 빌드하십시오.
실패하면 어느 STEP 에서 멈췄는지 먼저 보십시오. ADD 단계에서 멈추면 빌드 디렉터리에
파일이 없는 것이고, push 단계에서 멈추면 레지스트리 로그인이나 주소 문제입니다.
이미지 검증
배포한 뒤 OPENMARU APM 에서 접속되어 동작하는지 확인합니다.
- 에이전트 접속 확인
- JVM 모니터링 확인
/session/index.jsp호출 시 T-Map 확인
동작하지 않으면 프로세스의 JAVA_OPTS 순서를 확인합니다. 아래 순서여야 합니다.
ps -ef | grep jboss
...중략...
-javaagent:/opt/eap/khan-apm/khan-agent/khan-agent-5.1.0.jar
...중략...
-Xbootclasspath/p:...중략...
...중략...
-Djava.util.logging.manager=org.jboss.logmanager.LogManager
2. 애플리케이션 이미지에서 쓰기
빌드해 둔 이미지를 애플리케이션 Dockerfile 의 FROM 절에 넣는다.
FROM registry.access.redhat.com/jboss-eap-6/eap64-OpenShift
… 중략 …
⇒
FROM docker-registry-default.ocp-dev.opennaru.com/jboss-eap-6/eap64-OpenShift
… 중략 …
이렇게 빌드한 이미지로 애플리케이션을 배포하면 콘솔에 인스턴스가 나타나고 트랜잭션이
흐르기 시작합니다. WAS > 대시보드 에서 인스턴스가 보이면 설치가 끝난 것입니다.
화면을 읽는 법과 트러블슈팅 기능(스레드 덤프·힙 분석)은 사용자 매뉴얼에서 다룹니다.
3. S2I 로 빌드하기
S2I(Source-to-Image)는 소스 코드만으로 실행 가능한 컨테이너 이미지를 자동 생성하는 오픈소스 빌드 방식으로, 주로 OPENMARU COP, Red Hat OpenShift 에서 사용됩니다. 기본적으로 소스 기반 방식을 사용하지만 Dockerfile 방식과 Binary 방식도 지원합니다. 개발자가 빌드 과정을 직접 제어할 수 있다는 점이 장점입니다.
내려받은 khan-agent-5.1.0.zip 파일을 아래 data 디렉토리에 두면 POD 의
/deployments/data 디렉토리에 배포됩니다.
warning
S2I(Source-to-Image) 이미지에 따라
/deployments/data 경로는 변경될 수 있음
프로젝트/
├── data/
│ ├── khan-agent-5.1.0.jar # 에이전트 JAR 파일
│ ├── khan-agent.conf # 에이전트 설정 파일
│ └── user-interceptor.conf # 에이전트 설정 파일(사용자 인터셉터)
└── src/
└── ... # 사용자 애플리케이션 소스 코드
팁
S2I(Source-to-Image)를 사용하지 않아도
Dockerfile 로 빌드한다면 Agent 파일을 ADD 로 포함해 사용할 수 있습니다.
설정
정보
WAS 종류별 에이전트 설정 방법 을 참고하여 설정할 수 있습니다.
...
spec:
...
containers:
- resources: {}
name: testapp
env:
- name: OMAPM_HOST
value: 10.20.2.9
- name: OMAPM_PORT
value: '80'
- name: JAVA_TOOL_OPTIONS
value: '-javaagent:/data/khan-agent-5.1.0.jar'
- name: JAVA_OPTS
value: '-Dtest1=1 --add-opens=java.base/...'## 생략
- name: OMAPM_APPLICATION_NAME
value: 'testapp-${HOSTNAME:-:2}'
- name: OMAPM_INSTANCE_ID
value: 'testapp-${HOSTNAME:-:2}-${HOSTNAME:-:3}'
- name: OMAPM_TRANSACTION_TRACE_THRESHOLD
value: '500'
4. Pod 에서 쓸 수 있는 환경변수
Deployment 의 환경변수(Environment Variable)로 지정할 수 있는 OPENMARU APM
khan-agent.conf 설정 항목입니다.
| 설정항목 | 설명 | 기본값 |
|---|---|---|
| OMAPM_APPLICATION_NAME | 애플리케이션 그룹명을 지정합니다. 단, 빌드번호도 나오지 않는다. | 예) hostname 이 jboss-eap-egov-65-zs95r 와 같을 때 eap-${HOSTNAME:-:5} => eap-65 |
| OMAPM_HOST | ||
| OMAPM_PORT | 443 | |
| OMAPM_TLS | true | |
| OMAPM_AGENT_IP | ||
| OMAPM_USER_KEY | NIL | |
| OMAPM_INSTANCE_ID | 인스턴스 이름을 지정합니다. 지정하면 [OMAPM_INSTANCE_ID설정값]-빌드번호-랜덤값 와 같이 표시합니다. 지정하지 않으면 Deployment 이름이 사용됩니다. | 예) hostname 이 jboss-eap-egov-65-zs95r 와 같을 때 eap-${HOSTNAME:-:5}-${HOSTNAME:-:6} => eap-65-zs95r case1: instanceid-${RANDOM:4} ==> instanceid-qfPb case1: instanceid-${RANDOM:4}-s ==> instanceid-qfPb-s case1: instanceid-${IPADDR:3} ==> instanceid-23-10 (ip=192.168.23.10) case1: instanceid-${HOSTNAME:-:2} ==> instanceid-apm (hostname=test-apm) case1: instanceid-${HOSTNAME:-:2}-${IPADDR:3}-${RANDOM:4}-s ==> instanceid-apm-23.10-afcg-s (hostname=test-apm, ip=192.168.23.10) |
| OMAPM_AGENT_TYPE | WAS | |
| OMAPM_AGENT_COMPRESS_TYPE | 에이전트의 압축 알고리즘 타입을 지정합니다. | lzw (default=snappy) |
| OMAPM_APDEX_THRESHOLD | APDEX에서 사용자가 만족하는 응답시간을 지정합니다.(기본값 3초) | 3.0 |
| OMAPM_TRANSACTION_TRACE_ENABLED | 트랜잭션 Trace를 사용할지 여부를 지정합니다. | true |
| OMAPM_TRANSACTION_TRACE_THRESHOLD | 트랜잭션 Trace를 수집할 응답시간을 지정한다(ms단위) 기본값 : 500 ms | 500 |
| OMAPM_TRANSACTION_TRACE_THRESHOLD _UNDER_DETAIL_ENABLED | false | |
| OMAPM_SQL_CAPTURE_ENABLED | 트랜잭션 Trace시 SQL 문장을 수집할지 여부를 지정합니다. | true |
| OMAPM_TRANSACTION_TRACE_SQL_PARAMETERIZE | false | |
| OMAPM_TRANSACTION_SAMPLING_INTERVAL | 동일한 URL에 대한 트랜잭션 수집 Interval을 지정합니다. 10을 지정하면 동일한 URL에 대해 10개중 1개만 Trace를 보관합니다. | 1 |
| OMAPM_TRANSACTION_TRACE_SQL_STACKTRACE _THRESHOLD | SQL 쿼리의 stacktrace 임계값을 ms로 설정합니다. | 30000 |
| OMAPM_TRANSACTION_TRACE_HEADER_ENABLED | 요청한 값의 HEADER 추적 활성화 여부를 지정합니다. | true |
| OMAPM_TRANSACTION_TRACE_HEADER_KEYS | 요청한 HEADER의 키 값 | |
| OMAPM_TRANSACTION_TRACE_COOKIE_ENABLED | 요청한 쿠키 추적 활성화 여부를 지정합니다. | false |
| OMAPM_TRANSACTION_TRACE_COOKIE_KEYS | 요청한 쿠키의 키 값 | JSESSIONID |
| OMAPM_TRANSACTION_TRACE_PARAMETER_KEYS | URL의 매개변수 추가 | |
| OMAPM_DATABASE_FETCH_WARNINGS | SQL ResultSet Fetch시 컴마로 구분한 지정된 갯수를 Fetch하면 경고를 출력합니다. | 10000,20000,30000 |
| OMAPM_DATABASE_CONN_LEAK_WARNING | DB의 커넥션 부족 경고 | false |
| OMAPM_DATABASE_POOL_STAT_ENABLED | 전체 DB pool 통계 모니터링 활성화 여부 지정 | false |
| OMAPM_DATABASE_POOL_STAT_INCLUDE_PATTERNS | datasource 이름을 쉼표로 구분하여 포함할 패턴 목록 지정 | |
| OMAPM_DATABASE_POOL_STAT_EXCLUDE_PATTERNS | datasource 이름을 쉼표로 구분하여 제외할 패턴 목록 지정 | |
| OMAPM_INCLUDE_PACKAGES | ||
| OMAPM_TRANSACTION_EXCLUDE_URL_PATTERNS | 모니터링에서 제외할 URL(정규식) 예) /test/test.**,\**/abc/test.* | \* |
| OMAPM_TRANSACTION_EXCLUDE_URL_SUFFIX | .gif,.swf,.css,.hwp,.xls,.xlsx,.eot,.pptx,.ppt,.asf,.pdf,.txt,.flv,.mp3,.mp4,.doc,.html,.wmv,.jpg,.zip,.wav,.png,.ttf,.mov,.ico,.js,.woff,.xml,.htc,.NewProxyConnection,.DelegatingConnection,.SqlSessionTemplate,.CUBRIDConnection,.PoolableConnection,.WrappedConnection,/bea_wls_deployment_internal/DeploymentService,.GIF,.SWF,.CSS,.HWP,.XLS,.XLSX,.EOT,.PPTX,.PPT,.ASF,.PDF,.TXT,.FLV,.MP3,.MP4,.DOC,.HTML,.WMV,.JPG,.ZIP,.WAV,.PNG,.TTF,.MOV,.ICO,.JS,.WOFF,.XML,.HTC | |
| OMAPM_TRANSACTION_EXCLUDE_URL_SUFFIX_EXCLUDE | true | |
| OMAPM_TRANSACTION_EXCLUDE_USER_AGENT _PATTERNS | ^openmaru-health-check$ | |
| OMAPM_TRANSACTION_ERRORPAGE_URL_PATTERNS | /session/force500.\*,/test/test500.* | |
| OMAPM_TRANSACTION_WITH_EXCEPTION_VIEW _ENABLED | true | |
| OMAPM_TRANSACTION_WITH_EXTERNAL_HTTP _ERROR_VIEW_ENABLED | true | |
| OMAPM_TRANSACTION_WITH_EXTERNAL_HTTP _ERROR_CODES | ||
| OMAPM_TRAFFIC_CONTROL_ENABLED | true | |
| OMAPM_TRAFFIC_CONTROL_PATTERN_1 | 지정한 패턴의 동시에 최대로 허용할 요청 값 지정 | /test/slow., 100 |
| OMAPM_TRAFFIC_CONTROL_PATTERN_2 | 지정한 패턴의 동시에 최대로 허용할 요청 값 지정 | /test/test., 100 |
| OMAPM_TRAFFIC_CONTROL.PATTERN_3 | 지정한 패턴의 동시에 최대로 허용할 요청 값 지정 | /test/TestServlet., 100 |
| OMAPM_UBT_CHECK_ENABLED | false | |
| OMAPM_UBT_CHECK_TYPE | ip | |
| OMAPM_UBT_CHECK_USER_COUNT | 100 | |
| OMAPM_UBT_CHECK_TIME_INTERVAL | 1 | |
| OMAPM_UBT_CHECK_ALERT_DUP_PREVENT | 30 | |
| OMAPM_USER_TRACKING_MODE | 사용자 추적 모드 지정 0 : 클라이언트 IP 1 : JSESSIONID 쿠키 2 : KHANUSER Cookie - default | 2 |
| OMAPM_USER_THINKTIME_MINUTES | 5 | |
| OMAPM_ENABLE_FILTER_INTERCEPTOR | false | |
| OMAPM_ENABLE_IBATIS_INTERCEPTOR | false | |
| OMAPM_ENABLE_MYBATIS_INTERCEPTOR | false | |
| OMAPM_ENABLE_HTTP_INTERCEPTOR | false | |
| OMAPM_ENABLE_SPRINGBATCH_INTERCEPTOR | false | |
| OMAPM_ENABLE_LOGGING_INTERCEPTOR | false | |
| OMAPM_TRACE_LOGGING_LEVELS | WARN,ERROR,FATAL | |
| OMAPM_PUSH_TRANSACTION_NO_DELAY | true | |
| OMAPM_ACTIVEUSER_COUNTFIRSTREQUEST | false | |
| OMAPM_USER_CHARSET_ENCODING | APM의 인코딩 값 지정 | UTF-8 |
| OMAPM_USER_INTERCEPTOR_FILE | 사용자의 interceptor 환경변수를 설정한 파일명 | user-interceptor.conf |
| OMAPM_LOG_DIR | APM 로그 경로 설정 | /svc/test/khan-agent/log |
| OMAPM_LOG_FILE | 로그 파일 명 지정 | khan-agent-${INSTANCEID}.log |
| OMAPM_LOG_LEVEL | 로그 레벨 지정 | INFO |
| OMAPM_LOG_BACKUP_INDEX | 유지할 로그의 백업 파일 수 설정 | 3 |
| OMAPM_LOG_ROTATE_SIZE | 전환할 로그 파일의 크기 지정 | 10240000 |
| OMAPM_SESSION_MANAGER_ENABLED | 세션 매니저 활성화 여부 | true |
| OMAPM_ACTIVE_SESSION_COUNT_ENABLED | 세션 수 카운팅 여부 | true |
| OMAPM_AUDIT_LOG_ENABLED | 감사 로그 파일 활성화 여부 | true |
| OMAPM_AUDIT_LOG_USERIDKEY | USER_ID | |
| OMAPM_AUDIT_LOG_DIR | 감사 로그 경로 설정 | |
| OMAPM_AUDIT_LOG_FILENAME | 감사 로그 파일 명 지정 | audit-{date: yyyy-MM-dd}.log |
| OMAPM_AUDIT_LOG_POLICIES | daily: 00:00 | |
| OMAPM_AUDIT_LOG_BACKUPS | 유지할 감사 로그의 백업 파일 수 설정 | 3 |