3.1. 자동 계측 (APM Agent)

개요

라벨 하나만 붙이면 워크로드에 OPENMARU WAS 에이전트가 자동으로 주입 됩니다. 이미지 수정이 필요 없습니다.

1. 가장 빠른 사용법

모니터링할 Deployment 의 파드 템플릿 라벨 에 다음을 추가하고 재배포합니다.

spec:
  template:
    metadata:
      labels:
        openmaru.io/was-agent: 'true'    # 이 한 줄이면 자동 계측 적용

라벨은 반드시 spec.template.metadata.labels(파드 템플릿)에 넣습니다. Deployment 최상위 metadata.labels 가 아닙니다.

재배포 후 새로 뜨는 파드에는 다음이 자동으로 들어갑니다.

• khan-data 공유 볼륨(emptyDir)
• khan-agent-init Init 컨테이너 (에이전트 파일 압축 해제)
• 앱 컨테이너에 -javaagent 와 OMAPM_* 접속 환경변수

2. 라벨 옵션

라벨	필수	기본값	설명
openmaru.io/was-agent	필수	—	'true' 일 때만 계측. 그 외 값이거나 미설정이면 아무 것도 하지 않음
openmaru.io/container-names	선택	(전체)	컨테이너가 여러 개일 때 계측할 하나의 컨테이너 이름 지정
openmaru.io/was-agent-version	선택	5.1.0	주입할 에이전트(이미지 태그) 버전
openmaru.io/was-agent-image-pull-policy	선택	IfNotPresent	에이전트 이미지 풀 정책. Always 가능
openmaru.io/java-version	선택	11	앱의 Java 버전. 1.7/1.8/11/21 등. Java 9 이상이면 모듈 접근용 JAVA_OPTS(add-opens)가 함께 주입됨

전체 예시는 다음과 같습니다.

spec:
  replicas: 1
  selector:
    matchLabels:
      deployment: testapp
  template:
    metadata:
      labels:
        deployment: testapp
        openmaru.io/was-agent: 'true'
        openmaru.io/container-names: 'testapp'            # 생략 가능
        openmaru.io/was-agent-version: '5.1.0-10.3'       # 생략 가능 (기본 5.1.0)
        openmaru.io/was-agent-image-pull-policy: IfNotPresent
        openmaru.io/java-version: '11'                    # 생략 가능 (기본 11)
    spec:
      containers:
        - name: testapp
          image: my-registry/testapp:latest

3. 자동으로 추가되는 환경변수

계측이 적용되면 앱 컨테이너에 아래 환경변수가 주입됩니다. 이미 Deployment 에 같은 이름의 환경변수가 있으면 덮어쓰지 않습니다(사용자 값 우선). 단 JAVA_TOOL_OPTIONS 는 기존 값이 있으면 뒤에 이어 붙입니다(Append).

환경변수	예시 값	의미
OMAPM_HOST	openmaru-apm.openmaru-observ.svc.cluster.local	APM 서버 호스트 (미지정 시 Operator 기본값 OMAPM_HOST)
OMAPM_PORT	8080	APM 서버 포트
OMAPM_APPLICATION_NAME	testapp-${HOSTNAME:-:2}	APM 에 표시될 애플리케이션 이름
OMAPM_INSTANCE_ID	testapp-${HOSTNAME:-:2}-${HOSTNAME:-:3}	인스턴스 식별자
OMAPM_TRANSACTION_TRACE_THRESHOLD	500	트랜잭션 트레이스 임계(ms)
JAVA_TOOL_OPTIONS	-javaagent:/khan-agent/khan-agent-5.1.0.jar	에이전트 로딩 (기존 값 뒤에 Append)
JAVA_OPTS	-noverify --add-opens=...	Java 9 이상 모듈 접근 옵션 (java-version 이 8 초과일 때)

APM 서버를 개별 지정하려면 Deployment 의 컨테이너 env 에 OMAPM_HOST / OMAPM_PORT 를 직접 넣으십시오. Operator 기본값보다 우선합니다.

4. 적용 확인

새 파드에 Init 컨테이너와 javaagent 가 들어갔는지 확인합니다.

# Init 컨테이너(khan-agent-init) 와 볼륨(khan-data) 확인
kubectl describe pod <pod-name> | grep -E "khan-agent-init|khan-data"

# 주입된 환경변수 확인
kubectl set env pod/<pod-name> --list | grep -E "OMAPM_|JAVA_TOOL_OPTIONS"

이후 OPENMARU APM 콘솔(WAS 대시보드)에서 해당 애플리케이션/인스턴스가 보이면 정상입니다.

5. 동작 원리

6. 잘 안 될 때

증상	점검
파드에 에이전트가 안 붙음	라벨이 spec.template.metadata.labels 에 있는지, 값이 정확히 'true'(문자열)인지
Init 컨테이너 이미지 Pull 실패	IMAGE_REGISTRY/IMAGE_NAMESPACE(설치 설정)와 was-agent-version 으로 만든 이미지 경로가 실제 존재하는지
여러 컨테이너 중 엉뚱한 곳에 주입	openmaru.io/container-names 로 대상 컨테이너 지정
APM 콘솔에 안 보임	OMAPM_HOST/OMAPM_PORT 가 실제 APM 서버를 가리키는지(네트워크 도달 포함)
기존에 설정한 env 가 안 먹음	정상 동작입니다. 사용자가 넣은 동일 이름 env 가 우선합니다(덮어쓰지 않음)

---