システムコンポーネントのトレースは、クラスター内の処理のレイテンシーと処理間の関係性を記録します。
Kubernetesコンポーネントは、gRPCエクスポーターを使用してOpenTelemetry Protocolでトレースを出力し、OpenTelemetry Collectorを使用してトレースバックエンドに収集およびルーティングできます。
Kubernetesコンポーネントには、OTLPのトレースをエクスポートするための組み込みgRPCエクスポーターがあり、OpenTelemetry Collectorを使用する場合と使用しない場合の両方で利用できます。
トレースの収集とCollectorの使用に関する完全なガイドについては、OpenTelemetry Collectorの使い方を参照してください。 ただし、Kubernetesコンポーネント固有の注意点がいくつかあります。
デフォルトでは、KubernetesコンポーネントはOTLPのgRPCエクスポーターを使用して、IANA OpenTelemetryポートである4317番ポートでトレースをエクスポートします。 例えば、CollectorがKubernetesコンポーネントのサイドカーとして実行されている場合、以下のレシーバー設定でスパンを収集し、標準出力にログを出力します:
receivers:
otlp:
protocols:
grpc:
exporters:
# このエクスポーターをバックエンド用のエクスポーターに置き換えてください
exporters:
debug:
verbosity: detailed
service:
pipelines:
traces:
receivers: [otlp]
exporters: [debug]
Collectorを使用せずにバックエンドに直接トレースを出力するには、Kubernetesトレース設定ファイルのendpointフィールドに目的のトレースバックエンドアドレスを指定します。
この方法ではCollectorが不要になり、全体的な構成がシンプルになります。
認証情報を含むトレースバックエンドのヘッダー設定については、OTEL_EXPORTER_OTLP_HEADERS環境変数を使用できます。
詳細はOTLPエクスポーターの設定を参照してください。
また、Kubernetesクラスター名、名前空間、Pod名などのトレースリソース属性の設定には、OTEL_RESOURCE_ATTRIBUTES環境変数を使用できます。
詳細はOTLP Kubernetesリソースを参照してください。
kube-apiserverは、受信HTTPリクエスト、およびWebhook、etcd、再入リクエストへの送信リクエストに対してスパンを生成します。 kube-apiserverは送信リクエストでW3C Trace Contextを伝播しますが、kube-apiserverは多くの場合パブリックエンドポイントであるため、受信リクエストに付加されたトレースコンテキストは使用しません。
トレースを有効にするには、--tracing-config-file=<設定ファイルのパス>でkube-apiserverにトレース設定ファイルを提供します。
以下は、10000リクエストに1つの割合でスパンを記録し、デフォルトのOpenTelemetryエンドポイントを使用する設定の例です:
apiVersion: apiserver.config.k8s.io/v1
kind: TracingConfiguration
# default value
#endpoint: localhost:4317
samplingRatePerMillion: 100
TracingConfiguration構造体の詳細については、APIサーバー設定API (v1)を参照してください。
This is a stable feature in Kubernetes, and has been since version v1.34. It was first available in the v1.25 release. You can no longer disable or opt out of this feature or behavior (it is locked); if you explicitly set a value for the associated feature gate KubeletTracing, Kubernetes ignores it but does not report any error.
kubeletのCRIインターフェースと認証済みHTTPサーバーは、トレーススパンを生成するように計装されています。 apiserverと同様に、エンドポイントとサンプリングレートは設定可能です。 トレースコンテキストの伝播も設定されています。 親スパンのサンプリング決定は常に尊重されます。 指定されたトレース設定のサンプリングレートは、親を持たないスパンに適用されます。 エンドポイントを設定せずに有効にした場合、デフォルトのOpenTelemetry Collectorレシーバーアドレス「localhost:4317」が設定されます。
トレースを有効にするには、トレース設定を適用します。 以下は、10000リクエストに1つの割合でスパンを記録し、デフォルトのOpenTelemetryエンドポイントを使用するkubelet設定のスニペット例です:
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
tracing:
# default value
#endpoint: localhost:4317
samplingRatePerMillion: 100
samplingRatePerMillionを100万(1000000)に設定すると、すべてのスパンがエクスポーターに送信されます。
Kubernetes v1.37のkubeletは、ガベージコレクション、Pod同期ルーチン、およびすべてのgRPCメソッドからスパンを収集します。 kubeletはgRPCリクエストでトレースコンテキストを伝播するため、CRI-Oやcontainerdなどのトレースインストルメンテーションをサポートするコンテナランタイムは、kubeletからのトレースコンテキストに関連付けてエクスポートされたスパンを作成できます。 結果として得られるトレースには、kubeletとコンテナランタイムのスパン間の親子リンクが含まれ、ノードの問題をデバッグする際に役立つコンテキストを提供します。
スパンのエクスポートには、システム全体の設定に応じて、ネットワークとCPU側で常に小さなパフォーマンスオーバーヘッドが発生することに注意してください。
トレースが有効なクラスターでそのような問題が発生した場合は、samplingRatePerMillionを減らすか、設定を削除してトレースを完全に無効にすることで問題を軽減してください。
トレースインストルメンテーションはまだ活発に開発中であり、さまざまな形で変更される可能性があります。 これには、スパン名、付加された属性、計測対象のエンドポイントなどが含まれます。 この機能がStableに昇格するまで、トレースインストルメンテーションの後方互換性は保証されません。