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

Otelcol处理器.k8sattributes

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

您可以通过提供不同的标签来指定多个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的“passthrough模式”

• 仅添加一个k8s.pod.ip资源属性。
• 不会添加其他元数据。
• 不会访问Kubernetes API。
• 为了正确检测Pod IP，Alloy必须从服务直接接收跨度。
• passthrough设置在将Alloy配置为Kubernetes部署时很有用。作为部署运行的Alloy在没有任何知名IP属性的情况下无法检测生成遥测数据的Pod的IP地址。如果部署Alloy从作为DaemonSet部署的Alloy接收遥测数据，那么有些属性可能缺失。作为解决方案，您可以配置passthrough设置为true的DaemonSet Alloy。

阻挡：

在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，则以下字段将被提取并添加到跨度、指标和日志中作为资源属性

• k8s.pod.name
• k8s.pod_uid
• k8s.pod.start_time
• k8s.namespace.name
• k8s.node.name
• k8s.deployment.name （如果 Pod 受部署控制）
• 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 标签添加到跨度或指标。

您可以将 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 标签添加到跨度或指标。

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

filter 块

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

支持以下属性

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

field 块

《字段》块允许您通过通用的Kubernetes字段对Pod进行筛选。

支持以下属性

对于操作，允许以下值：

• 等于：字段值必须等于提供的值。
• 不等于：字段值必须不等于提供的值。
• 存在：字段值必须存在。仅适用于annotation字段。
• 不存在：字段值必须不存在。仅适用于annotation字段。

label 块

label块允许您通过通用的Kubernetes标签对Pod进行筛选。

支持以下属性

对于操作，允许以下值：

• 等于：字段值必须等于提供的值。
• 不等于：字段值必须不等于提供的值。
• 存在：字段值必须存在。仅适用于annotation字段。
• 不存在：字段值必须不存在。仅适用于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地址和端口号的属性。

级别是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 = 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 = 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的组件