Auto-Instrumentation 방법

개요

OPENMARU APM WAS Agent Operator 를 활용하여 Auto-Instrumentation 방법을 소개한다.

동작 흐름

1. 사용자가 애플리케이션 deployment openmaru.io/was-agent: 'true' 레이블이 있는 POD 생성
2. Kubernetes API Server가 POD CREATE 이벤트 발생
3. MutatingWebhook 이 이벤트를 감지하고 /mutate 엔드포인트 호출
4. POD Spec 변경

• Volume 추가 : khan-data (emptyDir) - OPENMARU WAS Agent JAR 공유 저장소
• InitContainer 추가 : khan-agent-init - OPENMARU WAS Agent ZIP 압축 해제
• 메인 컨테이너 수정
  • VolumeMount : /khan-agent 경로 마운트
  • 환경변수 주입
    • JAVA_TOOL_OPTIONS="-javaagent:/khan-agent/khan-agent-5.1.0.jar"
    • Java 버전별 --add-opens 옵션 (Java 11, 17, 21)
    • APM 서버 연결 정보 (OMAPM_HOST, OMAPM_PORT)
    • 애플리케이션 메타 데이터 (OMAPM_APPLICATION_NAME, OMAPM_INSTANCE_ID)

5. InitContainer 실행 (khan-agent-init)

• OPENMARU WAS Agent ZIP 압축 해제

6. 메인 컨테이너 실행

• JAVA_TOOL_OPTIONS 환경변수를 통해 OPENMARU WAS Agent JAR 자동 로드
• 애플리케이션 실행
• APM 서버로 데이터 전송 (OPENMARU WAS Agent)

OPENMARU WAS Agent Operator 설치

values.yaml

...
openmaruApmWasAgentOperator:
  enabled: true    # WasAgentOpertor 설치 시 반드시 enabled 되어 있어야 함
  ...
  imageAgent:
    repository: registry.openmaru.io/images/openmaru-operator-apm-agent     # 필요 시 변경
    tag: latest
    pullPolicy: IfNotPresent
  ...
    # OMAPM_HOST, OMAPM_PORT는 APM 서버 기본 정보 설정 (애플리케이션 Deployment에 설정을 우선함)
    - name: OMAPM_HOST
      value: "openmaru-apm-server.openmaru-apm.svc.cluster.local"
    - name: OMAPM_PORT
      value: "8080"
  ...

# openmaruApmWasAgentOperator 이외 enabled: false
...
openmaruApmHpaOperator:
  enabled: false
...
openmaruApmServer:
  enabled: false

helm install openmaru-apm ./openmaru-apm -f values.yaml--namespace openmaru-operator --create-namespace --insecure-skip-tls-verify

설정 방법

Deployment 설정에서 OPENMARU WAS Agent 옵션을 활성화한다.
옵션을 활성화하면 POD가 생성되는 시점에 -javaagent 설정이 자동으로 추가된다.

설정값

🟥 필수 openmaru.io/was-agent OPENMARU WAS Agent 설정 여부
🟦 선택 openmaru.io/container-names 컨테이너가 여러개일 경우 특정 하나만 지정하는 방법
🟦 선택 openmaru.io/was-agent-version 에이전트 버전을 선택 하는 방법
🟦 선택 openmaru.io/was-agent-image-pull-policy IfNotPresent(기본값), Always
🟦 선택 openmaru.io/java-version 11(기본값), 1.8, 11, 21

kind: Deployment
apiVersion: apps/v1
metadata:
  name: testapp
  namespace: openmaru
...
spec:
  replicas: 1
  selector:
    matchLabels:
      deployment: testapp
  template:
    metadata:
      creationTimestamp: null
      labels:
        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

자동으로 추가되는 값

warning

자동으로 추가되는 환경변수(ENV)는 Deployment 설정값을 우선함단, JAVA_TOOL_OPTIONS, JAVA_OPTS 값은 뒤에 추가됨

      env:
        - name: OMAPM_HOST
          value: 10.20.2.9
        - name: OMAPM_PORT
          value: '80'
        - name: JAVA_TOOL_OPTIONS
          value: '-javaagent:/khan-agent/khan-agent-5.1.0.jar'
        - name: JAVA_OPTS
          value: '-Dtest1=1 -noverify --add-opens=java.base/java.io=ALL-UNNAMED....'
        - 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'