Kubernetes 的重要组件

OpenTelemetry Collector 支持多种不同的接收器和处理器，以便于监控 Kubernetes。本节介绍了收集 Kubernetes 数据并增强数据的最重要的组件。

本页涵盖的组件有：

对于应用程序的追踪、指标或日志数据，我们推荐使用 OTLP 接收器，但任何适合您数据的接收器都可以使用。

Kubernetes 属性处理器

部署模式 是否可用
DaemonSet（Agent） 是
Deployment（网关） 是
Sidecar 否

Kubernetes 属性处理器会自动发现 Kubernetes Pod，提取其元数据，并将提取的元数据作为资源属性添加到 span、指标和日志中。

对于在 Kubernetes 中运行的收集器而言，Kubernetes 属性处理器是最重要的组件之一。任何接收应用程序数据的收集器都应该使用它。 由于它为遥测数据添加了 Kubernetes 上下文，Kubernetes 属性处理器允许您将应用程序的追踪、指标和日志信号与 Kubernetes 的指标和追踪等遥测数据进行关联。

Kubernetes 属性处理器使用 Kubernetes API 发现在集群中运行的所有 Pod，并记录它们的 IP 地址、Pod UID 和有趣的元数据。默认情况下，通过处理器的数据与 Pod 关联是通过传入请求的 IP 地址实现的，但可以配置不同的规则。由于处理器使用了 Kubernetes API，它需要特定的权限（请参见下面的示例）。如果您使用 OpenTelemetry Collector Helm Chart，您可以使用kubernetesAttributes预设配置来开始使用它。

默认会添加以下属性：

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

Kubernetes 属性处理器还可以使用您在 Pod 和命名空间中添加的 Kubernetes 标签和注释设置自定义资源属性，以用于追踪、指标和日志。

k8sattributes:
  auth_type: 'serviceAccount'
  extract:
    metadata: # 提取自 Pod 的元数据
      - k8s.namespace.name
      - k8s.pod.name
      - k8s.pod.start_time
      - k8s.pod.uid
      - k8s.deployment.name
      - k8s.node.name
    annotations:
      # 提取具有键 `annotation-one` 的 Pod 注释的值，并将其作为具有键 `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` 的 Pod 标签的值，并将其作为具有键 `l2` 的资源属性插入
      - tag_name: l2
        key: label2
        regex: field=(?P<value>.+)
        from: pod
  pod_association: # 如何将数据关联到 Pod（顺序很重要）
    - sources: # 首先尝试使用资源属性 k8s.pod.ip 的值
        - from: resource_attribute
          name: k8s.pod.ip
    - sources: # 然后尝试使用资源属性 k8s.pod.uid 的值
        - from: resource_attribute
          name: k8s.pod.uid
    - sources: # 如果前两者都不可用，使用请求的连接来获取 Pod 的 IP 地址。
        - from: connection

对于使用 Kubernetes DaemonSet（Agent）或 Kubernetes Deployment（网关）部署时的特殊配置选项，请参见部署方案。

有关 Kubernetes 属性处理器的配置详细信息，请参见 Kubernetes 属性处理器。

由于处理器使用了 Kubernetes API，它需要正确的权限才能正常工作。对于大多数用例，您应该为运行 Collector 的服务帐号通过 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

Kubelet 统计接收器

部署模式 是否可用
DaemonSet（Agent） 首选
Deployment（网关） 是，但仅会从部署所在节点收集指标
Sidecar 否

每个 Kubernetes 节点运行一个 kubelet，其中包括一个 API 服务器。Kubernetes 接收器通过 API 服务器连接到 kubelet，以收集有关节点和运行在节点上的工作负载的指标。

有不同的身份验证方法，但通常使用服务账户。该服务账户还需要适当的权限从 kubelet 中获取数据（请参见下面的示例）。如果您使用 OpenTelemetry Collector Helm Chart，您可以使用kubeletMetrics 预设配置来开始使用它。

默认情况下，将为 Pod 和节点收集指标，但您可以配置接收器以收集容器和卷的指标。接收器还允许配置指标的收集频率：

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

有关收集的具体指标，请参见默认指标。有关特定配置详细信息，请参见Kubelet 统计接收器。

由于处理器使用了 Kubernetes API，它需要正确的权限才能正常工作。对于大多数用例，您应该为运行 Collector 的服务帐号通过 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

文件日志接收器

部署模式 是否可用
DaemonSet（Agent） 首选
Deployment（网关） 是，但仅会从部署所在节点收集日志
Sidecar 是，但这被视为高级配置

文件日志接收器从文件中监视和解析日志。尽管它不是特定于 Kubernetes 的接收器，但它仍然是从 Kubernetes 收集任何日志的事实标准解决方案。

文件日志接收器由连接在一起的操作符组成，用于处理日志。每个操作符都执行一个简单的功能，例如解析时间戳或 JSON。配置文件日志接收器并不简单。如果您使用 OpenTelemetry Collector Helm Chart，您可以使用logsCollection预设配置来开始使用它。

由于 Kubernetes 日志通常符合一组标准格式，因此 Kubernetes 的典型文件日志接收器配置如下所示：

filelog:
  include:
    - /var/log/pods/*/*/*.log
  exclude:
    # 排除所有命名为 otlp-collector 的容器的日志
    - /var/log/pods/*/otel-collector/*.log
  start_at: beginning
  include_file_path: true
  include_file_name: false
  operators:
    # 查找 Kubernetes 使用的格式
    - type: router
      id: get-format
      routes:
        - output: parser-docker
          expr: 'body matches "^\\{"'
        - output: parser-crio
          expr: 'body matches "^[^ Z]+ "'
        - output: parser-containerd
          expr: 'body matches "^[^ Z]+Z"'
    # 解析 CRI-O 格式
    - type: regex_parser
      id: parser-crio
      regex:
        '^(?P<time>[^ Z]+) (?P<stream>stdout|stderr) (?P<logtag>[^ ]*)
        ?(?P<log>.*)$'
      output: extract_metadata_from_filepath
      timestamp:
        parse_from: attributes.time
        layout_type: gotime
        layout: '2006-01-02T15:04:05.999999999Z07:00'
    # 解析 CRI-Containerd 格式
    - type: regex_parser
      id: parser-containerd
      regex:
        '^(?P<time>[^ ^Z]+Z) (?P<stream>stdout|stderr) (?P<logtag>[^ ]*)
        ?(?P<log>.*)$'
      output: extract_metadata_from_filepath
      timestamp:
        parse_from: attributes.time
        layout: '%Y-%m-%dT%H:%M:%S.%LZ'
    # 解析 Docker 格式
    - type: json_parser
      id: parser-docker
      output: extract_metadata_from_filepath
      timestamp:
        parse_from: attributes.time
        layout: '%Y-%m-%dT%H:%M:%S.%LZ'
    - type: move
      from: attributes.log
      to: body
    # 从文件路径中提取元数据
    - type: regex_parser
      id: extract_metadata_from_filepath
      regex: '^.*\/(?P<namespace>[^_]+)_(?P<pod_name>[^_]+)_(?P<uid>[a-f0-9\-]{36})\/(?P<container_name>[^\._]+)\/(?P<restart_count>\d+)\.log$'
      parse_from: attributes["log.file.path"]
      cache:
        size: 128 # 默认每个节点的最大 Pod 数量为 110
    # 重命名属性
    - type: move
      from: attributes.stream
      to: attributes["log.iostream"]
    - type: move
      from: attributes.container_name
      to: resource["k8s.container.name"]
    - type: move
      from: attributes.namespace
      to: resource["k8s.namespace.name"]
    - type: move
      from: attributes.pod_name
      to: resource["k8s.pod.name"]
    - type: move
      from: attributes.restart_count
      to: resource["k8s.container.restart_count"]
    - type: move
      from: attributes.uid
      to: resource["k8s.pod.uid"]

有关文件日志接收器的配置详细信息，请参见 文件日志接收器。

除了文件日志接收器配置外，Kubernetes 中的 OpenTelemetry Collector 安装还需要访问其要收集的日志。通常，这意味着要将一些卷和卷挂载添加到收集器清单中：

---
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:
        ...
        # 通常，收集器将需要访问 Pod 日志和容器日志
        - name: varlogpods
          hostPath:
            path: /var/log/pods
        - name: varlibdockercontainers
          hostPath:
            path: /var/lib/docker/containers
        ...

Kubernetes集群接收器

部署模式 可用
DaemonSet（代理） 可用，但会导致重复数据
Deployment（网关） 可用，但多个副本会导致重复数据
Sidecar 不可用

Kubernetes集群接收器使用Kubernetes API服务器收集有关整个集群的指标和实体事件。使用此接收器回答有关Pod阶段、节点条件和其他全局集群的问题。由于接收器收集集群整体的遥测数据，因此在整个集群中只需要一个接收器实例即可收集所有数据。

有不同的身份验证方法，但通常使用服务帐户。服务帐户还需要适当的权限来从Kubernetes API服务器获取数据（见下文）。如果您使用的是OpenTelemetry Collector Helm图表，则可以使用clusterMetrics预设来开始使用。

对于节点条件，默认情况下，接收器仅收集Ready，但可以配置为收集更多条件。接收器还可以配置为报告一组可分配资源，例如cpu和memory：

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

有关所收集的指标的更多信息，请参见默认指标。有关配置详细信息，请参见Kubernetes集群接收器。

由于处理器使用了Kubernetes API，因此需要正确的权限才能正常工作。对于大多数用例，您应该为运行Collector的服务帐户提供以下权限，通过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对象接收器

部署模式 可用
DaemonSet（代理） 可用，但会导致重复数据
Deployment（网关） 可用，但多个副本会导致重复数据
Sidecar 不可用

Kubernetes对象接收器通过拉取或监视方式从Kubernetes API服务器收集对象。此接收器最常见的用例是监视Kubernetes事件，但也可用于收集任何类型的Kubernetes对象。由于接收器收集集群整体的遥测数据，因此在整个集群中只需要一个接收器实例即可收集所有数据。

目前，只能使用服务帐户进行身份验证。服务帐户还需要适当的权限从Kubernetes API服务器获取数据（见下文）。如果您使用的是OpenTelemetry Collector Helm图表，并且希望检索事件，可以使用kubernetesEvents预设来开始使用。

对于配置为拉取的对象，接收器将使用Kubernetes API定期列出集群中的所有对象。每个对象将转换为其自己的日志。对于配置为监视的对象，接收器将创建一个与Kubernetes API的流，并收到对象更改的更新。

要查看可在集群中收集的对象，请在集群中运行kubectl api-resources命令：

kubeclt 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，所以它需要正确的权限才能正常工作。由于服务帐户是唯一的身份验证选项，您必须为服务帐户授予适当的访问权限。对于您想要收集的任何对象，您需要确保将其名称添加到集群角色中。例如，如果您想要收集Pod，则集群角色如下所示：

---
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（代理） 可用
Deployment（网关） 可用
Sidecar 不可用

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 Operator包括了一个可选的组件，称为Target Allocator。可以使用此组件告诉收集器应该收集哪些Prometheus端点。

有关接收器设计的更多信息，请参见设计。

主机指标接收器

部署模式 可用
DaemonSet（代理） 首选
Deployment（网关） 可用，但仅从部署所在的节点收集指标
Sidecar 不可用

主机指标接收器使用各种抓取器从主机收集指标。与Kubeletstats接收器存在一些重叠，因此如果决定同时使用两者，可以考虑禁用这些重复的指标。

在Kubernetes中，接收器需要访问hostfs卷以正常工作。如果您使用的是OpenTelemetry Collector Helm图表，则可以使用hostMetrics预设来开始使用。

可用的抓取器如下：

抓取器 支持的操作系统 描述
cpu 除Mac以外的所有操作系统1 CPU利用率指标
disk 除Mac以外的所有操作系统1 磁盘I/O指标
load 所有操作系统 CPU负载指标
filesystem 所有操作系统 文件系统利用率指标
memory 所有操作系统 内存利用率指标
network 所有操作系统 网络接口I/O指标和TCP连接指标
paging 所有操作系统 分页/交换空间利用率和I/O指标
processes Linux，Mac 进程计数指标
process Linux，Windows，Mac 每个进程的CPU、内存和磁盘I/O指标

Mac上默认情况下不支持cgo编译，因此不支持此功能。

有关收集的指标以及其他特定配置详细信息，请参见主机指标接收器。

如果需要自己配置组件，请确保挂载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.  ↩︎ ↩︎
最后修改 December 13, 2023: improve glossary translation (46f8201b)