Resourcedetection Processor

Available in: contrib, k8s Maintainers: @Aneurysm9, @dashpole, @paulojmdias Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

The Resource Detection processor can be used to detect resource information from the host, in a format that conforms to the OpenTelemetry resource semantic conventions, and append or override the resource value in telemetry data with this information.

Note If a configured resource detector fails, the error will propagate and stop the collector from starting.

Retry configuration

By default, every detector retries failed Detect calls with exponential backoff. The retry block uses the standard configretry.BackOffConfig and applies to every detection attempt (including periodic refreshes when refresh_interval > 0).

Field	Default	Notes
`retry.enabled`	`true`	Set to `false` to perform a single attempt per detector with no retries.
`retry.initial_interval`	`1s`	Delay before the first retry.
`retry.randomization_factor`	`0.5`	Jitter applied to each interval.
`retry.multiplier`	`2`	Each interval is multiplied by this factor up to `max_interval`.
`retry.max_interval`	`30s`	Upper bound on the backoff interval.
`retry.max_elapsed_time`	`0`	Total retry budget. `0` means no explicit cap — the session is bounded by `timeout` (the HTTP client timeout) instead. Set to a positive duration to retry past `timeout`.

When retry.max_elapsed_time is 0, the whole detection session is bounded by timeout. When it is greater than zero, timeout only bounds each individual attempt, and max_elapsed_time bounds the total. The processor rejects configurations with retry.enabled: true, timeout: 0, and retry.max_elapsed_time: 0 — at least one of the two must be set so a hung detector cannot block startup indefinitely. Example: wait up to two minutes for a slow metadata server to come up.

processors:
  resource_detection/wait_for_metadata:
    detectors: [gcp]
    timeout: 5s
    retry:
      enabled: true
      initial_interval: 1s
      max_interval: 10s
      max_elapsed_time: 2m

Supported detectors

Environment Variable

Reads resource information from the OTEL_RESOURCE_ATTRIBUTES environment variable. This is expected to be in the format <key1>=<value1>,<key2>=<value2>,..., the details of which are currently pending confirmation in the OpenTelemetry specification. Example:

processors:
  resource_detection/env:
    detectors: [env]
    timeout: 2s
    override: false

[!NOTE] The deprecated coponent type resourcedetection (without the underscore) can still be used as an alias and will log a deprecation warning.

System metadata

Note: use the Docker detector (see below) if running the Collector as a Docker container. Queries the host machine to retrieve the system related resource attributes. The list of the populated resource attributes can be found at System Detector Resource Attributes. By default host.name is being set to FQDN if possible, and a hostname provided by OS used as fallback. This logic can be changed with hostname_sources configuration which is set to ["dns", "os"] by default. Use the following config to avoid getting FQDN and apply hostname provided by OS only:

processors:
  resource_detection/system:
    detectors: ["system"]
    system:
      hostname_sources: ["os"]

all valid options for hostname_sources:
- “dns”
- “os”
- “cname”
- “lookup”

Hostname Sources

dns

The “dns” hostname source 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. Lastly, if that fails, it does a reverse DNS query. Note: this hostname source may produce unreliable results on Windows. To produce a FQDN, Windows hosts might have better results using the “lookup” hostname source, which is mentioned below.

os

The “os” hostname source provides the hostname provided by the local machine’s kernel.

cname

The “cname” hostname source provides the canonical name, as provided by net.LookupCNAME in the Go standard library. Note: this hostname source may produce unreliable results on Windows.

lookup

The “lookup” hostname source does a reverse DNS lookup of the current host’s IP address.

Docker metadata

Queries the Docker daemon to retrieve resource attributes from the host machine. The list of the populated resource attributes can be found at Docker Detector Resource Attributes. You need to mount the Docker socket (/var/run/docker.sock on Linux) to contact the Docker daemon. Docker detection does not work on macOS. If container.name or container.image.name is enabled, the detector inspects the current container by using the container hostname as the Docker container name or ID. This can fail when the container hostname is changed, for example when running with network_mode: host. Example:

processors:
  resource_detection/docker:
    detectors: [env, docker]
    timeout: 2s
    override: false

Note: When fail_on_missing_metadata is true, this detector returns an error if the Docker daemon cannot be contacted. When false (default), failures are logged and an empty resource is returned.

Docker Socket Permissions

Since version 0.40.0, official OpenTelemetry Collector images run as a non-root user. To access the Docker socket, you need to configure appropriate permissions:

Linux: Grant access to the docker group (e.g., --group-add <docker-gid> or set runAsGroup in Kubernetes)
Windows: Ensure appropriate named pipe permissions

For detailed permission configuration options and security considerations, see the Docker Stats receiver documentation. For more information, see issue #11791.

Heroku metadata

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

Dyno metadata environment variable	Resource attribute
`HEROKU_APP_ID`	`heroku.app.id`
`HEROKU_APP_NAME`	`service.name`
`HEROKU_DYNO_ID`	`service.instance.id`
`HEROKU_RELEASE_CREATED_AT`	`heroku.release.creation_timestamp`
`HEROKU_RELEASE_VERSION`	`service.version`
`HEROKU_SLUG_COMMIT`	`heroku.release.commit`

For more information, see the Heroku cloud provider documentation under the OpenTelemetry specification semantic conventions. The list of the populated resource attributes can be found at Heroku Detector Resource Attributes.

processors:
  resource_detection/heroku:
    detectors: [env, heroku]
    timeout: 2s
    override: false

Note: When fail_on_missing_metadata is true, this detector returns an error if both HEROKU_DYNO_ID and HEROKU_APP_ID environment variables are not set, instead of silently returning an empty resource.

GCP Metadata

Uses the Google Cloud Client Libraries for Go to read resource information from the metadata server and environment variables to detect which GCP platform the application is running on, and detect the appropriate attributes for that platform. Regardless of the GCP platform the application is running on, use the gcp detector: It also can optionally gather labels for the GCE instance that the collector is running on. Note that in order to fetch GCE labels, the service account assigned to the GCE instance must have the roles/compute.viewer role. Example:

processors:
  resource_detection/gcp:
    detectors: [env, gcp]
    timeout: 2s
    override: false
    gcp:
      # A list of regex's to match label keys to add as resource attributes can be specified
      labels:
        - ^label1$
        - ^label2$
        - ^label.*$

The list of the populated resource attributes can be found at GCP Detector Resource Attributes.

GCE Metadata

cloud.provider (“gcp”)
cloud.platform (“gcp_compute_engine”)
cloud.account.id (project id)
cloud.region (e.g. us-central1)
cloud.availability_zone (e.g. 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

GKE Metadata

cloud.provider (“gcp”)
cloud.platform (“gcp_kubernetes_engine”)
cloud.account.id (project id)
cloud.region (e.g. “us-central1”)
cloud.availability_zone (only for zonal GKE clusters; e.g. “us-central1-c”)
k8s.cluster.name
host.id (instance id)
host.name (instance name; availability with workload identity depends on GKE version)

Google Cloud Run Services Metadata

cloud.provider (“gcp”)
cloud.platform (“gcp_cloud_run”)
cloud.account.id (project id)
cloud.region (e.g. “us-central1”)
faas.instance (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 (e.g. “us-central1”)
faas.instance (instance id)
faas.name (service name)
gcp.cloud_run.job.execution (“my-service-ajg89”)
gcp.cloud_run.job.task_index (“0”)

Cloud Run Worker Pools Metadata

cloud.provider (“gcp”)
cloud.platform (“gcp_cloud_run”)
cloud.account.id (project id)
cloud.region (e.g. “us-central1”)
faas.instance (instance id)
faas.name (worker pool name)
faas.version (worker pool revision)

Google Cloud Functions Metadata

cloud.provider (“gcp”)
cloud.platform (“gcp_cloud_functions”)
cloud.account.id (project id)
cloud.region (e.g. “us-central1”)
faas.instance (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 (e.g. “us-central1”)
cloud.availability_zone (e.g. “us-central1-c”)
faas.instance (instance id)
faas.name (service name)
faas.version (service version)

AWS EC2

Uses AWS SDK for Go to read resource information from the EC2 instance metadata API to retrieve related resource attributes: The list of the populated resource attributes can be found at EC2 Detector Resource Attributes. It also can optionally gather tags for the EC2 instance that the collector is running on. By default, tags are fetched via the EC2 DescribeTags API, which requires the IAM role assigned to the EC2 instance to include the ec2:DescribeTags permission. Alternatively, tags can be fetched via the Instance Metadata Service (IMDS), which does not require any IAM permissions but requires instance metadata tags to be enabled on the instance. Tag retrieval behavior is controlled by the tags_from_imds configuration field:

false (default): tags are fetched via the EC2 DescribeTags API — requires ec2:DescribeTags IAM permission.
true: tags are fetched via IMDS — no IAM permissions needed, but requires InstanceMetadataTags=enabled on the instance.

EC2 custom configuration example:

processors:
  resource_detection/ec2:
    detectors: ["ec2"]
    ec2:
      # A list of regex's to match tag keys to add as resource attributes can be specified
      tags:
        - ^tag1$
        - ^tag2$
        - ^label.*$
      # Set to true to fetch tags via IMDS instead of the EC2 DescribeTags API.
      # Requires InstanceMetadataTags=enabled on the instance; no IAM permissions needed.
      tags_from_imds: false

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 OTEL user to access 169.254.169.254/32 In some cases, you might need to change the behavior of the AWS metadata client from the standard retryer By default, the client retries 3 times with a max backoff delay of 20s. We offer a limited set of options to override those defaults specifically, such that you can set the client to retry 10 times, for up to 5 minutes, for example:

processors:
  resource_detection/ec2:
    detectors: ["ec2"]
    ec2:
      max_attempts: 10
      max_backoff: 5m

Deprecated: The per-detector fail_on_missing_metadata field is deprecated. Use the top-level fail_on_missing_metadata in the processor config instead. See Using the fail_on_missing_metadata parameter.

Amazon ECS

Queries the Task Metadata Endpoint (TMDE) to record information about the current ECS Task. Only TMDE V4 and V3 are supported. The list of the populated resource attributes can be found at ECS Detector Resource Attributes. Example:

processors:
  resource_detection/ecs:
    detectors: [env, ecs]
    timeout: 2s
    override: false

Note: When fail_on_missing_metadata is true, this detector returns an error if the ECS Task Metadata Endpoint is not detected (not running on ECS) or if container sidecar metadata retrieval fails, instead of silently returning an empty or partial resource.

Amazon Elastic Beanstalk

Reads the AWS X-Ray configuration file available on all Beanstalk instances with X-Ray Enabled. The list of the populated resource attributes can be found at Elastic Beanstalk Detector Resource Attributes. Example:

processors:
  resource_detection/elastic_beanstalk:
    detectors: [env, elastic_beanstalk]
    timeout: 2s
    override: false

Note: When fail_on_missing_metadata is true, this detector returns an error if the Elastic Beanstalk configuration file is not found, instead of silently returning an empty resource.

Migrating to the current deployment semantic conventions

By default this detector reports deployment.environment, which is deprecated in the semantic conventions, and reports the deployment ID as service.instance.id. Two feature gates move it to deployment.environment.name and deployment.id:

Feature gate	Effect
`processor.resourcedetection.elasticbeanstalk.EmitV1DeploymentConventions`	Emit `deployment.environment.name` and `deployment.id`.
`processor.resourcedetection.elasticbeanstalk.DontEmitV0DeploymentConventions`	Stop emitting `deployment.environment` and `service.instance.id`. Requires the gate above.

Enabling only EmitV1DeploymentConventions reports both sets of attributes, which lets you migrate dashboards and alerts before dropping the deprecated ones:

otelcol --feature-gates=processor.resourcedetection.elasticbeanstalk.EmitV1DeploymentConventions

Once nothing depends on the deprecated attributes, enable both gates:

otelcol --feature-gates=processor.resourcedetection.elasticbeanstalk.EmitV1DeploymentConventions,processor.resourcedetection.elasticbeanstalk.DontEmitV0DeploymentConventions

Amazon EKS

This detector reads resource information from the EC2 instance metadata service to retrieve related resource attributes. If IMDS is not available, (example: EKS-AutoMode and POD not on the hostnetwork), it falls back to a combination of Kubernetes API and EC2 API to retrieve related resource attributes. EC2 API requires the EC2:DescribeInstances permission to be granted to the IAM role. If IMDS is not accessible, ex: EKS-AutoMode, you can use POD Identity. The list of the populated resource attributes can be found at EKS Detector Resource Attributes. Example:

processors:
  resource_detection/eks:
    detectors: [env, eks]
    timeout: 15s
    override: false

Note: When fail_on_missing_metadata is true, this detector returns an error if EKS cannot be detected (environment check fails) or if metadata retrieval fails, instead of silently returning an empty resource.

Cluster Name

Cluster name detection is disabled by default, and can be enabled with the following configuration:

processors:
  resource_detection/eks:
    detectors: [env, eks]
    timeout: 15s
    override: false
    eks:
      resource_attributes:
        k8s.cluster.name:
          enabled: true

Note: The kubernetes cluster name is only available when running on EC2 instances, and requires permission to run the EC2:DescribeInstances action. If you see an error with the message context deadline exceeded, please increase the timeout setting in your config.

Node Name Env Variable

When using the EC2 API and the Kubernetes API to retrieve resource attributes, the node name is needed. The node name is extracted from the env variable you define on the pod. The node name env variable that contains the node name value can be set using the node_from_env_var option:

processors:
  resource_detection/eks:
    detectors: [eks]
    timeout: 15s
    override: false
    eks:
      node_from_env_var: K8S_NODE_NAME

In this example, the env variable K8S_NODE_NAME will hold the actual node name and can be set in the pod spec using the downward API.

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

AWS Lambda

Uses the AWS Lambda runtime environment variables to retrieve related resource attributes. The list of the populated resource attributes can be found at Lambda Detector Resource Attributes. Example:

processors:
  resource_detection/lambda:
    detectors: [env, lambda]
    timeout: 0.2s
    override: false

Note: When fail_on_missing_metadata is true, this detector returns an error if the AWS_LAMBDA_FUNCTION_NAME environment variable is not set (not running on Lambda), instead of silently returning an empty resource.

Azure

Queries the Azure Instance Metadata Service to retrieve related attributes. The list of the populated resource attributes can be found at Azure Detector Resource Attributes. Example:

processors:
  resource_detection/azure:
    detectors: [env, azure]
    timeout: 2s
    override: false

It also can optionally gather tags from the Azure instance that the Collector is running on. Azure custom configuration example:

processors:
  resource_detection/azure:
    detectors: ["azure"]
    azure:
      # A list of regex's to match tag keys to add as resource attributes can be specified
      tags:
        - ^tag1$
        - ^tag2$
        - ^label.*$

Matched tags are added as:

azure.tags.<tag name>

Azure AKS

The list of the populated resource attributes can be found at AKS Detector Resource Attributes.

processors:
  resource_detection/aks:
    detectors: [env, aks]
    timeout: 2s
    override: false

Cluster Name

Cluster name detection is disabled by default, and can be enabled with the following configuration:

processors:
  resource_detection/aks:
    detectors: [aks]
    timeout: 2s
    override: false
    aks:
      resource_attributes:
        k8s.cluster.name:
          enabled: true

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. e.g: 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 does not contain underscores and if a custom infrastructure resource group name was not used. If accurate parsing cannot be performed, the infrastructure resource group value is returned. This value can be used to uniquely identify the cluster, as Azure will not allow users to create multiple clusters with the same infrastructure resource group name.

Azure Container Apps

Uses the Azure Container Apps injected environment variables to retrieve related resource attributes. Note: Azure Container Apps jobs are not supported. The list of the populated resource attributes can be found at Azure Container Apps Detector Resource Attributes. Example:

processors:
  resourcedetection/azurecontainerapps:
    detectors: [env, azurecontainerapps]
    timeout: 2s
    override: false

Note: When fail_on_missing_metadata is true, this detector returns an error if the CONTAINER_APP_NAME environment variable is not set (not running on Azure Container Apps), instead of silently returning an empty resource.

Consul

Queries a consul agent and reads its configuration endpoint to retrieve related resource attributes: The list of the populated resource attributes can be found at Consul Detector Resource Attributes. In addition to:

exploded consul metadata - reads all key:value pairs in consul metadata into label:labelvalue pairs.

processors:
  resource_detection/consul:
    detectors: [env, consul]
    timeout: 2s
    override: false

Consul node metadata keys are emitted verbatim, without a namespace of their own. Enabling the processor.resourcedetection.consul.prefixMetaAttributes feature gate namespaces each key as consul.meta.<key>, consistent with the other detectors that expose user-defined key/value data (ec2.tag., azure.tag., gcp.gce.instance.labels., openstack.nova.meta.):

otelcol --feature-gates=processor.resourcedetection.consul.prefixMetaAttributes

The gate is alpha (disabled by default) and is expected to become the default in a future release.

Kubeadm Metadata

Queries the K8S API server to retrieve kubeadm resource attributes: The list of the populated resource attributes can be found at kubeadm Detector Resource Attributes.

Note: When fail_on_missing_metadata is true, this detector returns an error if Kubernetes API calls fail. When false (default), failures are logged and an empty resource is returned.

Oracle Cloud Infrastructure (OCI) metadata

The OCI detector implements a fast probe to the instance metadata service (IMDS) endpoint to quickly verify if the collector is running on OCI. If this probe fails, the detector returns an empty resource and no error. If the probe succeeds, it then fetches instance metadata; if this fetch fails, the detector logs and returns an error so that partial detection is not silently ignored. This behavior makes it possible to differentiate between the case where the collector is not running on OCI, vs it is running on OCI but the IMDS request failed. Queries the Oracle Cloud Infrastructure (OCI) metadata service to retrieve resource attributes related to the OCI instance environment. The list of the populated resource attributes can be found at OracleCloud Detector Resource Attributes. Example:

processors:
  resource_detection/oraclecloud:
    detectors: [env, oraclecloud]
    timeout: 2s
    override: false

Populated resource attributes:

cloud.provider
cloud.platform
cloud.region
cloud.resource_id
cloud.availability_zone
host.id
host.name
host.type
k8s.cluster.name

See internal/oraclecloud/documentation.md for detailed attribute definitions.

The following permissions are required:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: otel-collector
  namespace: kube-system
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    resourceNames: ["kubeadm-config"]
    verbs: ["get"]
  - apiGroups: [""]
    resources: ["namespaces"]
    resourceNames: ["kube-system"]
    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

Name	Type	Required	Default	Docs
auth_type	string	No	`serviceAccount`	How to authenticate to the K8s API server. This can be one of `none` (for no auth), `serviceAccount` (to use the standard service account token provided to the agent pod), or `kubeConfig` to use credentials from `~/.kube/config`.

K8S API Metadata

Queries the K8S API server to retrieve node and cluster resource attributes. The k8snode detector name is deprecated — use k8s_api instead. The list of the populated resource attributes can be found at k8s_api Detector Resource Attributes.

Note: When fail_on_missing_metadata is true, this detector returns an error if Kubernetes API calls fail. When false (default), failures are logged and an empty resource is returned.

The following permissions are required:

kind: ClusterRole
metadata:
  name: otel-collector
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["namespaces"]
    resourceNames: ["kube-system"]
    verbs: ["get"]

Note: node_from_env_var and the nodes RBAC permission are required even when only k8s.cluster.uid is enabled; the detector will fail to start if the env variable is unset or empty. The namespaces permission is required for k8s.cluster.uid; if missing, detection continues without it.

Name	Type	Required	Default	Docs
auth_type	string	No	`serviceAccount`	How to authenticate to the K8s API server. This can be one of `none` (for no auth), `serviceAccount` (to use the standard service account token provided to the agent pod), or `kubeConfig` to use credentials from `~/.kube/config`.
node_from_env_var	string	Yes	`K8S_NODE_NAME`	The environment variable name that holds the name of the node to retrieve metadata from. Default value is `K8S_NODE_NAME`. You can set the env dynamically on the workload definition using the downward API; see example

Example using the default `node_from_env_var` option:

processors:
  resource_detection:
    detectors: [k8s_api]

and add this to your workload:

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

Example using a custom variable `node_from_env_var` option:

processors:
  resource_detection:
    detectors: [k8s_api]
    k8s_api:
      node_from_env_var: "my_custom_var"

and add this to your workload:

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

OpenShift

Queries the OpenShift and Kubernetes API to retrieve related resource attributes. The list of the populated resource attributes can be found at OpenShift Detector Resource Attributes. The following permissions are required:

kind: ClusterRole
metadata:
  name: otel-collector
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 is not explicit 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. Example:

processors:
  resource_detection/openshift:
    detectors: [openshift]
    timeout: 2s
    override: false
    openshift: # optional
      address: "https://api.example.com"
      token: "token"
      tls:
        insecure: false
        ca_file: "/var/run/secrets/kubernetes.io/serviceaccount/ca.crt"

See: TLS Configuration Settings for the full set of available options.

Dynatrace

Loads resource information from the dt_host_metadata.properties file which is located in the /var/lib/dynatrace/enrichment (on *nix systems) or %ProgramData%\dynatrace\enrichment (on Windows) directories. If present in the file, the following attributes will be added:

dt.entity.host
host.name
dt.smartscape.host

The Dynatrace detector does not require any additional configuration, other than being added to the list of detectors. Example:

processors:
  resource_detection/dynatrace:
    override: false
    detectors: [dynatrace]

It is strongly recommended to use the override: false configuration option, to prevent the detector from overwriting existing resource attributes. If the Dynatrace host entity identifier attribute dt.entity.host, host.name, or dt.smartscape.host are already present on incoming data as it is sent from other sources to the collector, then these describe the monitored entity in the best way. Overriding these with the collector’s own identifier would instead make the telemetry appear as if it was coming from the collector or the collector’s host instead, which might be inaccurate.

Hetzner

Uses the Hetzner metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Hetzner Detector Resource Attributes. Hetzner custom configuration example:

processors:
  resource_detection/hetzner:
    detectors: ["hetzner"]

Akamai

Uses the Akamai metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Akamai Detector Resource Attributes. Akamai custom configuration example:

processors:
  resource_detection/akamai:
    detectors: ["akamai"]

Scaleway

Uses the Scaleway metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Scaleway Detector Resource Attributes. Scaleway custom configuration example:

processors:
  resource_detection/scaleway:
    detectors: ["scaleway"]

Upcloud

Uses the Upcloud metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Upcloud Detector Resource Attributes. Upcloud custom configuration example:

processors:
  resource_detection/upcloud:
    detectors: ["upcloud"]

Deprecated: The per-detector fail_on_missing_metadata field is deprecated. Use the top-level fail_on_missing_metadata in the processor config instead. See Using the fail_on_missing_metadata parameter.

Vultr

Uses the Vultr metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Vultr Detector Resource Attributes. Vultr custom configuration example:

processors:
  resource_detection/vultr:
    detectors: ["vultr"]

Deprecated: The per-detector fail_on_missing_metadata field is deprecated. Use the top-level fail_on_missing_metadata in the processor config instead. See Using the fail_on_missing_metadata parameter.

Digital Ocean

Uses the Digital Ocean metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Digital Ocean Detector Resource Attributes. Akamai custom configuration example:

processors:
  resource_detection/digitalocean:
    detectors: ["digitalocean"]

Openstack Nova

Uses the OpenStack Nova metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Nova Detector Resource Attributes. It can also optionally capture metadata keys from the "meta" section of meta_data.json as resource attributes, using regular expressions to match the keys you want. Nova custom configuration example:

processors:
  resource_detection/nova:
    detectors: ["nova"]
    nova:
      # A list of regex's to match label keys to add as resource attributes can be specified
      labels:
        - ^tag1$
        - ^tag2$
        - ^label.*$

Deprecated: The per-detector fail_on_missing_metadata field is deprecated. Use the top-level fail_on_missing_metadata in the processor config instead. See Using the fail_on_missing_metadata parameter.

Alibaba Cloud ECS

Uses the Alibaba Cloud metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Alibaba Cloud ECS Detector Resource Attributes. Alibaba Cloud ECS custom configuration example:

processors:
  resource_detection/alibaba_ecs:
    detectors: ["alibaba_ecs"]

Deprecated: The per-detector fail_on_missing_metadata field is deprecated. Use the top-level fail_on_missing_metadata in the processor config instead. See Using the fail_on_missing_metadata parameter.

Tencent Cloud CVM

Uses the Tencent Cloud metadata API to read resource information from the instance metadata service and populate related resource attributes. The list of the populated resource attributes can be found at Tencent Cloud CVM Detector Resource Attributes. Tencent Cloud CVM custom configuration example:

processors:
  resource_detection/tencent_cvm:
    detectors: ["tencent_cvm"]

Deprecated: The per-detector fail_on_missing_metadata field is deprecated. Use the top-level fail_on_missing_metadata in the processor config instead. See Using the fail_on_missing_metadata parameter.

IBM Cloud VPC

Queries the IBM Cloud VPC Instance Metadata Service to retrieve resource attributes from the instance. The list of the populated resource attributes can be found at IBM Cloud VPC Detector Resource Attributes. By default, the detector queries the IBM Cloud VPC Instance Metadata Service at http://api.metadata.cloud.ibm.com. Set protocol: https to use HTTPS instead.

Note The protocol option must match the instance’s metadata service access mode. If the Secure access state is toggled while the collector is running, update the protocol configuration value accordingly and restart the collector.

Example:

processors:
  resource_detection/ibmcloud_vpc:
    detectors: [env, ibmcloud_vpc]
    timeout: 2s
    override: false

IBM Cloud VPC custom configuration example:

processors:
  resource_detection/ibmcloud_vpc:
    detectors: ["ibmcloud_vpc"]
    ibmcloud_vpc:
      # Use HTTPS for the IMDS endpoint
      protocol: https

IBM Cloud Classic

Queries the IBM Cloud Classic (SoftLayer) Resource Metadata Service to retrieve resource attributes from the instance. The list of the populated resource attributes can be found at IBM Cloud Classic Detector Resource Attributes. Example:

processors:
  resource_detection/ibmcloud_classic:
    detectors: [env, ibmcloud_classic]
    timeout: 2s
    override: false

Configuration

detectors: [ <string> ]
# determines if existing resource attributes should be overridden or preserved, defaults to true
override: <bool>
# how often resource detection should be refreshed; if unset, detection runs only once at startup
refresh_interval: <duration>
# controls whether network-based detectors treat an unreachable metadata service as a hard failure;
# supersedes the per-detector fail_on_missing_metadata fields (now deprecated). Default: false
fail_on_missing_metadata: <bool>

You have the ability to specify which detector should collect each attribute with resource_attributes option. An example of such a configuration is:

resource_detection:
  detectors: [system, ec2]
  system:
    resource_attributes:
      host.name:
        enabled: true
      host.id:
        enabled: false
  ec2:
    resource_attributes:
      host.name:
        enabled: false
      host.id:
        enabled: true

Using the `refresh_interval` parameter

The refresh_interval option allows resource attributes to be periodically refreshed without restarting the Collector. Important considerations:

Latency: Newly detected resource attributes will be applied after the next refresh cycle completes (up to refresh_interval duration).
Metric cardinality: Changes to resource attributes create new metric time series, which can significantly increase storage costs and query complexity.
Performance impact: Each refresh re-runs all configured detectors. Values below 5 minutes can increase CPU and memory usage. There is no enforced minimum, but intervals below 1 minute are strongly discouraged.

Recommendation: In most environments, a single resource detection at startup is sufficient. Periodic refresh should be used only when resource attributes are expected to change during the Collector’s lifetime (e.g., Kubernetes pod labels, cloud instance tags).

Using the `fail_on_missing_metadata` parameter

The fail_on_missing_metadata option controls whether detectors treat an unreachable metadata service as a hard failure. When set to true, affected detectors return an error instead of silently returning an empty resource, enabling the collector’s retry mechanism to wait until the metadata service becomes available. This is particularly useful for workloads where the metadata service may be temporarily unavailable during node startup.

processors:
  resource_detection/gke:
    detectors: [gcp]
    fail_on_missing_metadata: true

Note: The per-detector fail_on_missing_metadata fields in the ec2, alibaba_ecs, tencent_cvm, upcloud, vultr, and nova detector configs are deprecated. Use this top-level flag instead.

Performance

Benchmark Tests

This component includes comprehensive benchmark tests for all stable signals. The benchmarks measure the performance of the processor under different configurations:

Traces: BenchmarkConsumeTracesDefault and BenchmarkConsumeTracesAll
Metrics: BenchmarkConsumeMetricsDefault and BenchmarkConsumeMetricsAll
Logs: BenchmarkConsumeLogsDefault and BenchmarkConsumeLogsAll

To run the benchmarks locally:

go test -bench=. -benchmem

For the latest benchmark results, see the GitHub Actions workflow runs.

Internal Telemetry

The processor emits internal telemetry to observe resource detection. For the complete list of metrics and their attributes, see the Internal Telemetry documentation.

Ordering

Note that 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 below ordering is recommended.

AWS

lambda
elastic_beanstalk
eks
ecs
ec2

The full list of settings exposed for this extension are documented in config.go with detailed sample configurations in testdata/config.yaml.

Attributes

Attribute Name	Description	Type	Values
`detector`	The resource detector that produced the result.	string	`akamai`, `aks`, `alibaba_ecs`, `azure`, `consul`, `digitalocean`, `docker`, `dynatrace`, `ec2`, `ecs`, `eks`, `elastic_beanstalk`, `env`, `gcp`, `heroku`, `hetzner`, `ibmcloud_classic`, `ibmcloud_vpc`, `k8s_api`, `k8snode`, `kubeadm`, `lambda`, `nova`, `openshift`, `oraclecloud`, `scaleway`, `system`, `tencent_cvm`, `upcloud`, `vultr`
`error.type`	The type of error that caused detection to fail. Absent on success.	string
`outcome`	Whether the detection operation succeeded or failed.	string	`success`, `failure`

Configuration

config.yaml (testdata)

resource_detection:
resource_detection/openshift:
  detectors: [openshift]
  timeout: 2s
  override: false
  openshift:
    address: "127.0.0.1:4444"
    token: "some_token"
    tls:
      insecure: true

resource_detection/aks:
  detectors: [env, aks]
  timeout: 2s
  override: false

resource_detection/azurecontainerapps:
  detectors: [env, azurecontainerapps]

resource_detection/gcp:
  detectors: [env, gcp]
  timeout: 2s
  override: false

resource_detection/ec2:
  detectors: [env, ec2]
  timeout: 2s
  override: false
  ec2:
    tags:
      - ^tag1$
      - ^tag2$

resource_detection/ecs:
  detectors: [env, ecs]
  timeout: 2s
  override: false

resource_detection/lambda:
  detectors: [env, lambda]
  timeout: 2s
  override: false

resource_detection/system:
  detectors: [env, system]
  timeout: 2s
  override: false
  system:
    hostname_sources: [os]

resource_detection/docker:
  detectors: [env, docker]
  timeout: 2s
  override: false

resource_detection/azure:
  detectors: [env, azure]
  timeout: 2s
  override: false

resource_detection/heroku:
  detectors: [env, heroku]
  timeout: 2s
  override: false

resource_detection/refresh:
  detectors: [system]
  timeout: 2s
  override: false
  refresh_interval: 5s

resource_detection/invalid:
  detectors: [env, system]
  timeout: 2s
  override: false
  system:
    hostname_sources: [invalid_source]

resource_detection/fail_on_missing_metadata:
  detectors: [gcp, azure, ec2]
  fail_on_missing_metadata: true
  timeout: 5s
  override: false

resource_detection/resourceattributes:
  detectors: [system, ec2]
  timeout: 2s
  override: false
  ec2:
    resource_attributes:
      host.name:
        enabled: false
      host.id:
        enabled: false
      host.type:
        enabled: false
  system:
    resource_attributes:
      os.type:
        enabled: false

config.yaml (testdata)

exporters:
  otlp:
    endpoint: host.docker.internal:4317
    tls:
      insecure: true
extensions:
  health_check:
    endpoint: 0.0.0.0:13133
processors:
  resource_detection:
    detectors: [docker]
    timeout: 2s
    override: false
    docker:
      resource_attributes:
        container.name:
          enabled: true
        container.image.name:
          enabled: true
receivers:
  hostmetrics:
    collection_interval: 1s
    scrapers:
      cpu:
service:
  telemetry:
    logs:
      level: "debug"
  extensions:
    - health_check
  pipelines:
    metrics:
      receivers:
        - hostmetrics
      processors:
        - resource_detection
      exporters:
        - otlp

Last generated: 2026-08-24

​Resourcedetection Processor

​Supported Telemetry

​Overview

​Retry configuration

​Supported detectors

​Environment Variable

​System metadata

​Hostname Sources

dns

os

cname

lookup

​Docker metadata

​Docker Socket Permissions

​Heroku metadata

​GCP Metadata

​GCE Metadata

​GKE Metadata

​Google Cloud Run Services Metadata

​Cloud Run Jobs Metadata

​Cloud Run Worker Pools Metadata

​Google Cloud Functions Metadata

​Google App Engine Metadata

​AWS EC2

​Amazon ECS

​Amazon Elastic Beanstalk

​Migrating to the current deployment semantic conventions

​Amazon EKS

​Cluster Name

​Node Name Env Variable

​AWS Lambda

​Azure

​Azure AKS

​Cluster Name

​Azure Container Apps

​Consul

​Kubeadm Metadata

​Oracle Cloud Infrastructure (OCI) metadata

​K8S API Metadata

​Example using the default node_from_env_var option:

​Example using a custom variable node_from_env_var option:

​OpenShift

​Dynatrace

​Hetzner

​Akamai

​Scaleway

​Upcloud

​Vultr

​Digital Ocean

​Openstack Nova

​Alibaba Cloud ECS

​Tencent Cloud CVM

​IBM Cloud VPC

​IBM Cloud Classic

​Configuration

​Using the refresh_interval parameter

​Using the fail_on_missing_metadata parameter

​Performance

​Benchmark Tests

​Internal Telemetry

​Ordering

​AWS

​Attributes

​Configuration

​config.yaml (testdata)

​config.yaml (testdata)

Resourcedetection Processor

Supported Telemetry

Overview

Retry configuration

Supported detectors

Environment Variable

System metadata

Hostname Sources

Docker metadata

Docker Socket Permissions

Heroku metadata

GCP Metadata

GCE Metadata

GKE Metadata

Google Cloud Run Services Metadata

Cloud Run Jobs Metadata

Cloud Run Worker Pools Metadata

Google Cloud Functions Metadata

Google App Engine Metadata

AWS EC2

Amazon ECS

Amazon Elastic Beanstalk

Migrating to the current deployment semantic conventions

Amazon EKS

Cluster Name

Node Name Env Variable

AWS Lambda

Azure

Azure AKS

Cluster Name

Azure Container Apps

Consul

Kubeadm Metadata

Oracle Cloud Infrastructure (OCI) metadata

K8S API Metadata

Example using the default `node_from_env_var` option:

Example using a custom variable `node_from_env_var` option:

OpenShift

Dynatrace

Hetzner

Akamai

Scaleway

Upcloud

Vultr

Digital Ocean

Openstack Nova

Alibaba Cloud ECS

Tencent Cloud CVM

IBM Cloud VPC

IBM Cloud Classic

Configuration

Using the `refresh_interval` parameter

Using the `fail_on_missing_metadata` parameter

Performance

Benchmark Tests

Internal Telemetry

Ordering

AWS

Attributes

Configuration

config.yaml (testdata)

config.yaml (testdata)