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_* 접속 환경변수

Init 컨테이너에는 allowPrivilegeEscalation: false · capabilities.drop: [ALL] · runAsNonRoot: true · runAsUser: 1000 · seccompProfile: RuntimeDefault 가 항상 함께 들어갑니다. Pod Security 의 restricted 프로파일을 지키기 위해서입니다. 파드에 runAsUser 가 이미 지정돼 있으면 그 값을 씁니다 — 압축을 푼 파일을 앱이 읽어야 하므로 같은 사용자여야 합니다.

같은 파드에 계측을 다시 적용해도 Init 컨테이너와 -javaagent 는 한 번만 들어갑니다.

2. 라벨과 어노테이션 옵션

계측 대상을 고르는 스위치는 라벨 하나뿐이고, 세부 설정은 모두 어노테이션입니다.

키	위치	필수	기본값	설명
`openmaru.io/was-agent`	라벨	필수	—	`'true'` 일 때만 계측. 그 외 값이거나 미설정이면 아무 것도 하지 않음
`openmaru.io/container-names`	어노테이션	선택	(전체)	계측할 컨테이너 이름. 둘 이상은 쉼표로 구분
`openmaru.io/was-agent-version`	어노테이션	선택	설치 시 지정한 값	주입할 에이전트(이미지 태그) 버전
`openmaru.io/was-agent-image-pull-policy`	어노테이션	선택	`IfNotPresent`	에이전트 이미지 풀 정책. `Always` 가능

🔴 위 표의 위치를 지킵니다. was-agent 를 어노테이션에 적으면 계측이 되지 않고, 나머지 셋을 라벨에 적으면 값에 따라 파드 생성이 거부될 수 있습니다(라벨 값은 영숫자와 -·_·. 만 받습니다).

기존 배포는 그대로 동작합니다. 이 셋을 라벨로 적어 둔 워크로드도 계속 읽습니다. 같은 키가 라벨과 어노테이션에 둘 다 있으면 어노테이션을 씁니다.

전체 예시

spec:
  replicas: 1
  selector:
    matchLabels:
      deployment: testapp
  template:
    metadata:
      labels:
        deployment: testapp
        openmaru.io/was-agent: 'true'                     # 필수, 라벨
      annotations:
        openmaru.io/container-names: 'testapp'            # 생략 가능
        openmaru.io/was-agent-version: '5.1.0-11.1'       # 생략 가능
        openmaru.io/was-agent-image-pull-policy: IfNotPresent
    spec:
      containers:
        - name: testapp
          image: my-registry/testapp:latest

컨테이너를 둘 이상 고를 때는 쉼표로 구분합니다.

      annotations:
        openmaru.io/container-names: 'app,sidecar'

Init 컨테이너와 khan-data 볼륨은 어느 컨테이너를 골랐는지와 관계없이 파드에 항상 붙습니다. container-names 가 정하는 것은 -javaagent 와 볼륨 마운트를 받을 앱 컨테이너입니다.

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

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

환경변수	예시 값	의미
`OMAPM_HOST`	`openmaru-apm-server.openmaru-apm.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)

CATALINA_OPTS_APPEND · JAVA_OPTS_APPEND · JAVA_OPTS 는 건드리지 않습니다. 앱이 정한 값을 그대로 둡니다.

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

🔴 OMAPM_APPLICATION_NAME 은 APM 의 애플리케이션 그룹 이름이 됩니다. 기본값에는 ReplicaSet 해시가 들어가 재배포할 때마다 바뀝니다. 오토스케일링에 쓴다면 값을 직접 지정해 고정하십시오 — 자세한 것은 302 오토스케일링 을 보십시오.

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 가 우선합니다(덮어쓰지 않음)

개요​

1. 가장 빠른 사용법​

2. 라벨과 어노테이션 옵션​

전체 예시​

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

4. 적용 확인​

5. 동작 원리​

6. 잘 안 될 때​

개요