Kubernetesのための重要なコンポーネント

OpenTelemetry Collectorは、Kubernetesの監視を容易にするために、多くの異なるレシーバーとプロセッサーをサポートしています。 このセクションでは、Kubernetesのデータを収集し、それを拡張するためにもっとも重要なコンポーネントを取り上げます。

このページで取り上げているコンポーネントは以下の通りです。

アプリケーションのトレース、メトリクス、またはログの場合は、OTLPレシーバー をおすすめしますが、データに合ったレシーバーであれば何でも構いません。

Kubernetes属性プロセッサー (Kubernetes Attributes Processor)

デプロイメントパターン利用可能
DaemonSet （エージェント）Yes
Deployment （ゲートウェイ）Yes
サイドカーNo

Kubernetes属性プロセッサーは、Kubernetesポッドを自動的に検出し、そのメタデータを抽出し、抽出したメタデータをリソース属性としてスパン、メトリクス、ログに追加します。

Kubernetes属性プロセッサーは、Kubernetesで動作するコレクターにとってもっとも重要なコンポーネントの1つです。アプリケーションデータを受信するコレクターは、これを使用すべきです。 Kubernetes属性プロセッサーはテレメトリーにKubernetesのコンテキストを追加するため、アプリケーションのトレース、メトリクス、ログのシグナルをポッドのメトリクスやトレースなどのKubernetesテレメトリーと関連付けることができます。

Kubernetes属性プロセッサーは、Kubernetes APIを使用してクラスタ内で実行されているすべてのポッドを検出し、それらのIPアドレス、ポッドのUID、および興味深いメタデータの記録を保持します。 デフォルトでは、プロセッサーを通過するデータは、受信リクエストのIPアドレスを介してポッドに関連付けられますが、異なるルールを設定することもできます。 プロセッサーはKubernetes APIを使用するため、特別なパーミッションが必要です（以下の例を参照）。 OpenTelemetryコレクターHelmチャート を使っている場合は、kubernetesAttributes preset を使って開始できます。

デフォルトでは以下の属性が追加されます。

  • k8s.namespace.name
  • k8s.pod.name
  • k8s.pod.uid
  • k8s.pod.start_time
  • k8s.deployment.name
  • k8s.node.name

Kubernetes属性プロセッサーは、ポッドと名前空間に追加したKubernetesラベルとKubernetesアノテーションを使用して、トレース、メトリクス、ログのカスタムリソース属性を設定することもできます。

k8sattributes:  auth_type: 'serviceAccount'  extract:  metadata: # ポッドから抽出  - k8s.namespace.name  - k8s.pod.name  - k8s.pod.start_time  - k8s.pod.uid  - k8s.deployment.name  - k8s.node.name  annotations:  # キー `annotation-one` を持つポッドアノテーションの値を取り出し、キー `a1` を持つリソース属性として挿入します。  - tag_name: a1  key: annotation-one  from: pod  # キー `annotation-two` を持つ名前空間アノテーションの値を正規表現で抽出し、キー `a2` を持つリソースに挿入します。  - tag_name: a2  key: annotation-two  regex: field=(?P<value>.+)  from: namespace  labels:  # キー `label1` を持つ名前空間ラベルの値を取り出し、キー `l1` を持つリソース属性として挿入します。  - tag_name: l1  key: label1  from: namespace  # キー `label2` を持つポッドラベルの値を正規表現で抽出し、キー `l2` を持つリソース属性として挿入します。  - tag_name: l2  key: label2  regex: field=(?P<value>.+)  from: pod  pod_association: # データをポッドに関連付ける方法（順序が重要）  - sources: # まず、リソース属性k8s.pod.ipの値を使用してみます。  - from: resource_attribute  name: k8s.pod.ip  - sources: # 次に、リソース属性k8s.pod.uidの値を使用してみます。  - from: resource_attribute  name: k8s.pod.uid  - sources: # どちらもうまくいかない場合は、リクエストのコネクションを使ってポッドのIPを取得します。  - from: connection

コレクターが Kubernetes DaemonSet (エージェント) または Kubernetes Deployment (ゲートウェイ) としてデプロイされる場合の特別な設定オプションもあります。 詳細はデプロイメントシナリオを参照してください。

Kubernetes属性プロセッサーの設定の詳細については、Kubernetes Attributes Processorを参照してください。

プロセッサーはKubernetes APIを使用するため、正しく動作するには適切なパーミッションが必要です。 ほとんどのユースケースでは、コレクターを実行するサービスアカウントにClusterRoleを介して以下の権限を与える必要があります。

apiVersion: v1 kind: ServiceAccount metadata:  name: collector  namespace: <OTEL_COL_NAMESPACE> --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata:  name: otel-collector rules:  - apiGroups:  - ''  resources:  - 'pods'  - 'namespaces'  verbs:  - 'get'  - 'watch'  - 'list'  - apiGroups:  - 'apps'  resources:  - 'replicasets'  verbs:  - 'get'  - 'list'  - 'watch'  - apiGroups:  - 'extensions'  resources:  - 'replicasets'  verbs:  - 'get'  - 'list'  - 'watch' --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata:  name: otel-collector subjects:  - kind: ServiceAccount  name: collector  namespace: <OTEL_COL_NAMESPACE> roleRef:  kind: ClusterRole  name: otel-collector  apiGroup: rbac.authorization.k8s.io

Kubeletstatsレシーバー (Kubeletstats Receiver)

デプロイメントパターン利用可能
DaemonSet （エージェント）推奨
Deployment （ゲートウェイ）Yes ただし、デプロイされたノードからのみメトリクスを収集する
サイドカーNo

各Kubernetesノードは、APIサーバーを含むkubeletを実行します。 KubeletstatsレシーバーはAPIサーバーを介してそのkubeletに接続し、ノードとノード上で実行されているワークロードに関するメトリクスを収集します。

認証にはさまざまな方法がありますが、通常はサービスアカウントが使用されます。 サービスアカウントは、Kubeletからデータをプルするための適切なパーミッションも必要となります（下記参照）。 OpenTelemetryコレクターHelmチャート を使用している場合は、kubeletMetrics preset を使用して開始できます。

デフォルトでは、メトリクスはポッドとノードに対して収集されますが、コンテナとボリュームのメトリクスも収集するようにレシーバーを設定できます。 レシーバーでは、メトリクスを収集する頻度も設定できます。

receivers:  kubeletstats:  collection_interval: 10s  auth_type: 'serviceAccount'  endpoint: '${env:K8S_NODE_NAME}:10250'  insecure_skip_verify: true  metric_groups:  - node  - pod  - container

収集されるメトリクスの具体的な詳細については、デフォルトメトリクスを参照してください。 具体的な設定の詳細については、Kubeletstatsレシーバーのドキュメントを参照してください。

プロセッサーはKubernetes APIを使用するため、正しく動作するには適切なパーミッションが必要です。 ほとんどのユースケースでは、コレクターを実行しているサービスアカウントにClusterRoleを介して以下の権限を与える必要があります。

--- apiVersion: v1 kind: ServiceAccount metadata:  name: otel-collector --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata:  name: otel-collector rules:  - apiGroups: ['']  resources: ['nodes/stats']  verbs: ['get', 'watch', 'list'] --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata:  name: otel-collector roleRef:  apiGroup: rbac.authorization.k8s.io  kind: ClusterRole  name: otel-collector subjects:  - kind: ServiceAccount  name: otel-collector  namespace: default

ファイルログレシーバー (Filelog Receiver)

デプロイメントパターン利用可能
DaemonSet （エージェント）推奨
Deployment （ゲートウェイ）Yes ただし、ログを収集するのは、それがデプロイされているノードからのみ
サイドカーYes しかし、これは高度な設定とみなされるでしょう

ファイルログレシーバーは、ファイルからのログをテイルし、解析します。 Kubernetesに特化したレシーバーではないですが、Kubernetesからあらゆるログを収集するための事実上のソリューションであることに変わりありません。

ファイルログレシーバーは、ログを処理するために連結されるオペレーターで構成されます。 各オペレーターは、タイムスタンプやJSONの解析など、単純な責任を実行します。 ファイルログレシーバーの設定は簡単ではありません。 OpenTelemetryコレクターHelmチャート を使っている場合は、logsCollection preset を使って開始できます。

Kubernetesのログは通常、一連の標準フォーマットに適合するため、Kubernetes用の典型的なFilelogレシーバー設定は次のようになります。

filelog:  include:  - /var/log/pods/*/*/*.log  exclude:  # Exclude logs from all containers named otel-collector  - /var/log/pods/*/otel-collector/*.log  start_at: end  include_file_path: true  include_file_name: false  operators:  # parse container logs  - type: container  id: container-parser

ファイルログレシーバーの設定の詳細については、ファイルログレシーバーのドキュメントを参照してください。

Filelog Receiverの設定に加えて、KubernetesにインストールしたOpenTelemetryコレクターは、収集したいログにアクセスする必要があります。 通常、これはコレクターマニフェストにボリュームとボリュームマウントを追加することを意味します。

--- apiVersion: apps/v1 kind: DaemonSet ... spec:  ...  template:  ...  spec:  ...  containers:  - name: opentelemetry-collector  ...  volumeMounts:  ...  # ボリュームをコレクターコンテナにマウントする  - name: varlogpods  mountPath: /var/log/pods  readOnly: true  - name: varlibdockercontainers  mountPath: /var/lib/docker/containers  readOnly: true  ...  volumes:  ...  # 通常、コレクターはポッドログとコンテナログにアクセスしたいでしょう  - name: varlogpods  hostPath:  path: /var/log/pods  - name: varlibdockercontainers  hostPath:  path: /var/lib/docker/containers  ...

Kubernetesクラスターレシーバー (Kubernetes Cluster Receiver)

デプロイメントパターン利用可能
DaemonSet （エージェント）Yes しかし、データが重複する
Deployment （ゲートウェイ）Yes しかし、2つ以上のレプリカを使用すると、データが重複する
サイドカーNo

Kubernetesクラスターレシーバーは、Kubernetes APIサーバーを使用してクラスタ全体に関するメトリクスとエンティティイベントを収集します。 ポッドのフェーズ、ノードの状態、およびその他のクラスタ全体の疑問に答えるためには、このレシーバーを使用します。 レシーバーはクラスタ全体のテレメトリーを収集するので、すべてのデータを収集するためにクラスタ全体で必要なレシーバーのインスタンスは1つだけです。

認証にはさまざまな方法がありますが、通常はサービスアカウントが使われます。 サービスアカウントには、Kubernetes API サーバーからデータを引き出すための適切なパーミッションも必要です（下記参照）。 OpenTelemetryコレクターHelmチャート を使っている場合は、clusterMetrics preset を使って開始できます。

ノードの状態については、デフォルトでは Ready のみを収集しますが、それ以上を収集するように設定することもできます。 また、cpu や memory などの割り当て可能なリソースを報告するように設定することも可能です。

k8s_cluster:  auth_type: serviceAccount  node_conditions_to_report:  - Ready  - MemoryPressure  allocatable_types_to_report:  - cpu  - memory

収集されるメトリクスの詳細については、デフォルトメトリクス を参照してください。 設定の詳細については、Kubernetesクラスターレシーバーのドキュメントを参照してください。

プロセッサーはKubernetes APIを使用するため、正しく動作するには適切なパーミッションが必要です。 ほとんどのユースケースでは、コレクターを実行しているサービスアカウントにClusterRoleを介して以下の権限を与える必要があります。

--- apiVersion: v1 kind: ServiceAccount metadata:  name: otel-collector-opentelemetry-collector --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata:  name: otel-collector-opentelemetry-collector rules:  - apiGroups:  - ''  resources:  - events  - namespaces  - namespaces/status  - nodes  - nodes/spec  - pods  - pods/status  - replicationcontrollers  - replicationcontrollers/status  - resourcequotas  - services  verbs:  - get  - list  - watch  - apiGroups:  - apps  resources:  - daemonsets  - deployments  - replicasets  - statefulsets  verbs:  - get  - list  - watch  - apiGroups:  - extensions  resources:  - daemonsets  - deployments  - replicasets  verbs:  - get  - list  - watch  - apiGroups:  - batch  resources:  - jobs  - cronjobs  verbs:  - get  - list  - watch  - apiGroups:  - autoscaling  resources:  - horizontalpodautoscalers  verbs:  - get  - list  - watch --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata:  name: otel-collector-opentelemetry-collector roleRef:  apiGroup: rbac.authorization.k8s.io  kind: ClusterRole  name: otel-collector-opentelemetry-collector subjects:  - kind: ServiceAccount  name: otel-collector-opentelemetry-collector  namespace: default

Kubernetesオブジェクトレシーバー (Kubernetes Objects Receiver)

デプロイメントパターン利用可能
DaemonSet （エージェント）Yes しかし、データが重複する
Deployment （ゲートウェイ）Yes しかし、2つ以上のレプリカを使用すると、データが重複する
サイドカーNo

Kubernetesオブジェクトレシーバーは、Kubernetes APIサーバからオブジェクトをプルまたはウォッチして収集します。 このレシーバーのもっとも一般的な使用例はKubernetesイベントの監視ですが、あらゆるタイプのKubernetesオブジェクトを収集するために使用できます。 レシーバーはクラスタ全体のテレメトリーを収集するため、すべてのデータを収集するためにはクラスタ全体で1つのインスタンスしか必要ありません。

現在、認証に使用できるのはサービスアカウントのみです。 サービスアカウントはまた、Kubernetes API サーバーからデータを取り込むために適切なパーミッションが必要です（下記参照）。 OpenTelemetryコレクターHelmチャート を使用していて、イベントを取り込みたい場合は、kubernetesEvents preset を使用して開始できます。

プル用に設定されたオブジェクトについては、レシーバーはKubernetes APIを使用して、クラスタ内のすべてのオブジェクトを定期的にリストします。 各オブジェクトは独自のログに変換されます。 監視用に設定されたオブジェクトの場合、レシーバーはKubernetes APIでストリームを作成し、オブジェクトが変更されると更新を受け取ります。

クラスタで実行可能なオブジェクトを確認するには kubectl api-resources を実行します。

kubectl api-resources NAME SHORTNAMES APIVERSION NAMESPACED KIND bindings v1 true Binding componentstatuses cs v1 false ComponentStatus configmaps cm v1 true ConfigMap endpoints ep v1 true Endpoints events ev v1 true Event limitranges limits v1 true LimitRange namespaces ns v1 false Namespace nodes no v1 false Node persistentvolumeclaims pvc v1 true PersistentVolumeClaim persistentvolumes pv v1 false PersistentVolume pods po v1 true Pod podtemplates v1 true PodTemplate replicationcontrollers rc v1 true ReplicationController resourcequotas quota v1 true ResourceQuota secrets v1 true Secret serviceaccounts sa v1 true ServiceAccount services svc v1 true Service mutatingwebhookconfigurations admissionregistration.k8s.io/v1 false MutatingWebhookConfiguration validatingwebhookconfigurations admissionregistration.k8s.io/v1 false ValidatingWebhookConfiguration customresourcedefinitions crd,crds apiextensions.k8s.io/v1 false CustomResourceDefinition apiservices apiregistration.k8s.io/v1 false APIService controllerrevisions apps/v1 true ControllerRevision daemonsets ds apps/v1 true DaemonSet deployments deploy apps/v1 true Deployment replicasets rs apps/v1 true ReplicaSet statefulsets sts apps/v1 true StatefulSet tokenreviews authentication.k8s.io/v1 false TokenReview localsubjectaccessreviews authorization.k8s.io/v1 true LocalSubjectAccessReview selfsubjectaccessreviews authorization.k8s.io/v1 false SelfSubjectAccessReview selfsubjectrulesreviews authorization.k8s.io/v1 false SelfSubjectRulesReview subjectaccessreviews authorization.k8s.io/v1 false SubjectAccessReview horizontalpodautoscalers hpa autoscaling/v2 true HorizontalPodAutoscaler cronjobs cj batch/v1 true CronJob jobs batch/v1 true Job certificatesigningrequests csr certificates.k8s.io/v1 false CertificateSigningRequest leases coordination.k8s.io/v1 true Lease endpointslices discovery.k8s.io/v1 true EndpointSlice events ev events.k8s.io/v1 true Event flowschemas flowcontrol.apiserver.k8s.io/v1beta2 false FlowSchema prioritylevelconfigurations flowcontrol.apiserver.k8s.io/v1beta2 false PriorityLevelConfiguration ingressclasses networking.k8s.io/v1 false IngressClass ingresses ing networking.k8s.io/v1 true Ingress networkpolicies netpol networking.k8s.io/v1 true NetworkPolicy runtimeclasses node.k8s.io/v1 false RuntimeClass poddisruptionbudgets pdb policy/v1 true PodDisruptionBudget clusterrolebindings rbac.authorization.k8s.io/v1 false ClusterRoleBinding clusterroles rbac.authorization.k8s.io/v1 false ClusterRole rolebindings rbac.authorization.k8s.io/v1 true RoleBinding roles rbac.authorization.k8s.io/v1 true Role priorityclasses pc scheduling.k8s.io/v1 false PriorityClass csidrivers storage.k8s.io/v1 false CSIDriver csinodes storage.k8s.io/v1 false CSINode csistoragecapacities storage.k8s.io/v1 true CSIStorageCapacity storageclasses sc storage.k8s.io/v1 false StorageClass volumeattachments storage.k8s.io/v1 false VolumeAttachment

具体的な設定の詳細については、Kubernetesオブジェクトレシーバーのドキュメントを参照してください。

プロセッサーはKubernetes APIを使用するため、正しく動作するには適切なパーミッションが必要です。 サービスアカウントが唯一の認証オプションなので、サービスアカウントに適切なアクセス権を与える必要があります。 収集したいオブジェクトについては、その名前がクラスターロールに追加されていることを確認する必要があります。 たとえば、ポッドを収集したい場合、クラスターロールは次のようになります。

--- apiVersion: v1 kind: ServiceAccount metadata:  name: otel-collector-opentelemetry-collector --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRole metadata:  name: otel-collector-opentelemetry-collector rules:  - apiGroups:  - ''  resources:  - pods  verbs:  - get  - list  - watch --- apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata:  name: otel-collector-opentelemetry-collector roleRef:  apiGroup: rbac.authorization.k8s.io  kind: ClusterRole  name: otel-collector-opentelemetry-collector subjects:  - kind: ServiceAccount  name: otel-collector-opentelemetry-collector  namespace: default

Prometheusレシーバー

デプロイメントパターン利用可能
DaemonSet （エージェント）Yes
Deployment （ゲートウェイ）Yes
サイドカーNo

Prometheusは、KubernetesとKubernetes上で動作するサービスの両方に共通のメトリクスフォーマットです。 Prometheusレシーバーは、これらのメトリクスを収集するためにすぐに利用できる最小限の置き換えです。 Prometheus scrape_config オプション のフルセットをサポートしています。

レシーバーがサポートしていない Prometheus の高度な機能がいくつかあります。 設定 YAML/コードに以下のいずれかが含まれている場合、レシーバーはエラーを返します。

  • alert_config.alertmanagers
  • alert_config.relabel_configs
  • remote_read
  • remote_write
  • rule_files

具体的な設定の詳細については、Prometheusレシーバーのドキュメントを参照してください。

Prometheusのレシーバーはステートフルであり、使用する際に考慮すべき重要な点があります。

  • コレクターの複数のレプリカを実行すると、コレクターはスクレイピングプロセスを自動スケールできません。
  • コレクターの複数のレプリカを同じ設定で実行すると、ターゲットを複数回スクレイピングします。
  • 手動でスクレイピングプロセスをシャーディングしたい場合、ユーザーは各レプリカを異なるスクレイピング構成で構成する必要があります。

Prometheus レシーバーの設定を簡単にするために、OpenTelemetryオペレーターには ターゲットアロケーター というオプションのコンポーネントがあります。 このコンポーネントを使用して、どの Prometheus エンドポイントをスクレイピングすべきかをコレクターに指示できます。

レシーバーの設計については、設計を参照のこと。

ホストメトリクスレシーバー (Host Metrics Receiver)

デプロイメントパターン利用可能
DaemonSet （エージェント）推奨
Deployment （ゲートウェイ）Yes ただし、デプロイされたノードからのみメトリクスを収集する
サイドカーNo

ホストメトリクスレシーバーは、さまざまなスクレイパーを使用してホストからメトリクスを収集します。 Kubeletstatsレシーバーと重複する部分があるので、両方を使うことにした場合は、これらの重複するメトリクスを無効にしたほうがいいかもしれません。

Kubernetes では、レシーバーが正しく動作するためには hostfs ボリュームにアクセスする必要があります。 OpenTelemetryコレクターHelmチャート を使っている場合は、hostMetrics preset を使って開始できます。

使用可能なスクレーパーは以下の通りです。

スクレーパーサポートされているOS説明
cpuAll except macOS1CPU使用率のメトリクス
diskAll except macOS1ディスクI/Oのメトリクス
loadAllCPU負荷のメトリクス
filesystemAllファイルシステム使用量のメトリクス
memoryAllメモリ使用量のメトリクス
networkAllネットワークインターフェースI/OのメトリクスとTCP接続のメトリクス
pagingAllページ空間／スワップ空間の使用量とI/Oのメトリクス
processesLinux, macOSプロセス数のメトリクス
processLinux, macOS, Windowsプロセス毎のCPU、Memory、ディスクI/Oのメトリクス

どのメトリクスが収集されるか、および具体的な構成の詳細については、ホストメトリクスレシーバーのドキュメントを参照してください。

コンポーネントを自分で構成する必要がある場合、コンテナではなくノードのメトリクスを収集したい場合は、必ず hostfs ボリュームをマウントしてください。

--- apiVersion: apps/v1 kind: DaemonSet ... spec:  ...  template:  ...  spec:  ...  containers:  - name: opentelemetry-collector  ...  volumeMounts:  ...  - name: hostfs  mountPath: /hostfs  readOnly: true  mountPropagation: HostToContainer  volumes:  ...  - name: hostfs  hostPath:  path: /  ...

そして volumeMount を使用するようにホストメトリクスレシーバーを設定します。

receivers:  hostmetrics:  root_path: /hostfs  collection_interval: 10s  scrapers:  cpu:  load:  memory:  disk:  filesystem:  network:

レシーバーをコンテナ内で使用する方法の詳細については、コンテナ内からホストメトリクスを収集する（Linuxのみ）を参照してください。

  1. Collector SIGがリリースしたイメージのデフォルトであるcgoなしでコンパイルした場合、macOSではサポートされません。 ↩︎ ↩︎


最終更新 August 26, 2025: [ja] docs(i18n): fix drifted files of content/ja/docs/platforms/ (#7612) (67bbf476)