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

otelcol.processor.k8sattributes

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

您可以通过为多个 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 必须直接从服务接收 span。
• 当将 Alloy 配置为 Kubernetes Deployment 时，passthrough 设置非常有用。作为 Deployment 运行的 Alloy 无法检测生成遥测数据的 pod 的 IP 地址，而没有任何众所周知的 IP 属性。如果 Deployment Alloy 从作为 DaemonSet 部署的 Alloy 接收遥测数据，则可能会缺少某些属性。作为一种解决方法，您可以将 DaemonSet Alloy 配置为将 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，则会提取以下字段并作为资源属性添加到 span、指标和日志中

• 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 规范包含以下标签

• 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 标签添加到 span 或指标中。

您可以将 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 规范包含以下标签

• 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 标签添加到 span 或指标中。

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

filter 块

filter 块配置要从中获取数据的节点以及要获取的字段和标签。

支持以下属性

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

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 地址和端口号的属性将被删除。

level 是 Alloy 等效于 OpenTelemetry Collector 中的 telemetry.metrics.level 功能门。可能的值为 "none"、"basic"、"normal" 和 "detailed"。

导出的字段

导出以下字段，并且可以被其他组件引用

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

组件健康状况

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

调试信息

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

示例

基本用法

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

• 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 的组件