Resourcedetection Processor

Available in: contrib, k8s Maintainers: @Aneurysm9, @dashpole 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.

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:
  resourcedetection/env:
    detectors: [env]
    timeout: 2s
    override: false

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:
  resourcedetection/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. Example:

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

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:
  resourcedetection/heroku:
    detectors: [env, heroku]
    timeout: 2s
    override: false

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:
  resourcedetection/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 (only for regional GKE clusters; 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; only when workload identity is disabled)

One known issue is when GKE workload identity is enabled, the GCE metadata endpoints won’t be available, thus the GKE resource detector won’t be able to determine host.name. In that case, users are encouraged to set host.name from either:

node.name through the downward API with the env detector
obtaining 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 (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”)

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:
  resourcedetection/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:
  resourcedetection/ec2:
    detectors: ["ec2"]
    ec2:
      max_attempts: 10
      max_backoff: 5m

The EC2 detector will report an error in logs if the EC2 metadata endpoint is unavailable. You can configure the detector to instead fail with this flag:

processors:
  resourcedetection/ec2:
    detectors: ["ec2"]
    ec2:
      fail_on_missing_metadata: true

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:
  resourcedetection/ecs:
    detectors: [env, ecs]
    timeout: 2s
    override: false

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:
  resourcedetection/elastic_beanstalk:
    detectors: [env, elastic_beanstalk]
    timeout: 2s
    override: false

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:
  resourcedetection/eks:
    detectors: [env, eks]
    timeout: 15s
    override: false

Cluster Name

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

processors:
  resourcedetection/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:
  resourcedetection/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:
  resourcedetection/lambda:
    detectors: [env, lambda]
    timeout: 0.2s
    override: false

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:
  resourcedetection/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:
  resourcedetection/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:
  resourcedetection/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:
  resourcedetection/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.

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:
  resourcedetection/consul:
    detectors: [env, consul]
    timeout: 2s
    override: false

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.

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:
  resourcedetection/oraclecloud:
    detectors: [env, oraclecloud]
    timeout: 2s
    override: false

Populated resource attributes:

cloud.provider
cloud.platform
cloud.region
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 Node Metadata

Queries the K8S api server to retrieve node resource attributes. The list of the populated resource attributes can be found at k8snode Detector Resource Attributes. The following permissions are required:

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

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:
  resourcedetection/k8snode:
    detectors: [k8snode]

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:
  resourcedetection/k8snode:
    detectors: [k8snode]
    k8snode:
      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:
  resourcedetection/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:
  resourcedetection/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:
  resourcedetection/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:
  resourcedetection/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:
  resourcedetection/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:
  resourcedetection/upcloud:
    detectors: ["upcloud"]

The Upcloud detector will report an error in logs if the metadata endpoint is unavailable. You can configure the detector to instead fail with this flag:

processors:
  resourcedetection/upcloud:
    detectors: ["upcloud"]
    upcloud:
      fail_on_missing_metadata: true

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:
  resourcedetection/vultr:
    detectors: ["vultr"]

The Vultr detector will report an error in logs if the metadata endpoint is unavailable. You can configure the detector to instead fail with this flag:

processors:
  resourcedetection/vultr:
    detectors: ["vultr"]
    vultr:
      fail_on_missing_metadata: true

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:
  resourcedetection/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:
  resourcedetection/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.*$

The Nova detector will report an error in logs if the metadata endpoint is unavailable. You can configure the detector to instead fail with this flag:

processors:
  resourcedetection/nova:
    detectors: ["nova"]
    nova:
      fail_on_missing_metadata: true

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:
  resourcedetection/alibaba_ecs:
    detectors: ["alibaba_ecs"]

The Alibaba Cloud ECS detector will report an error in logs if the metadata endpoint is unavailable. You can configure the detector to instead fail with this flag:

processors:
  resourcedetection/alibaba_ecs:
    detectors: ["alibaba_ecs"]
    alibaba_ecs:
      fail_on_missing_metadata: true

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:
  resourcedetection/tencent_cvm:
    detectors: ["tencent_cvm"]

The Tencent Cloud CVM detector will report an error in logs if the metadata endpoint is unavailable. You can configure the detector to instead fail with this flag:

processors:
  resourcedetection/tencent_cvm:
    detectors: ["tencent_cvm"]
    tencent_cvm:
      fail_on_missing_metadata: true

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:
  resourcedetection/ibmcloud_vpc:
    detectors: [env, ibmcloud_vpc]
    timeout: 2s
    override: false

IBM Cloud VPC custom configuration example:

processors:
  resourcedetection/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:
  resourcedetection/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>

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

resourcedetection:
  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).

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.

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.

Configuration

config.yaml (testdata)

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

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

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

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

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

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

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

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

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

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

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

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

resourcedetection/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:
  resourcedetection:
    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:
        - resourcedetection
      exporters:
        - otlp

Last generated: 2026-04-13

Collector components

​Resourcedetection Processor

​Supported Telemetry

​Overview

​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

​Google Cloud Functions Metadata

​Google App Engine Metadata

​AWS EC2

​Amazon ECS

​Amazon Elastic Beanstalk

​Amazon EKS

​Cluster Name

​Node Name Env Variable

​AWS Lambda

​Azure

​Azure AKS

​Cluster Name

​Consul

​Kubeadm Metadata

​Oracle Cloud Infrastructure (OCI) metadata

​K8S Node 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

​Performance

​Benchmark Tests

​Ordering

​AWS

​Configuration

​config.yaml (testdata)

​config.yaml (testdata)

Resourcedetection Processor

Supported Telemetry

Overview

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

Google Cloud Functions Metadata

Google App Engine Metadata

AWS EC2

Amazon ECS

Amazon Elastic Beanstalk

Amazon EKS

Cluster Name

Node Name Env Variable

AWS Lambda

Azure

Azure AKS

Cluster Name

Consul

Kubeadm Metadata

Oracle Cloud Infrastructure (OCI) metadata

K8S Node 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

Performance

Benchmark Tests

Ordering

AWS

Configuration

config.yaml (testdata)

config.yaml (testdata)