Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components otelcol otelcol.processor.resourcedetection

otelcol.processor.resourcedetection

otelcol.processor.resourcedetection detects resource information from the host in a format that conforms to the OpenTelemetry resource semantic conventions, and appends or overrides the resource values in the telemetry data with this information.

You can specify multiple otelcol.processor.resourcedetection components by giving them different labels.

Usage

Alloy Copy

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

Arguments

You can use the following arguments with otelcol.processor.resourcedetection:

detectors could contain the following values:

env is the only detector that’s not configured through a block. The env detector reads resource information from the OTEL_RESOURCE_ATTRIBUTES environment variable. This variable must be in the format <key1>=<value1>,<key2>=<value2>,..., the details of which are currently pending confirmation in the OpenTelemetry specification.

If a detector other than env is needed, you can customize it with the relevant block. For example, you can customize the ec2 detector with the ec2 block. If you omit the ec2 block, the defaults specified in the ec2 block documentation are used.

If multiple detectors are inserting the same attribute name, the first detector to insert wins. For example, if you had detectors = ["eks", "ec2"] then cloud.platform will be aws_eks instead of ec2.

The following order is recommended for AWS:

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

Blocks

You can use the following blocks with otelcol.processor.resourcedetection:

output

aks

The aks block adds resource attributes related to Azure AKS.

The aks block supports the following blocks:

aks > resource_attributes

The resource_attributes block supports the following blocks:

Example values:

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

Azure AKS cluster name is derived from the Azure Instance Metadata Service’s (IMDS) infrastructure resource group field. This field contains the resource group and name of the cluster, separated by underscores. For example: MC_<resource group>_<cluster name>_<location>.

Example:

• Resource group: my-resource-group
• Cluster name: my-cluster
• Location: eastus
• Generated name: MC_my-resource-group_my-cluster_eastus

The cluster name is detected if it doesn’t contain underscores and if a custom infrastructure resource group name wasn’t used.

If accurate parsing can’t be performed, the infrastructure resource group value is returned. This value can be used to uniquely identify the cluster, because Azure won’t allow users to create multiple clusters with the same infrastructure resource group name.

azure

The azure block queries the Azure Instance Metadata Service to retrieve various resource attributes.

The azure block supports the following blocks:

The azure block supports the following attributes:

azure > resource_attributes

The resource_attributes block supports the following blocks:

Example values:

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

consul

The consul block queries a Consul agent and reads its configuration endpoint to retrieve values for resource attributes.

The consul block supports the following attributes:

token is only required if the Consul ACL System is enabled.

The consul block supports the following blocks:

consul > resource_attributes

The resource_attributes block supports the following blocks:

debug_metrics

docker

The docker block queries the Docker daemon to retrieve various resource attributes from the host machine.

You need to mount the Docker socket (/var/run/docker.sock on Linux) to contact the Docker daemon. Docker detection doesn’t work on MacOS.

The docker block supports the following blocks:

docker > resource_attributes

The resource_attributes block supports the following blocks:

dynatrace

The dynatrace block loads resource information from the dt_host_metadata.properties file which is located in the /var/lib/dynatrace/enrichment (on Unix systems) or %ProgramData%\dynatrace\enrichment (on Windows) directories.

The dynatrace block supports the following blocks:

dynatrace > resource_attributes

The resource_attributes block supports the following blocks:

ec2

The ec2 block reads resource information from the EC2 instance metadata API using the AWS SDK for Go.

The ec2 block supports the following attributes:

If you are using a proxy server on your EC2 instance, it’s important that you exempt requests for instance metadata as described in the AWS cli user guide. Failing to do so can result in proxied or missing instance data.

If the instance is part of AWS ParallelCluster and the detector is failing to connect to the metadata server, check the iptable and make sure the chain PARALLELCLUSTER_IMDS contains a rule that allows the Alloy user to access 169.254.169.254/32.

tags can be used to gather tags for the EC2 instance which Alloy is running on. To fetch EC2 tags, the IAM role assigned to the EC2 instance must have a policy that includes the ec2:DescribeTags permission.

The ec2 block supports the following blocks:

ec2 > resource_attributes

The resource_attributes block supports the following blocks:

ecs

The ecs block queries the Task Metadata Endpoint (TMDE) to record information about the current ECS Task. Only TMDE V4 and V3 are supported.

The ecs block supports the following blocks:

ecs > resource_attributes

The resource_attributes block supports the following blocks:

eks

The eks block adds resource attributes for Amazon EKS.

The eks block supports the following blocks:

eks > resource_attributes

The resource_attributes block supports the following blocks:

Example values:

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

elasticbeanstalk

The elasticbeanstalk block reads the AWS X-Ray configuration file available on all Beanstalk instances with X-Ray Enabled.

The elasticbeanstalk block supports the following blocks:

elasticbeanstalk > resource_attributes

The resource_attributes block supports the following blocks:

Example values:

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

gcp

The gcp block detects resource attributes using the Google Cloud Client Libraries for Go, which reads resource information from the GCP metadata server. The detector also uses environment variables to identify which GCP platform the application is running on, and assigns appropriate resource attributes for that platform.

Use the gcp detector regardless of the GCP platform Alloy is running on.

The gcp block supports the following blocks:

gcp > resource_attributes

The resource_attributes block supports the following blocks:

Google Compute Engine (GCE) metadata

• cloud.provider: "gcp"
• cloud.platform: "gcp_compute_engine"
• cloud.account.id: Project ID
• cloud.region: For example, "us-central1"
• cloud.availability_zone: For example, "us-central1-c"
• host.id: Instance ID
• host.name: Instance name
• host.type: Machine type
• (optional) gcp.gce.instance.hostname
• (optional) gcp.gce.instance.name
• gcp.gce.instance.group_manager.name: Managed instance group name
• gcp.gce.instance.group_manager.region: Managed instance group region
• gcp.gce.instance.group_manager.zone: Managed instance group zone

Google Kubernetes Engine (GKE) metadata

• cloud.provider: "gcp"
• cloud.platform: "gcp_kubernetes_engine"
• cloud.account.id: Project ID
• cloud.region: Only for regional GKE clusters, for example "us-central1"
• cloud.availability_zone: only for zonal GKE clusters, for example, "us-central1-c"
• k8s.cluster.name
• host.id: Instance ID
• host.name: Instance name, only when workload identity is disabled

One known issue happens when GKE workload identity is enabled. The GCE metadata endpoints won’t be available, and the GKE resource detector won’t be able to determine host.name. If this happens, you can set host.name from one of the following resources:

• Get the node.name through the downward API with the env detector.
• Get the Kubernetes node name from the Kubernetes API (with k8s.io/client-go).

Google Cloud Run Services metadata

• cloud.provider: "gcp"
• cloud.platform: "gcp_cloud_run"
• cloud.account.id: Project ID
• cloud.region: For example, "us-central1"
• faas.id: Instance ID
• faas.name: Service name
• faas.version: Service revision

Cloud Run Jobs metadata

• cloud.provider: "gcp"
• cloud.platform: "gcp_cloud_run"
• cloud.account.id: Project ID
• cloud.region: For example, "us-central1"
• faas.id: Instance ID
• faas.name: Service name
• gcp.cloud_run.job.execution: For example, "my-service-ajg89"
• gcp.cloud_run.job.task_index: For example, "0"

Google Cloud Functions metadata

• cloud.provider: "gcp"
• cloud.platform: "gcp_cloud_functions"
• cloud.account.id: Project ID
• cloud.region: For example, "us-central1"
• faas.id: Instance ID
• faas.name: Function name
• faas.version: Function version

Google App Engine metadata

• cloud.provider: "gcp"
• cloud.platform: "gcp_app_engine"
• cloud.account.id: Project ID
• cloud.region: For example, "us-central1"
• cloud.availability_zone: For example, "us-central1-c"
• faas.id: Instance ID
• faas.name: Service name
• faas.version: Service version

heroku

The heroku block adds resource attributes derived from Heroku dyno metadata.

The heroku block supports the following blocks:

heroku > resource_attributes

The resource_attributes block supports the following blocks:

When Heroku dyno metadata is active, Heroku applications publish information through environment variables. These environment variables map to resource attributes as follows:

For more information, refer to the Heroku cloud provider documentation under the OpenTelemetry specification semantic conventions.

kubeadm

The kubeadm block queries the Kubernetes API server to retrieve kubeadm resource attributes.

The kubeadm block supports the following attributes:

The following permissions are required:

YAML Copy

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

You can set auth_type to one of the following:

• none: No authentication.
• serviceAccount: Use the standard service account token provided to the Alloy Pod.
• kubeConfig: Use credentials from ~/.kube/config.

The kubeadm block supports the following blocks:

kubeadm > resource_attributes

The resource_attributes block supports the following blocks:

kubernetes_node

The kubernetes_node block queries the Kubernetes API server to retrieve various node resource attributes.

The kubernetes_node block supports the following attributes:

The “get” and “list” permissions are required:

YAML Copy

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

auth_type can be set to one of the following:

• none: No authentication.
• serviceAccount: Use the standard service account token provided to the Alloy Pod.
• kubeConfig: Use credentials from ~/.kube/config.

The kubernetes_node block supports the following blocks:

kubernetes_node > resource_attributes

The resource_attributes block supports the following blocks:

lambda

The lambda block uses the AWS Lambda runtime environment variables to retrieve various resource attributes.

The lambda block supports the following blocks:

lambda > resource_attributes

The resource_attributes block supports the following blocks:

Cloud semantic conventions:

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

Function as a Service semantic conventions and AWS Lambda semantic conventions:

• 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 Logs semantic conventions:

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

openshift

The openshift block queries the OpenShift and Kubernetes APIs to retrieve various resource attributes.

The openshift block supports the following attributes:

The “get”, “watch”, and “list” permissions are required:

YAML Copy

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

By default, the API address is determined from the environment variables KUBERNETES_SERVICE_HOST, KUBERNETES_SERVICE_PORT and the service token is read from /var/run/secrets/kubernetes.io/serviceaccount/token. If TLS isn’t explicitly disabled and no ca_file is configured, /var/run/secrets/kubernetes.io/serviceaccount/ca.crt is used. The determination of the API address, ca_file, and the service token is skipped if they are set in the configuration.

The openshift block supports the following blocks:

openshift > tls

The tls block configures TLS settings used for the connection to the gRPC server.

tpm

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Expand table

Name	Type	Description	Default	Required
auth	string	The authorization value used to authenticate the TPM device.	""	no
enabled	bool	Load the tls.key_file from TPM.	false	no
owner_auth	string	The owner authorization value used to authenticate the TPM device.	""	no
path	string	Path to the TPM device or Unix domain socket.	""	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

Example

Alloy Copy

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

In the above example, the private key my-tss2-key.key in TSS2 format will be loaded from the TPM device /dev/tmprm0.

openshift > resource_attributes

The resource_attributes block supports the following blocks:

system

The system block queries the host machine to retrieve various resource attributes.

The system block supports the following attributes:

The valid options for hostname_sources are:

• "dns": Uses multiple sources to get the fully qualified domain name. First, it looks up the host name in the local machine’s hosts file. If that fails, it looks up the CNAME. If the CNAME lookup fails, it does a reverse DNS query. This hostname source may produce unreliable results on Windows. To produce a FQDN, Windows hosts might have better results using the “lookup” hostname source.
• "os": Provides the hostname provided by the local machine’s kernel.
• "cname": Provides the canonical name, as provided by net.LookupCNAME in the Go standard library. This hostname source may produce unreliable results on Windows.
• "lookup": Does a reverse DNS lookup of the current host’s IP address.

If there is an error fetching a hostname from a source, the next source from the list of hostname_sources will be considered.

The system block supports the following blocks:

system > resource_attributes

The resource_attributes block supports the following blocks:

Common configuration

Resource attribute configuration

This block describes how to configure resource attributes such as k8s.node.name and azure.vm.name. Every block is configured using the same set of attributes. Only the default values for those attributes might differ across resource attributes. For example, some resource attributes have enabled set to true by default, whereas others don’t.

The following attributes are supported:

To see the default value for enabled, refer to the tables in the sections above which list the resource attributes blocks. The “Description” column will state either:

Sets enabled to true by default.

or:

Sets enabled to false by default.

Exported fields

The following fields are exported and can be referenced by other components:

input accepts otelcol.Consumer OTLP-formatted data for any telemetry signal of these types:

• logs
• metrics
• traces

Component health

otelcol.processor.resourcedetection is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.processor.resourcedetection doesn’t expose any component-specific debug information.

Examples

env detector

If you set up a OTEL_RESOURCE_ATTRIBUTES environment variable with value of TestKey=TestValue, then all logs, metrics, and traces have a resource attribute with a key TestKey and value of TestValue.

Alloy Copy

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

There is no need to put in an ec2 {} block. The ec2 defaults are applied automatically, as specified in ec2.

Alloy Copy

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 with default resource attributes

There is no need to put in a ec2 {} block. The ec2 defaults are applied automatically, as specified in ec2.

Alloy Copy

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 with explicit resource attributes

Alloy Copy

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 with a default node

This example uses the default node_from_env_var option of K8S_NODE_NAME.

There is no need to put in a kubernetes_node {} block. The kubernetes_node defaults are applied automatically, as specified in kubernetes_node.

Alloy Copy

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

You need to add this to your workload:

YAML Copy

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

kubernetes_node with a custom environment variable

This example uses a custom node_from_env_var set to my_custom_var.

Alloy Copy

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

You need to add this to your workload:

YAML Copy

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

Compatible components

otelcol.processor.resourcedetection can accept arguments from the following components:

• Components that export OpenTelemetry otelcol.Consumer

otelcol.processor.resourcedetection has exports that can be consumed by the following components:

• Components that consume OpenTelemetry otelcol.Consumer