A.1. 레퍼런스 및 문제 해결
개요
본 장은 자동 계측 라벨·어노테이션과 주입 환경변수, HPA 지표의 전체 목록과 자주 묻는 질문, 점검 명령을 모아 둔 참고 자료입니다.
1. 라벨·어노테이션 레퍼런스 (자동 계측)
계측 대상을 고르는 라벨은 하나뿐이고, 세부 설정은 모두 어노테이션입니다.
라벨 — spec.template.metadata.labels
| 라벨 | 필수 | 기본값 | 허용 값 / 예시 |
|---|---|---|---|
openmaru.io/was-agent | 필수 | — | 'true' |
어노테이션 — spec.template.metadata.annotations
| 어노테이션 | 필수 | 기본값 | 허용 값 / 예시 |
|---|---|---|---|
openmaru.io/container-names | 선택 | 전체 | 쉼표로 구분한 컨테이너 이름 (예: testapp · app,sidecar) |
openmaru.io/was-agent-version | 선택 | 설치 시 지정한 값 | 이미지 태그 (예: 5.1.0-11.1) |
openmaru.io/was-agent-image-pull-policy | 선택 | IfNotPresent | IfNotPresent / Always |
이 셋은 라벨로 적어 둔 기존 배포도 계속 읽습니다. 같은 키가 라벨과 어노테이션에 둘 다 있으면 어노테이션을 씁니다.
2. 주입 환경변수 레퍼런스
이미 같은 이름이 있으면 덮어쓰지 않습니다. JAVA_TOOL_OPTIONS 만 Append 입니다.
| 환경변수 | 기본 동작 |
|---|---|
OMAPM_HOST | 미지정 시 Operator 의 OMAPM_HOST |
OMAPM_PORT | 미지정 시 Operator 의 OMAPM_PORT |
OMAPM_APPLICATION_NAME | <container>-${HOSTNAME:-:2} |
OMAPM_INSTANCE_ID | <container>-${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 는 건드리지 않습니다.
앱이 정한 값을 그대로 둡니다.
OMAPM_APPLICATION_NAME 의 기본값에는 ReplicaSet 해시가 들어가 재배포 때마다 바뀝니다.
오토스케일링에 쓴다면 값을 직접 지정해 고정하십시오
(302 3.1절).
3. Operator 설치 환경변수 레퍼런스
| 키 | 컴포넌트 | 의미 |
|---|---|---|
IMAGE_REGISTRY | Agent | 주입할 khan-agent 이미지 레지스트리 |
IMAGE_NAMESPACE | Agent | 레지스트리 내 네임스페이스(앞에 / 포함) |
OMAPM_HOST / OMAPM_PORT | Agent | 계측 대상 기본 APM 서버 |
envHpa 의 각 name/value | HPA | apmAlias → APM 서버 URL 매핑 |
DEFAULT_AGENT_VERSION | Agent | 주입할 에이전트 이미지 태그의 기본값 |
<apmAlias>_ACCESS_KEY | HPA | 해당 APM 서버 API 액세스 키. 별칭마다 짝지어 두십시오 — 없으면 APM 이 HTTP 403 을 줍니다 |
TLS_CERT_FILE / TLS_KEY_FILE | 공통 | 서버 인증서·개인키 경로. 차트가 시크릿을 마운트하고 채웁니다 |
4. HPA 지표 레퍼런스
selector 라벨은 모두 apmAlias 와 groupName 이고, 질의 대상은
{APM}/monitoring/api/metrics/apps/info/{groupName} 입니다.
| 지표 | 무엇 | 범위 | target.type |
|---|---|---|---|
tps | 초당 처리 건수 | — | AverageValue |
activeUser | 접속 사용자 수 | — | AverageValue |
loginUser | 로그인 사용자 수 | — | AverageValue |
avgRT | 평균 응답시간 (밀리초) | — | Value |
errorRate | 오류율 | 0~100 | Value |
apdexDeficit | 100 - apdex. 클수록 응답이 나쁩니다 | 0~100 | Value |
apdex | 만족도. 클수록 좋습니다 | 0~100 | HPA 에 쓸 수 없음 — 조회 전용 |
AverageValue 는 받은 값을 파드 수로 나눕니다. 합계인 지표에만 쓰십시오.
소수는 밀리 단위로 실려 옵니다 (27.667 → 27667m).
5. 자주 묻는 질문 (FAQ)
Q. 애플리케이션 이미지를 바꿔야 하나요?
아니요. 라벨만 추가하면 됩니다. 에이전트는 Init 컨테이너로 주입되어 원본 이미지를 건드리지 않습니다.
Q. 이미 -javaagent 나 OMAPM_HOST 를 쓰고 있습니다.
사용자가 설정한 환경변수가 우선합니다(덮어쓰지 않음). JAVA_TOOL_OPTIONS 는 기존 값 뒤에 이어 붙습니다.
Q. 컨테이너가 여러 개인 파드는 어떻게 하나요?
openmaru.io/container-names 어노테이션으로 계측할 컨테이너를 지정하십시오.
Q. CPU/메모리 HPA 와 같이 쓸 수 있나요?
네. 표준 HPA 의 metrics 배열에 Resource(cpu/memory)와 External(tps)를 함께 넣을 수 있습니다.
Q. APM 서버가 여러 대입니다.
envHpa 에 별칭(name)별로 등록하고 HPA 의 apmAlias 로 선택합니다(302 오토스케일링 참고).
6. 문제 해결 빠른 표
| 영역 | 증상 | 해결 |
|---|---|---|
| 설치 | Operator 파드가 안 뜸 | kubectl get pod -n openmaru-apm 로 상태·로그 확인, Helm enabled: true 확인 |
| 계측 | 에이전트 미주입 | 라벨 위치(spec.template.metadata.labels)와 값 'true' 확인 |
| 계측 | 이미지 Pull 실패 | IMAGE_REGISTRY/IMAGE_NAMESPACE + was-agent-version 조합 이미지 존재 확인 |
| 계측 | APM 콘솔 미표시 | OMAPM_HOST/OMAPM_PORT 도달성 확인 |
| HPA | TARGETS <unknown> | kubectl describe hpa <이름> 의 Events 에 원인이 메시지로 나옵니다 |
| HPA | 재배포 뒤 스케일 멈춤 | 그룹 이름이 바뀌었을 가능성이 큽니다. OMAPM_APPLICATION_NAME 을 고정하십시오 |
| HPA | HTTP 403 | 별칭에 <apmAlias>_ACCESS_KEY 가 짝지어져 있는지 확인 |
| HPA | apdex 로 걸었더니 반대로 움직임 | apdexDeficit 을 쓰십시오 |
| HPA | 스케일 안 됨 | minReplicas/maxReplicas, target.value 재검토 |
| 설치 | helm 이 caBundle/tlsCrt/tlsKey 가 비었다며 멈춤 | 인증서 값을 넘겨야 합니다 (201 5절) |
7. 점검 명령 모음
# Operator 상태
kubectl get pod -n openmaru-apm
kubectl logs deploy/openmaru-operator-apm-agent -n openmaru-apm
kubectl logs deploy/openmaru-operator-apm-hpa -n openmaru-apm
# 계측 적용 확인
kubectl describe pod <pod> | grep -E "khan-agent-init|khan-data"
kubectl set env pod/<pod> --list | grep -E "OMAPM_|JAVA_TOOL_OPTIONS"
# HPA / 외부 지표
kubectl get hpa
kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/<ns>/tps" | jq .