Kubernetes 系统组件的跟踪

特性状态: Kubernetes v1.27 [beta]

系统组件跟踪记录了集群中操作的延迟和关系。

Kubernetes 组件使用 OpenTelemetry 协议与 gRPC 导出器发出跟踪,可以通过 OpenTelemetry Collector 收集并路由到跟踪后端。

跟踪收集

Kubernetes 组件内置了用于 OTLP 的 gRPC 导出器,可以通过 OpenTelemetry Collector 或不通过 OpenTelemetry Collector 导出跟踪。

有关收集跟踪和使用收集器的完整指南,请参阅 OpenTelemetry Collector 入门。但是,有一些特定于 Kubernetes 组件的注意事项。

默认情况下,Kubernetes 组件使用 OTLP 的 gRPC 导出器在 IANA OpenTelemetry 端口 4317 上导出跟踪。例如,如果收集器作为 Kubernetes 组件的 Sidecar 运行,以下接收器配置将收集 Span 并将其记录到标准输出:

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]

要不使用收集器直接将跟踪发送到后端,请在 Kubernetes 跟踪配置文件中通过所需的跟踪后端地址指定 `endpoint` 字段。这种方法无需收集器,简化了整体结构。

对于跟踪后端标头配置,包括身份验证详细信息,可以使用带有 `OTEL_EXPORTER_OTLP_HEADERS` 的环境变量,请参阅 OTLP 导出器配置

此外,对于跟踪资源属性配置,例如 Kubernetes 集群名称、命名空间、Pod 名称等,还可以使用带有 `OTEL_RESOURCE_ATTRIBUTES` 的环境变量,请参阅 OTLP Kubernetes 资源

组件跟踪

kube-apiserver 跟踪

kube-apiserver 为传入的 HTTP 请求以及对 Webhook、etcd 和重入请求的传出请求生成 Span。它在传出请求中传播 W3C 跟踪上下文,但由于 kube-apiserver 通常是公共端点,因此不使用附加到传入请求的跟踪上下文。

在 kube-apiserver 中启用跟踪

要启用跟踪,请使用 `--tracing-config-file=<path-to-config>` 为 kube-apiserver 提供跟踪配置文件。这是一个示例配置,它为 10000 个请求中的 1 个请求记录 Span,并使用默认的 OpenTelemetry 端点:

apiVersion: apiserver.config.k8s.io/v1
kind: TracingConfiguration
# default value
#endpoint: localhost:4317
samplingRatePerMillion: 100

有关 `TracingConfiguration` 结构的更多信息,请参阅 API 服务器配置 API (v1)

kubelet 跟踪

特性状态: Kubernetes v1.34 [稳定] (默认启用:true)

kubelet CRI 接口和经过身份验证的 HTTP 服务器都经过检测以生成跟踪 Span。与 apiserver 一样,端点和采样率都是可配置的。跟踪上下文传播也已配置。父 Span 的采样决策始终受到尊重。提供的跟踪配置采样率将应用于没有父 Span 的 Span。如果未配置端点,则默认 OpenTelemetry Collector 接收器地址“localhost:4317”将被设置。

在 kubelet 中启用跟踪

要启用跟踪,请应用 跟踪配置。这是一个 kubelet 配置示例片段,它为 10000 个请求中的 1 个请求记录 Span,并使用默认的 OpenTelemetry 端点:

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
tracing:
  # default value
  #endpoint: localhost:4317
  samplingRatePerMillion: 100

如果 `samplingRatePerMillion` 设置为一百万(`1000000`),则每个 Span 都将发送到导出器。

Kubernetes v1.34 中的 kubelet 会从垃圾收集、Pod 同步例程以及每个 gRPC 方法收集 Span。kubelet 会通过 gRPC 请求传播跟踪上下文,以便支持跟踪检测的容器运行时(例如 CRI-O 和 containerd)可以将其导出的 Span 与来自 kubelet 的跟踪上下文相关联。生成的跟踪将在 kubelet 和容器运行时 Span 之间具有父子链接,这在调试节点问题时提供了有用的上下文。

请注意,导出 Span 始终会带来网络和 CPU 方面的小幅性能开销,具体取决于系统的总体配置。如果在启用了跟踪的集群中出现此类问题,可以通过降低 `samplingRatePerMillion` 或通过删除配置完全禁用跟踪来缓解问题。

稳定性

跟踪检测仍在积极开发中,可能会以各种方式发生变化。这包括 Span 名称、附加属性、检测的端点等。在此功能稳定之前,无法保证跟踪检测的向后兼容性。

下一步

最后修改时间:2025 年 7 月 2 日下午 12:05 (PST):KEP-2831: kubelet tracing GA in 1.34 (f8d1342d61)