文档 Grafana Alloy 参考 组件 otelcol otelcol.processor.k8sattributes

otelcol.processor.k8sattributes

otelcol.processor.k8sattributes 接收来自其他 otelcol 组件的遥测数据，并将 Kubernetes 元数据添加到 spans、日志或指标的资源属性中。

您可以指定多个 otelcol.processor.k8sattributes 组件，只需给它们不同的标签。

用法

alloy 复制

otelcol.processor.k8sattributes "LABEL" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

参数

支持以下参数

auth_type 支持的值包括

• none: 无需认证。
• serviceAccount: 使用 Kubernetes 为每个 Pod 自动配置的内置服务账户。
• kubeConfig: 使用本地凭据，例如 kubectl 使用的凭据。
• tls: 使用客户端 TLS 认证。

将 passthrough 设置为 true 启用 otelcol.processor.k8sattributes 的“透传模式”

• 只会添加 k8s.pod.ip 资源属性。
• 不会添加其他元数据。
• 不会访问 Kubernetes API。
• 为了正确检测 Pod IP，Alloy 必须直接从服务接收 spans。
• 当将 Alloy 配置为 Kubernetes Deployment 时，passthrough 设置非常有用。以 Deployment 形式运行的 Alloy 无法在没有众所周知的 IP 属性的情况下检测到生成遥测数据的 Pod 的 IP 地址。如果 Deployment Alloy 从作为 DaemonSet 部署的 Alloys 接收遥测数据，则可能缺少其中一些属性。作为一种变通方法，您可以配置 DaemonSet Alloys 的 passthrough 设置为 true。

默认情况下，otelcol.processor.k8sattributes 在启动后立即就绪，即使尚未获取任何元数据。如果在元数据同步之前将遥测数据发送到此处理器，则不会有元数据可用于丰富遥测数据。

要等待元数据同步后 otelcol.processor.k8sattributes 才就绪，请将 wait_for_metadata 选项设置为 true。然后，处理器将一直等到元数据完全同步后才就绪。因此，Alloy 的启动将被阻塞。如果在达到 metadata_sync_timeout 时长之前无法同步元数据，otelcol.processor.k8sattributes 将变为不健康并启动失败。

如果 otelcol.processor.k8sattributes 不健康，其他 Alloy 组件仍然可以启动。但是，它们可能无法向 otelcol.processor.k8sattributes 发送遥测数据。

块

otelcol.processor.k8sattributes 的定义中支持以下块

符号 > 表示更深的嵌套层级。例如，extract > annotation 指的是在 extract 块内部定义的 annotation 块。

extract 块

extract 块配置要从 Pod 中提取哪些元数据、注释和标签。

支持以下属性

当前支持的 metadata 键包括

• k8s.pod.name
• k8s.pod.uid
• k8s.deployment.name
• k8s.node.name
• k8s.namespace.name
• k8s.pod.start_time
• k8s.replicaset.name
• k8s.replicaset.uid
• k8s.daemonset.name
• k8s.daemonset.uid
• k8s.job.name
• k8s.job.uid
• k8s.cronjob.name
• k8s.statefulset.name
• k8s.statefulset.uid
• k8s.container.name
• container.image.name
• container.image.tag
• container.id

默认情况下，如果未指定 metadata，则提取以下字段并将其作为资源属性添加到 spans、指标和日志中

• k8s.pod.name
• k8s.pod.uid
• k8s.pod.start_time
• k8s.namespace.name
• k8s.node.name
• k8s.deployment.name（如果 Pod 由一个 deployment 控制）
• k8s.container.name（需要设置额外的属性：container.id）
• container.image.name（需要设置以下额外属性之一：container.id 或 k8s.container.name）
• container.image.tag（需要设置以下额外属性之一：container.id 或 k8s.container.name）

annotation 块

annotation 块配置如何提取 Kubernetes 注释。

支持以下属性

当您未指定 tag_name 时，将使用默认标签名称，格式为

• k8s.pod.annotations.<annotation key>
• k8s.pod.labels.<label key>

例如，如果未指定 tag_name，且键为 git_sha，则属性名称将是 k8s.pod.annotations.git_sha。

您可以设置 key 属性或 key_regex 属性，但不能同时设置两者。当存在 key_regex 时，tag_name 支持对命名捕获和位置捕获的反向引用。

例如，假设您的 Pod spec 包含以下标签

• app.kubernetes.io/component: mysql
• app.kubernetes.io/version: 5.7.21

如果您希望为所有前缀为 app.kubernetes.io/ 的标签添加标签并去除前缀，则可以指定以下提取规则

alloy 复制

extract {
  label {
    from = "pod"
    key_regex = "kubernetes.io/(.*)"
    tag_name  = "$1"
  }
}

这些规则将 component 和 version 标签添加到 spans 或指标中。

您可以将 from 属性设置为 "pod" 或 "namespace"。

label 块

label 块配置如何提取 Kubernetes 标签。

支持以下属性

当您未指定 tag_name 时，将使用默认标签名称，格式为

• k8s.pod.annotations.<annotation key>
• k8s.pod.labels.<label key>

例如，如果未指定 tag_name，且键为 git_sha，则属性名称将是 k8s.pod.annotations.git_sha。

您可以设置 key 属性或 key_regex 属性，但不能同时设置两者。当存在 key_regex 时，tag_name 支持对命名捕获和位置捕获的反向引用。

例如，假设您的 Pod spec 包含以下标签

• app.kubernetes.io/component: mysql
• app.kubernetes.io/version: 5.7.21

如果您希望为所有前缀为 app.kubernetes.io/ 的标签添加标签并去除前缀，则可以指定以下提取规则

alloy 复制

extract {
  label {
    from = "pod"
    key_regex = "kubernetes.io/(.*)"
    tag_name  = "$1"
  }
}

这些规则将 component 和 version 标签添加到 spans 或指标中。

您可以将 from 属性设置为 "pod" 或 "namespace"。

filter 块

filter 块配置从哪些节点获取数据以及获取哪些字段和标签。

支持以下属性

如果指定了 node，则不在指定节点上运行的任何 Pod 都将被 otelcol.processor.k8sattributes 忽略。

field 块

field 块允许您按通用的 Kubernetes 字段过滤 Pod。

支持以下属性

对于 op，允许以下值

• equals: 字段值必须等于提供的值。
• not-equals: 字段值必须不等于提供的值。
• exists: 字段值必须存在。仅适用于 annotation 字段。
• does-not-exist: 字段值必须不存在。仅适用于 annotation 字段。

label 块

label 块允许您按通用的 Kubernetes 标签过滤 Pod。

支持以下属性

对于 op，允许以下值

• equals: 字段值必须等于提供的值。
• not-equals: 字段值必须不等于提供的值。
• exists: 字段值必须存在。仅适用于 annotation 字段。
• does-not-exist: 字段值必须不存在。仅适用于 annotation 字段。

pod_association 块

pod_association 块配置如何将日志/追踪/指标与 Pod 关联的规则。

pod_association 块不支持任何参数，完全通过子块进行配置。

pod_association 块可以重复多次，以配置额外的规则。

示例

alloy 复制

pod_association {
    source {
        from = "resource_attribute"
        name = "k8s.pod.ip"
    }
}

pod_association {
    source {
        from = "resource_attribute"
        name = "k8s.pod.uid"
    }
    source {
        from = "connection"
    }
}

source 块

source 块配置 Pod 关联规则。k8sattributes 处理器使用此规则来确定与遥测信号关联的 Pod。

当一个 pod_association 块内指定多个 source 块时，只有当所有 source 块都匹配时，Pod 才会与遥测信号关联。

支持以下属性

exclude 块

exclude 块配置要从处理器中排除的 Pod。

pod 块

pod 块配置要从处理器中排除的 Pod。

支持以下属性

output 块

output 块配置一组组件，用于转发生成的遥测数据。

支持以下参数

您必须指定 output 块，但其所有参数都是可选的。默认情况下，遥测数据会被丢弃。相应地配置 metrics、logs 和 traces 参数以将遥测数据发送到其他组件。

debug_metrics 块

debug_metrics 块配置此组件用于监控其状态的指标。

支持以下参数

disable_high_cardinality_metrics 是 Grafana Alloy 中与 OpenTelemetry Collector 中的 telemetry.disableHighCardinalityMetrics 功能门等效的设置。它移除可能导致高基数指标的属性。例如，HTTP 和 gRPC 连接指标中包含 IP 地址和端口号的属性会被移除。

导出字段

导出以下字段，可供其他组件引用

input 接受任何遥测信号（指标、日志或 traces）的 otelcol.Consumer 数据。

组件健康状态

仅当配置无效时，otelcol.processor.k8sattributes 才会被报告为不健康。

调试信息

otelcol.processor.k8sattributes 不公开任何组件特定的调试信息。

示例

基本用法

在大多数情况下，这足以开始使用。它会将这些资源属性添加到所有日志、指标和 traces 中

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

示例

alloy 复制

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.k8sattributes.default.input]
    logs    = [otelcol.processor.k8sattributes.default.input]
    traces  = [otelcol.processor.k8sattributes.default.input]
  }
}

otelcol.processor.k8sattributes "default" {
  output {
    metrics = [otelcol.exporter.otlp.default.input]
    logs    = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = sys.env("OTLP_ENDPOINT")
  }
}

添加额外的元数据和标签

alloy 复制

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.k8sattributes.default.input]
    logs    = [otelcol.processor.k8sattributes.default.input]
    traces  = [otelcol.processor.k8sattributes.default.input]
  }
}

otelcol.processor.k8sattributes "default" {
  extract {
    label {
      from      = "pod"
      key_regex = "(.*)/(.*)"
      tag_name  = "$1.$2"
    }

    metadata = [
      "k8s.namespace.name",
      "k8s.deployment.name",
      "k8s.statefulset.name",
      "k8s.daemonset.name",
      "k8s.cronjob.name",
      "k8s.job.name",
      "k8s.node.name",
      "k8s.pod.name",
      "k8s.pod.uid",
      "k8s.pod.start_time",
    ]
  }

  output {
    metrics = [otelcol.exporter.otlp.default.input]
    logs    = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

otelcol.exporter.otlp "default" {
  client {
    endpoint = sys.env("OTLP_ENDPOINT")
  }
}

将 Kubernetes 元数据添加到 Prometheus 指标

otelcol.processor.k8sattributes 以资源属性的形式将元数据添加到指标信号中。要将元数据显示为 Prometheus 指标的标签，必须将 OTLP 属性从资源属性转换为数据点属性。一种方法是使用 otelcol.processor.transform 组件。

alloy 复制

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.k8sattributes.default.input]
  }
}

otelcol.processor.k8sattributes "default" {
  extract {
    label {
      from = "pod"
    }

    metadata = [
      "k8s.namespace.name",
      "k8s.pod.name",
    ]
  }

  output {
    metrics = [otelcol.processor.transform.add_kube_attrs.input]
  }
}

otelcol.processor.transform "add_kube_attrs" {
  error_mode = "ignore"

  metric_statements {
    context = "datapoint"
    statements = [
      "set(attributes[\"k8s.pod.name\"], resource.attributes[\"k8s.pod.name\"])",
      "set(attributes[\"k8s.namespace.name\"], resource.attributes[\"k8s.namespace.name\"])",
    ]
  }

  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

兼容组件

otelcol.processor.k8sattributes 可以接受来自以下组件的参数

• 导出 OpenTelemetry otelcol.Consumer 的组件

otelcol.processor.k8sattributes 导出的字段可被以下组件消费

• 消费 OpenTelemetry otelcol.Consumer 的组件