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

otelcol 处理器资源检测

otelcol.processor.resourcedetection 从主机中检测符合 OpenTelemetry 资源语义约定 格式的资源信息，并将此信息附加或覆盖遥测数据中的资源值。

您可以通过提供不同的标签来指定多个 otelcol.processor.resourcedetection 组件。

用法

合金 复制

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

参数

otelcol.processor.resourcedetection 支持以下参数

detectors 可能包含以下值

• env
• ec2
• ecs
• eks
• elasticbeanstalk
• lambda
• azure
• aks
• consul
• docker
• gcp
• heroku
• system
• openshift
• kubernetes_node

env 是唯一不是通过块配置的检测器。 env 检测器从 OTEL_RESOURCE_ATTRIBUTES 环境变量中读取资源信息。此变量必须采用以下格式 <key1>=<value1>,<key2>=<value2>,...，其详细信息目前正在 OpenTelemetry 规范中确认。

如果需要除 env 以外的检测器，可以使用相关块进行自定义。例如，可以使用 ec2 块自定义 ec2 检测器。如果您省略 ec2 块，则使用 ec2 块文档中指定的默认值。

如果有多个检测器插入相同的属性名称，则首先插入的检测器获胜。例如，如果您有 detectors = ["eks", "ec2"]，则 cloud.platform 将为 aws_eks 而不是 ec2。

对于 AWS，以下顺序是推荐的

1. lambda
2. elasticbeanstalk
3. eks
4. ecs
5. ec2

块

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

output

output 块配置了一组组件，以将结果遥测数据转发到。

支持以下参数

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

debug_metrics 块

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

支持以下参数

disable_high_cardinality_metrics 是 Grafana Alloy 对 OpenTelemetry Collector 中 telemetry.disableHighCardinalityMetrics 功能门的等效项。它删除可能导致高基数指标的属性。例如，从关于 HTTP 和 gRPC 连接的指标中删除包含 IP 地址和端口号的属性。

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

ec2

ec2 块使用 EC2 实例元数据 API 和 AWS SDK for Go 从 EC2 实例读取资源信息。

ec2 块支持以下属性

如果您在 EC2 实例上使用代理服务器，则非常重要，您需要根据 AWS CLI 用户指南 中所述免除对实例元数据的请求。未能这样做可能会导致代理或丢失实例数据。

如果实例是 AWS ParallelCluster 的一部分，并且检测器无法连接到元数据服务器，请检查 iptable 并确保链 PARALLELCLUSTER_IMDS 包含允许 Alloy 用户访问 169.254.169.254/32 的规则。

tags 可以用来收集 Alloy 在其上运行的 EC2 实例的标签。要获取 EC2 标签，分配给 EC2 实例的 IAM 角色必须有一个包含 ec2:DescribeTags 权限的策略。

ec2 块支持以下块

ec2 > resource_attributes

resource_attributes 块支持以下块

ecs

ecs 块通过查询 任务元数据端点 (TMDE) 来记录当前 ECS 任务的信息。仅支持 TMDE V4 和 V3。

ecs 块支持以下块

ecs > resource_attributes

resource_attributes 块支持以下块

eks

eks 块为 Amazon EKS 添加资源属性。

eks 块支持以下块

eks > resource_attributes

resource_attributes 块支持以下块

示例值

• cloud.provider: "aws"
• cloud.platform: "aws_eks"

elasticbeanstalk

elasticbeanstalk 块读取所有带有 X-Ray 启用 的 Beanstalk 实例上的 AWS X-Ray 配置文件。

《elasticbeanstalk》块支持以下块：

elasticbeanstalk > resource_attributes

resource_attributes 块支持以下块

示例值

• cloud.provider: "aws"
• cloud.platform: "aws_elastic_beanstalk"

lambda

《lambda》块使用 AWS Lambda 的 运行时环境变量 来检索各种资源属性。

《lambda》块支持以下块：

lambda > resource_attributes

resource_attributes 块支持以下块

云语义约定:

• cloud.provider: "aws"
• cloud.platform: "aws_lambda"
• cloud.region: $AWS_REGION

函数即服务语义约定 和 AWS Lambda 语义约定

• faas.name: $AWS_LAMBDA_FUNCTION_NAME
• faas.version: $AWS_LAMBDA_FUNCTION_VERSION
• faas.instance: $AWS_LAMBDA_LOG_STREAM_NAME
• faas.max_memory: $AWS_LAMBDA_FUNCTION_MEMORY_SIZE

AWS 日志语义约定:

• aws.log.group.names: $AWS_LAMBDA_LOG_GROUP_NAME
• aws.log.stream.names: $AWS_LAMBDA_LOG_STREAM_NAME

azure

《azure》块查询 Azure 实例元数据服务 来检索各种资源属性。

《azure》块支持以下块：

《azure》块支持以下属性：

azure > resource_attributes

resource_attributes 块支持以下块

示例值

• cloud.provider: "azure"
• cloud.platform: "azure_vm"

aks

《aks》块添加与 Azure AKS 相关的资源属性。

《aks》块支持以下块：

aks > resource_attributes

resource_attributes 块支持以下块

示例值

• cloud.provider: "azure"
• cloud.platform: "azure_vm"

Azure AKS 集群名称是从 Azure 实例元数据服务（IMDS）的基础设施资源组字段派生的。此字段包含资源组和集群的名称，由下划线分隔。例如：MC_<资源组>_<集群名称>_<位置>。

示例

• 资源组：my-resource-group
• 集群名称：my-cluster
• 位置：eastus
• 生成的名称：MC_my-resource-group_my-cluster_eastus

如果集群名称不包含下划线且未使用自定义基础设施资源组名称，则会检测到集群名称。

如果无法执行准确解析，则返回基础设施资源组值。此值可用于唯一标识集群，因为 Azure 不允许用户创建具有相同基础设施资源组名称的多个集群。

consul

《consul》块查询 Consul 代理并读取其配置端点以检索资源属性的值。

《consul》块支持以下属性：

token 仅在启用 Consul 的 ACL 系统 时才需要。

consul 块支持以下块

consul > resource_attributes

resource_attributes 块支持以下块

docker

docker 块通过查询 Docker 守护进程从主机机器检索各种资源属性。

您需要挂载 Docker 套接字（Linux 上的 /var/run/docker.sock）以联系 Docker 守护进程。Docker 检测在 MacOS 上不起作用。

docker 块支持以下块

docker > resource_attributes

resource_attributes 块支持以下块

gcp

gcp 块通过使用 Go 的 Google Cloud 客户端库 识别资源属性，它从 GCP 元数据服务器 读取资源信息。检测器还使用环境变量来识别应用程序运行在哪个 GCP 平台上，并为该平台分配适当的资源属性。

无论 Alloy 运行在哪个 GCP 平台上，都使用 gcp 检测器。

gcp 块支持以下块

gcp > resource_attributes

resource_attributes 块支持以下块

Google Compute Engine (GCE) 元数据

• cloud.provider: "gcp"
• cloud.platform: "gcp_compute_engine"
• cloud.account.id: 项目 ID
• cloud.region: 例如 "us-central1"
• cloud.availability_zone: 例如 "us-central1-c"
• host.id: 实例 ID
• host.name: 实例名称
• host.type: 机器类型
• (可选) gcp.gce.instance.hostname
• (可选) gcp.gce.instance.name

Google Kubernetes Engine (GKE) 元数据

• cloud.provider: "gcp"
• cloud.platform: "gcp_kubernetes_engine"
• cloud.account.id: 项目 ID
• cloud.region: 仅适用于区域 GKE 集群；例如 "us-central1"
• cloud.availability_zone: 仅适用于区域 GKE 集群；例如 "us-central1-c"
• k8s.cluster.name
• host.id: 实例 ID
• host.name: 实例名称；仅当禁用工作负载身份时

一个已知问题是当启用 GKE 工作负载身份时发生。GCE 元数据端点将不可用，并且 GKE 资源检测器将无法确定 host.name。如果发生这种情况，您可以从以下资源之一设置 host.name

• 通过 向下 API 使用 env 检测器获取 node.name。
• 从 Kubernetes API（使用 k8s.io/client-go）获取 Kubernetes 节点名。

Google Cloud Run 服务元数据

• cloud.provider: "gcp"
• cloud.platform: "gcp_cloud_run"
• cloud.account.id: 项目 ID
• cloud.region: 例如 "us-central1"
• faas.id: 实例 ID
• faas.name: 服务名称
• faas.version: 服务版本

Cloud Run 作业元数据

• cloud.provider: "gcp"
• cloud.platform: "gcp_cloud_run"
• cloud.account.id: 项目 ID
• cloud.region: 例如 "us-central1"
• faas.id: 实例 ID
• faas.name: 服务名称
• gcp.cloud_run.job.execution: 例如 "my-service-ajg89"
• gcp.cloud_run.job.task_index: 例如 "0"

Google Cloud Functions 元数据

• cloud.provider: "gcp"
• cloud.platform: "gcp_cloud_functions"
• cloud.account.id: 项目 ID
• cloud.region: 例如 "us-central1"
• faas.id: 实例 ID
• faas.name: 函数名称
• faas.version: 函数版本

Google App Engine 元数据

• cloud.provider: "gcp"
• cloud.platform: "gcp_app_engine"
• cloud.account.id: 项目 ID
• cloud.region: 例如 "us-central1"
• cloud.availability_zone: 例如 "us-central1-c"
• faas.id: 实例 ID
• faas.name: 服务名称
• faas.version: 服务版本

heroku

《heroku》块添加了从 Heroku 动态进程元数据 中派生出的资源属性。

《heroku》块支持以下块

heroku > resource_attributes

resource_attributes 块支持以下块

当 Heroku 动态进程元数据 激活时，Heroku 应用程序通过环境变量发布信息。我们将这些环境变量映射到以下资源属性

有关更多信息，请参阅 Heroku 云提供商文档，该文档位于 OpenTelemetry 规范语义约定 下。

system

《system》块查询主机以检索各种资源属性。

《system》块支持以下属性

《hostname_sources》的有效选项包括

• "dns"：使用多个来源获取完全限定的域名。首先，在本地计算机的 hosts 文件中查找主机名。如果失败，则查找 CNAME。最后，如果失败，则执行反向 DNS 查询。注意：此主机名来源可能在 Windows 上产生不可靠的结果。为了生成 FQDN，Windows 主机可能使用以下提到的“lookup”主机名来源会更好。
• "os"：提供由本地计算机的内核提供的主机名。
• "cname"：提供由 Go 标准库中的 net.LookupCNAME 提供的规范名称。注意：此主机名来源可能在 Windows 上产生不可靠的结果。
• "lookup"：对当前主机的 IP 地址执行反向 DNS 查询。

在从来源获取主机名时发生错误的情况下，将考虑 hostname_sources 列表中的下一个来源。

《system》块支持以下块

system > resource_attributes

resource_attributes 块支持以下块

openshift

《openshift》块查询 OpenShift 和 Kubernetes API 以检索各种资源属性。

《openshift》块支持以下属性

需要“get”、“watch”和“list”权限。

yaml 复制

kind: ClusterRole
metadata:
  name: alloy
rules:
- apiGroups: ["config.openshift.io"]
  resources: ["infrastructures", "infrastructures/status"]
  verbs: ["get", "watch", "list"]

默认情况下，API地址由环境变量KUBERNETES_SERVICE_HOST、KUBERNETES_SERVICE_PORT确定，服务令牌从/var/run/secrets/kubernetes.io/serviceaccount/token读取。如果未显式禁用TLS且未配置ca_file，则使用/var/run/secrets/kubernetes.io/serviceaccount/ca.crt。如果配置中已设置，则跳过API地址、ca_file和服务令牌的确定。

openshift块支持以下块

openshift > tls

tls块配置用于连接gRPC服务器的TLS设置。

支持以下参数

如果服务器不支持TLS，必须将insecure参数设置为true。

要禁用服务器连接的TLS，请将insecure参数设置为true。

如果reload_interval设置为"0s"，则证书永远不会重新加载。

以下参数对互斥，不能同时设置

• ca_pem和ca_file
• cert_pem和cert_file
• key_pem和key_file

如果留空cipher_suites，则使用安全默认列表。有关受支持的密码套件列表，请参阅Go TLS文档。

openshift > resource_attributes

resource_attributes 块支持以下块

kubernetes_node

kubernetes_node块查询Kubernetes API服务器以检索各种节点资源属性。

kubernetes_node块支持以下属性

需要“get”和“list”权限

yaml 复制

kind: ClusterRole
metadata:
  name: alloy
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list"]

auth_type可以设置为以下之一

• none：不进行身份验证。
• serviceAccount：使用提供给Alloy pod的标准服务帐户令牌。
• kubeConfig: 使用 ~/.kube/config 中的凭据。

kubernetes_node 块支持以下块

kubernetes_node > resource_attributes

resource_attributes 块支持以下块

通用配置

资源属性配置

此块描述了如何配置资源属性，例如 k8s.node.name 和 azure.vm.name。每个块都使用相同的属性集进行配置。只有这些属性的默认值可能因资源属性而异。例如，某些资源属性默认将 enabled 设置为 true，而其他则不是。

以下属性被支持

要查看 enabled 的默认值，请参阅上述列资源属性块的表格。描述列将声明...

默认设置为 enabled 为 true。

...

默认设置为 enabled 为 false。

导出字段

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

input 接受任何遥测信号类型的 otelcol.Consumer OTLP 格式数据

• logs
• metrics
• traces

组件健康状态

otelcol.processor.resourcedetection 仅在给定无效配置时报告为不健康。

调试信息

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

示例

环境检测器

如果您设置一个 OTEL_RESOURCE_ATTRIBUTES 环境变量，其值为 TestKey=TestValue，则所有日志、指标和跟踪都具有键 TestKey 和值 TestValue 的资源属性。

合金 复制

otelcol.processor.resourcedetection "default" {
  detectors = ["env"]

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

环境和 ec2

无需放入 ec2 {} 块。默认情况下自动应用 ec2，如 ec2 中指定。

合金 复制

otelcol.processor.resourcedetection "default" {
  detectors = ["env", "ec2"]

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

具有默认资源属性的 ec2

无需放入 ec2 {} 块。默认情况下自动应用 ec2，如 ec2 中指定。

合金 复制

otelcol.processor.resourcedetection "default" {
  detectors = ["ec2"]

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

具有显式资源属性的 ec2

合金 复制

otelcol.processor.resourcedetection "default" {
  detectors = ["ec2"]
  ec2 {
    tags = ["^tag1$", "^tag2$", "^label.*$"]
    resource_attributes {
      cloud.account.id  { enabled = true }
      cloud.availability_zone  { enabled = true }
      cloud.platform  { enabled = true }
      cloud.provider  { enabled = true }
      cloud.region  { enabled = true }
      host.id  { enabled = true }
      host.image.id  { enabled = false }
      host.name  { enabled = false }
      host.type  { enabled = false }
    }
  }

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

kubernetes_node

此示例使用 K8S_NODE_NAME 的默认 node_from_env_var 选项。

无需放入 kubernetes_node {} 块。默认情况下自动应用 kubernetes_node，如 kubernetes_node 中指定。

合金 复制

otelcol.processor.resourcedetection "default" {
  detectors = ["kubernetes_node"]

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

您需要将其添加到您的负载中

yaml 复制

        env:
          - name: K8S_NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName

带有自定义环境变量的 kubernetes_node

此示例使用设置为 my_custom_var 的自定义 node_from_env_var。

合金 复制

otelcol.processor.resourcedetection "default" {
  detectors = ["kubernetes_node"]
  kubernetes_node {
    node_from_env_var = "my_custom_var"
  }

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

您需要将其添加到您的负载中

yaml 复制

        env:
          - name: my_custom_var
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName

兼容组件

otelcol.processor.resourcedetection 可以接受以下组件的参数

• 导出 OpenTelemetry otelcol.Consumer 的组件

otelcol.processor.resourcedetection 的导出可以被以下组件消费

• 消费 OpenTelemetry otelcol.Consumer 的组件