시스템 컴포넌트 트레이스

시스템 컴포넌트 트레이스 (Traces For Kubernetes System Components)

클러스터가 느리게 반응하거나 특정 작업이 지연될 때, "어디서 시간이 걸리는지"를 정확히 짚어내기란 쉽지 않아요. 시스템 컴포넌트 트레이스는 바로 이런 문제를 진단할 때 큰 도움이 됩니다. 클러스터 운영 간의 대기 시간(latency)과 관계(relationship)를 기록해 주거든요.

출처: 쿠버네티스 공식 문서 — Traces For Kubernetes System Components

기능 상태: Kubernetes v1.27 [beta]

시스템 컴포넌트 트레이스는 클러스터 안의 작업 간 대기 시간과 관계를 기록해요. 쿠버네티스 컴포넌트는 OpenTelemetry Protocol(OTLP)을 gRPC 익스포터와 함께 사용해 트레이스를 내보내며, OpenTelemetry Collector를 통해 수집·라우팅될 수 있습니다.

트레이스 수집 (Trace Collection)

쿠버네티스 컴포넌트는 OTLP용 gRPC 익스포터가 내장되어 있어, OpenTelemetry Collector를 사용하거나 사용하지 않고 트레이스를 내보낼 수 있어요.

기본적으로 쿠버네티스 컴포넌트는 IANA OpenTelemetry 포트 4317에서 OTLP용 grpc 익스포터로 트레이스를 내보냅니다. 예를 들어 Collector가 쿠버네티스 컴포넌트의 사이드카로 실행 중이라면, 아래 리시버 설정은 스팬을 수집해 표준 출력으로 로깅합니다.

receivers:
  otlp:
    protocols:
      grpc:
exporters:
  # 이 익스포터를 백엔드용 익스포터로 바꾸세요
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]

Collector 없이 백엔드로 직접 트레이스를 내보내려면, 쿠버네티스 트레이싱 설정 파일의 endpoint 필드에 원하는 트레이스 백엔드 주소를 지정하면 돼요. 이 방법은 Collector가 필요 없어져 전체 구조가 단순해집니다.

트레이스 백엔드 헤더 설정(인증 포함)에는 환경 변수 OTEL_EXPORTER_OTLP_HEADERS를 사용할 수 있고, 클러스터 이름·네임스페이스·Pod 이름 같은 트레이스 리소스 속성 설정에는 OTEL_RESOURCE_ATTRIBUTES 환경 변수를 사용할 수 있어요.

컴포넌트 트레이스 (Component traces)

kube-apiserver 트레이스

kube-apiserver는 들어오는 HTTP 요청과, 웹훅·etcd·재진입(re-entrant) 요청으로 나가는 요청에 대한 스팬을 생성해요. 나가는 요청에는 W3C Trace Context를 전파하지만, 들어오는 요청에 붙은 트레이스 컨텍스트는 사용하지 않습니다. kube-apiserver는 공개 엔드포인트인 경우가 많기 때문이에요.

트레이싱 활성화: kube-apiserver에 --tracing-config-file=<path-to-config>로 트레이싱 설정 파일을 제공하세요. 아래는 10000개 중 1개 요청에 대해 스팬을 기록하고 기본 OpenTelemetry 엔드포인트를 쓰는 예시 설정입니다.

apiVersion: apiserver.config.k8s.io/v1
kind: TracingConfiguration
# 기본값
# endpoint: localhost:4317
samplingRatePerMillion: 100

TracingConfiguration 구조체에 대한 자세한 내용은 API 서버 설정 API (v1)를 참고하세요.

kubelet 트레이스

기능 상태: Kubernetes v1.34 [stable](기본 활성화)

kubelet의 CRI 인터페이스와 인증된 http 서버는 트레이스 스팬을 생성하도록 계측(instrument)됩니다. apiserver와 마찬가지로 엔드포인트와 샘플링 비율을 설정할 수 있고, 트레이스 컨텍스트 전파도 설정됩니다. 부모 스팬의 샘플링 결정은 항상 존중되고, 부모가 없는 스팬에는 제공된 샘플링 비율이 적용돼요. 엔드포인트가 설정되지 않았더라도 기본 OpenTelemetry Collector 리시버 주소인 localhost:4317이 설정됩니다.

트레이싱 활성화: 트레이싱 설정을 적용하세요. 아래는 10000개 중 1개 요청에 대해 스팬을 기록하고 기본 OpenTelemetry 엔드포인트를 쓰는 kubelet 설정 예시입니다.

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
tracing:
  # 기본값
  # endpoint: localhost:4317
  samplingRatePerMillion: 100

samplingRatePerMillion을 백만(1000000)으로 설정하면 모든 스팬이 익스포터로 전송됩니다.

쿠버네티스 v1.36의 kubelet은 가비지 컬렉션, Pod 동기화 루틴, 그리고 모든 gRPC 메서드에서 스팬을 수집해요. kubelet은 gRPC 요청과 함께 트레이스 컨텍스트를 전파해서, CRI-O나 containerd처럼 트레이스 계측이 있는 컨테이너 런타임이 kubelet의 트레이스 컨텍스트와 자신이 내보낸 스팬을 연결할 수 있게 합니다. 결과적으로 kubelet과 컨테이너 런타임 스팬 사이에 부모-자식 링크가 생겨, 노드 문제를 디버깅할 때 유용한 컨텍스트를 제공해요.

스팬 내보내기는 시스템 전체 설정에 따라 네트워킹·CPU 쪽에 약간의 성능 오버헤드를 동반합니다. 트레이싱을 켠 클러스터에서 그런 문제가 생기면 samplingRatePerMillion을 줄이거나, 설정을 제거해 트레이싱을 완전히 끄는 방식으로 완화하세요.

안정성 (Stability)

트레이싱 계측은 아직 활발히 개발 중이며, 스팬 이름·붙는 속성·계측된 엔드포인트 등 여러 방식으로 바뀔 수 있어요. 이 기능이 stable로 올라가기 전까지는 트레이싱 계측에 대한 하위 호환성이 보장되지 않습니다.

시스템 컴포넌트 트레이스