쿠버네티스 시스템 컴포넌트의 트레이스
쿠버네티스 시스템 컴포넌트의 트레이스 (Traces For Kubernetes System Components)
시스템 컴포넌트 트레이스는 클러스터 안의 작업 사이의 지연 시간과 관계를 기록해요.
쿠버네티스 컴포넌트는 gRPC 익스포터와 함께 OpenTelemetry Protocol을 사용해 트레이스를 내보내며, OpenTelemetry Collector를 사용해 수집하고 트레이싱 백엔드로 라우팅할 수 있어요.
출처: 문서
본문
트레이스 수집 (Trace Collection)
쿠버네티스 컴포넌트는 OpenTelemetry Collector가 있든 없든 트레이스를 내보내기 위해 OTLP용 내장 gRPC 익스포터를 가져요.
트레이스를 수집하고 collector를 사용하는 완전한 가이드는 OpenTelemetry Collector 시작하기를 참고해요. 다만 쿠버네티스 컴포넌트에 특정한 몇 가지 주의할 점이 있어요.
기본적으로 쿠버네티스 컴포넌트는 IANA OpenTelemetry 포트 4317에서 OTLP용 grpc 익스포터로 트레이스를 내보내요. 예를 들어 collector가 쿠버네티스 컴포넌트의 사이드카로 실행된다면, 다음 receiver 구성으로 스팬을 수집해 표준 출력으로 기록해요:
receivers:
otlp:
protocols:
grpc:
exporters:
# Replace this exporter with the exporter for your backend
exporters:
debug:
verbosity: detailed
service:
pipelines:
traces:
receivers: [otlp]
exporters: [debug]
collector를 사용하지 않고 백엔드로 직접 트레이스를 내보내려면, 쿠버네티스 트레이싱 구성 파일의 endpoint 필드에 원하는 트레이스 백엔드 주소를 지정해요. 이 방법은 collector의 필요성을 없애고 전체 구조를 단순화해요.
인증 세부 사항을 포함한 트레이스 백엔드 헤더 구성은 OTEL_EXPORTER_OTLP_HEADERS 로 환경 변수를 사용할 수 있어요. OTLP Exporter Configuration 참고.
추가로 쿠버네티스 클러스터 이름, 네임스페이스, Pod 이름 같은 트레이스 리소스 속성 구성은 OTEL_RESOURCE_ATTRIBUTES 로 환경 변수를 사용할 수도 있어요. OTLP Kubernetes Resource 참고.
컴포넌트 트레이스
kube-apiserver 트레이스
kube-apiserver는 수신 HTTP 요청과 webhook·etcd로의 발신 요청, 재진입(re-entrant) 요청에 대한 스팬을 생성해요. 발신 요청과 함께 W3C Trace Context를 전파하지만, kube-apiserver가 공개 엔드포인트인 경우가 많아 수신 요청에 첨부된 트레이스 컨텍스트는 사용하지 않아요.
kube-apiserver에서 트레이싱 활성화하기
트레이싱을 활성화하려면 --tracing-config-file=<path-to-config> 로 kube-apiserver에 트레이싱 구성 파일을 제공해요. 다음은 10000개 요청 중 1개에 대한 스팬을 기록하고 기본 OpenTelemetry 엔드포인트를 사용하는 예시 구성이에요:
apiVersion: apiserver.config.k8s.io/v1
kind: TracingConfiguration
# default value
#endpoint: localhost:4317
samplingRatePerMillion: 100
TracingConfiguration 구조체에 대한 자세한 내용은 API server config API (v1)를 참고해요.
kubelet 트레이스
이는 쿠버네티스의 stable 기능이며 버전 v1.34부터 stable입니다. 처음에는 v1.25 릴리스에서 사용할 수 있었어요. 이 기능이나 동작은 더 이상 비활성화하거나 옵트아웃할 수 없어요(잠겨 있음). 관련 기능 게이트에 값을 명시적으로 설정하면 쿠버네티스는 그 값을 무시하지만 오류를 보고하지 않아요.
kubelet CRI 인터페이스와 인증된 http 서버는 트레이스 스팬을 생성하도록 계측(instrumented)돼 있어요. apiserver와 마찬가지로 endpoint와 샘플링 속도는 구성 가능해요. 트레이스 컨텍스트 전파도 구성돼요. 상위 스팬의 샘플링 결정은 항상 존중돼요. 제공된 트레이싱 구성 샘플링 속도는 상위가 없는 스팬에 적용돼요. endpoint가 구성되지 않은 채 활성화되면 기본 OpenTelemetry Collector receiver 주소인 "localhost:4317" 이 설정돼요.
kubelet에서 트레이싱 활성화하기
트레이싱을 활성화하려면 tracing configuration을 적용해요. 다음은 10000개 요청 중 1개에 대한 스팬을 기록하고 기본 OpenTelemetry 엔드포인트를 사용하는 kubelet 구성의 예시 스니펫이에요:
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
tracing:
# default value
#endpoint: localhost:4317
samplingRatePerMillion: 100
samplingRatePerMillion 이 1백만(1000000)으로 설정되면 모든 스팬이 익스포터로 전송돼요.
쿠버네티스 v1.37의 kubelet은 가비지 컬렉션, 파드 동기화 루틴, 그리고 모든 gRPC 메서드에서 스팬을 수집해요. kubelet은 gRPC 요청과 함께 트레이스 컨텍스트를 전파해서 CRI-O나 containerd 같은 트레이스 계측이 있는 컨테이너 런타임이 kubelet의 트레이스 컨텍스트와 함께 자신의 내보낸 스팬을 연관시킬 수 있게 해요. 결과 트레이스는 kubelet 스팬과 컨테이너 런타임 스팬 사이에 부모-자식 링크를 가져, 노드 문제를 디버깅할 때 유용한 컨텍스트를 제공해요.
스팬 내보내기는 시스템의 전체 구성에 따라 네트워킹·CPU 측면에서 항상 약간의 성능 오버헤드가 수반된다는 점을 기억하세요. 트레이싱을 활성화한 채 실행 중인 클러스터에서 그런 문제가 있다면 samplingRatePerMillion 을 줄이거나 구성을 제거해 트레이싱을 완전히 비활성화해 문제를 완화해요.
안정성 (Stability)
트레이스 계측은 아직 활발히 개발 중이며 다양한 방식으로 바뀔 수 있어요. 여기에는 스팬 이름, 첨부된 속성, 계측된 엔드포인트 등이 포함돼요. 이 기능이 stable로 승격될 때까지 트레이스 계측에 대한 이전 버전과의 호환성은 보장되지 않아요.