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

otelcol.processor.resourcedetection

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

您可以通过为 otelcol.processor.resourcedetection 组件赋予不同的标签来指定多个实例。

用法

alloy 复制

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
• kubeadm
• dynatrace

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

ec2

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

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

函数即服务 (Function as a Service) 语义约定 和 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_<resource group>_<cluster name>_<location>。

示例

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

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

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

consul

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

consul 块支持以下属性

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

consul 块支持以下块

consul > resource_attributes

resource_attributes 块支持以下块

docker

docker 块查询 Docker daemon 以检索主机上的各种资源属性。

您需要挂载 Docker socket（在 Linux 上是 /var/run/docker.sock）才能联系 Docker daemon。Docker 检测在 MacOS 上不起作用。

docker 块支持以下块

docker > resource_attributes

resource_attributes 块支持以下块

gcp

gcp 块使用 Google Cloud Client Libraries for Go 检测资源属性，它从 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
• gcp.gce.instance.group_manager.name: 托管实例组名称
• gcp.gce.instance.group_manager.region: 托管实例组区域
• gcp.gce.instance.group_manager.zone: 托管实例组可用区

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

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

Google Cloud Run Services 元数据

• 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 Jobs 元数据

• 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 dyno 元数据 派生的资源属性。

heroku 块支持以下块

heroku > resource_attributes

resource_attributes 块支持以下块

当 Heroku dyno 元数据 处于活动状态时，Heroku 应用程序会通过环境变量发布信息。我们将这些环境变量映射到资源属性，如下所示

更多信息，请参阅 OpenTelemetry 规范语义约定 中的 Heroku 云提供商文档。

system

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

system 块支持以下属性

hostname_sources 的有效选项包括

• "dns": 使用多个来源获取完全限定域名。首先，它在本地机器的 hosts 文件中查找主机名。如果失败，它会查找 CNAME。最后，如果仍然失败，它会执行反向 DNS 查询。注意：此主机名来源在 Windows 上可能会产生不可靠的结果。要在 Windows 上生成 FQDN，使用下方提到的“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 确定，服务 token 从 /var/run/secrets/kubernetes.io/serviceaccount/token 读取。如果没有显式禁用 TLS 且未配置 ca_file，则使用 /var/run/secrets/kubernetes.io/serviceaccount/ca.crt。如果在配置中设置了 API 地址、ca_file 和服务 token，则跳过确定过程。

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 文档。

curve_preferences 参数按优先顺序确定在握手期间优先选择的椭圆曲线集。如果未提供，则使用默认列表。可用的椭圆曲线集包括 X25519、P521、P256 和 P384。

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 块支持以下块

kubeadm

kubeadm 块查询 Kubernetes API 服务器以检索 kubeadm 资源属性。

kubeadm 块支持以下属性

需要以下权限

yaml 复制

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: otel-collector
  namespace: kube-system
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["kubeadm-config"]
    verbs: ["get"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: otel-collector-rolebinding
  namespace: kube-system
subjects:
- kind: ServiceAccount
  name: default
  namespace: default
roleRef:
  kind: Role
  name: otel-collector
  apiGroup: rbac.authorization.k8s.io

您可以将 auth_type 设置为以下之一

• none：无认证。
• serviceAccount：使用提供给 Alloy Pod 的标准服务帐户令牌。
• kubeConfig：使用 ~/.kube/config 中的凭据。

kubeadm 块支持以下块

kubeadm > resource_attributes

resource_attributes 块支持以下块

dynatrace

dynatrace 块从 dt_host_metadata.properties 文件加载资源信息，该文件位于 /var/lib/dynatrace/enrichment (*nix 系统上) 或 %ProgramData%\dynatrace\enrichment (Windows 上) 目录中。

dynatrace 块支持以下块

dynatrace > resource_attributes

resource_attributes 块支持以下块

通用配置

资源属性配置

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

支持以下属性

要查看 enabled 的默认值，请参阅上面列出资源属性块的章节中的表格。“Description”列将说明是…

默认情况下将 enabled 设置为 true。

…或

默认情况下将 enabled 设置为 false。

导出字段

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

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

• logs
• metrics
• traces

组件健康状况

只有在给定无效配置时，otelcol.processor.resourcedetection 才会报告为不健康。

调试信息

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

示例

env detector

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

alloy 复制

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]
  }
}

env and ec2

无需添加 ec2 {} 块。正如 ec2 中所指定，会自动应用 ec2 默认值。

alloy 复制

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 默认值。

alloy 复制

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

alloy 复制

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 默认值。

alloy 复制

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。

alloy 复制

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