diff --git a/content/ko/docs/concepts/cluster-administration/system-traces.md b/content/ko/docs/concepts/cluster-administration/system-traces.md new file mode 100644 index 0000000000..589c62eb86 --- /dev/null +++ b/content/ko/docs/concepts/cluster-administration/system-traces.md @@ -0,0 +1,89 @@ +--- +title: 쿠버네티스 시스템 컴포넌트에 대한 추적(trace) + + + +content_type: concept +weight: 60 +--- + + + +{{< feature-state for_k8s_version="v1.22" state="alpha" >}} + +시스템 컴포넌트 추적은 클러스터 내에서 수행된 동작들 간의 지연(latency)과 관계(relationship)를 기록한다. + +쿠버네티스 컴포넌트들은 [OpenTelemetry 프로토콜](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/otlp.md#opentelemetry-protocol-specification)과 +gRPC exporter를 이용하여 추적을 생성하고 +[OpenTelemetry 수집기](https://github.com/open-telemetry/opentelemetry-collector#-opentelemetry-collector)를 +통해 추적 백엔드(tracing backends)로 라우팅되거나 수집될 수 있다. + + + +## 추적 수집 + +추적 수집 및 수집기에 대한 전반적인 가이드는 +[OpenTelemetry 수집기 시작하기](https://opentelemetry.io/docs/collector/getting-started/)에서 제공한다. +그러나, 쿠버네티스 컴포넌트에 관련된 몇 가지 사항에 대해서는 특별히 살펴볼 필요가 있다. + +기본적으로, 쿠버네티스 컴포넌트들은 [IANA OpenTelemetry 포트](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=opentelemetry)인 +4317 포트로 OTLP에 대한 grpc exporter를 이용하여 추적를 내보낸다. +예를 들면, 수집기가 쿠버네티스 컴포넌트에 대해 사이드카(sidecar)로 동작한다면, +다음과 같은 리시버 설정을 통해 span을 수집하고 그 로그를 표준 출력(standard output)으로 내보낼 것이다. + +```yaml +receivers: + otlp: + protocols: + grpc: +exporters: + # 이 exporter를 사용자의 백엔드를 위한 exporter로 변경 + logging: + logLevel: debug +service: + pipelines: + traces: + receivers: [otlp] + exporters: [logging] +``` + +## 컴포넌트 추적 + +### kube-apiserver 추적 + +kube-apiserver는 들어오는 HTTP 요청들과 +webhook, etcd 로 나가는 요청들, 그리고 재진입 요청들에 대해 span을 생성한다. +kube-apiserver는 자주 퍼블릭 엔드포인트로 이용되기 때문에, +들어오는 요청들에 첨부된 추적 컨택스트를 사용하지 않고, +나가는 요청들을 통해 [W3C Trace Context](https://www.w3.org/TR/trace-context/)를 전파한다. + +#### kube-apiserver 에서의 추적 활성화 + +추적을 활성화하기 위해서는, kube-apiserve에서 `APIServerTracing` +[기능 게이트](/ko/docs/reference/command-line-tools-reference/feature-gates/)를 활성화한다. +또한, kube-apiserver의 추적 설정 파일에 +`--tracing-config-file=`을 추가한다. +다음은 10000개 요청 당 1개에 대한 span을 기록하는 설정에 대한 예시이고, 이는 기본 OpenTelemetry 엔드포인트를 이용한다. + +```yaml +apiVersion: apiserver.config.k8s.io/v1alpha1 +kind: TracingConfiguration +# 기본값 +#endpoint: localhost:4317 +samplingRatePerMillion: 100 +``` + +`TracingConfiguration` 구조체에 대해 더 많은 정보를 얻고 싶다면 +[API server config API (v1alpha1)](/docs/reference/config-api/apiserver-config.v1alpha1/#apiserver-k8s-io-v1alpha1-TracingConfiguration)를 참고한다. + +## 안정성 + +추적의 계측화(tracing instrumentation)는 여전히 활발히 개발되는 중이어서 다양한 형태로 변경될 수 있다. +span의 이름, 첨부되는 속성, 계측될 엔드포인트(instrumented endpoints)들 등이 그렇다. +이 속성이 안정화(graduates to stable)되기 전까지는 +이전 버전과의 호환성은 보장되지 않는다. + +## {{% heading "whatsnext" %}} + +* [OpenTelemetry 수집기 시작하기](https://opentelemetry.io/docs/collector/getting-started/)을 참고 +