자동 계측

코드 변경 없이 애플리케이션을 자동으로 계측하는 방법을 안내합니다.

개요

자동 계측을 통해 코드 수정 없이 분산 트레이싱과 메트릭을 수집할 수 있습니다.

자동 계측 옵션

APM Agent (eBPF 기반)

개요

APM Agent는 eBPF 기술을 사용하여 커널 레벨에서 네트워크 트래픽을 감지합니다.

장점

• ✅ 코드 변경 불필요
• ✅ 설정 변경 불필요
• ✅ 모든 언어 지원
• ✅ 낮은 오버헤드
• ✅ 네트워크 플로우 시각화

요구사항

확인 방법

APM Agent가 정상 동작하는지 확인:

# APM Agent 파드 상태 확인
kubectl get pods -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent

# APM Agent 로그 확인
kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent --tail=50

# 감지된 프로세스 확인
kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent | grep "discovered"

자동 감지 프로토콜

수집 메트릭

APM Agent가 자동 수집하는 RED 메트릭:

# 요청률 (Rate)
http_server_request_total
grpc_server_started_total

# 에러 (Errors)
http_server_errors_total
grpc_server_handled_total{grpc_code!="OK"}

# 지연시간 (Duration)
http_server_request_duration_seconds
grpc_server_handling_seconds

OpenTelemetry Operator

개요

OTel Operator는 Kubernetes에서 사이드카를 자동 주입하여 더 상세한 트레이스를 수집합니다.

장점

• ✅ 코드 변경 불필요
• ✅ 더 상세한 내부 트레이스
• ✅ 언어별 최적화된 계측
• ✅ 세밀한 설정 제어

설치 확인

Agent 클러스터 설치 시 OTel Operator가 함께 설치됩니다:

# Operator 상태 확인
kubectl get pods -n skuber-observability -l app.kubernetes.io/name=opentelemetry-operator

# Instrumentation CRD 확인
kubectl get instrumentation -n skuber-observability

자동 계측 활성화

네임스페이스 또는 파드에 어노테이션을 추가하여 자동 계측을 활성화합니다.

네임스페이스 전체 적용

apiVersion: v1
kind: Namespace
metadata:
  name: my-app
  annotations:
    instrumentation.opentelemetry.io/inject-java: "skuber-observability/otel-instrumentation"

개별 파드 적용

apiVersion: v1
kind: Pod
metadata:
  name: my-java-app
  annotations:
    instrumentation.opentelemetry.io/inject-java: "skuber-observability/otel-instrumentation"
spec:
  containers:
    - name: app
      image: my-java-app:latest

언어별 어노테이션

값 옵션

APM Agent vs OTel Operator

기능 비교

선택 가이드

함께 사용하기

APM Agent와 OTel Operator를 함께 사용할 수 있습니다:

• APM Agent: 네트워크 레벨 메트릭 + Service Map
• OTel Operator: 상세 애플리케이션 트레이스

설정 예시

Java 애플리케이션

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  namespace: production
spec:
  template:
    metadata:
      annotations:
        # OTel Operator 자동 계측 활성화
        instrumentation.opentelemetry.io/inject-java: "skuber-observability/otel-instrumentation"
    spec:
      containers:
        - name: app
          image: order-service:1.0.0
          ports:
            - containerPort: 8080

Python 애플리케이션

apiVersion: apps/v1
kind: Deployment
metadata:
  name: user-service
  namespace: production
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-python: "skuber-observability/otel-instrumentation"
    spec:
      containers:
        - name: app
          image: user-service:1.0.0

Node.js 애플리케이션

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-gateway
  namespace: production
spec:
  template:
    metadata:
      annotations:
        instrumentation.opentelemetry.io/inject-nodejs: "skuber-observability/otel-instrumentation"
    spec:
      containers:
        - name: app
          image: api-gateway:1.0.0

트러블슈팅

APM Agent 문제

트레이스가 수집되지 않음

1. 커널 버전 확인:

   uname -r  # 5.8 이상 필요

2. APM Agent 로그 확인:

   kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent | grep -i error

3. eBPF 지원 확인:

   kubectl logs -n skuber-observability -l app.kubernetes.io/name=skuber-apm-agent | grep "BTF"

특정 서비스가 감지되지 않음

1. 지원 프로토콜인지 확인
2. 서비스에 트래픽이 있는지 확인
3. 포트가 표준 포트인지 확인 (80, 443, 8080 등)

OTel Operator 문제

사이드카가 주입되지 않음

1. 어노테이션 확인:

   kubectl get pod <pod-name> -o yaml | grep instrumentation

2. Instrumentation CRD 확인:

   kubectl get instrumentation -n skuber-observability

3. Operator 로그 확인:

   kubectl logs -n skuber-observability -l app.kubernetes.io/name=opentelemetry-operator

트레이스가 전송되지 않음

1. 사이드카 로그 확인:

   kubectl logs <pod-name> -c opentelemetry-auto-instrumentation

2. OTel Collector 연결 확인

다음 단계

• Java 계측 - Java 수동 계측 가이드
• Python 계측 - Python 수동 계측 가이드
• Node.js 계측 - Node.js 수동 계측 가이드
• Go 계측 - Go 수동 계측 가이드
• .NET 계측 - .NET 수동 계측 가이드