> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Resourcedetection

> OpenTelemetry processor for Resourcedetection

# Resourcedetection Processor

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`, `k8s`

**Maintainers:** [@Aneurysm9](https://github.com/Aneurysm9), [@dashpole](https://github.com/dashpole)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-beta-blue) ![Metrics](https://img.shields.io/badge/metrics-beta-green) ![Traces](https://img.shields.io/badge/traces-beta-orange)

## 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](https://github.com/open-telemetry/semantic-conventions/tree/main/docs/resource), 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:

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/system/documentation.md).

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:

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/docker/documentation.md).

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:

```yaml theme={null}
processors:
  resource_detection/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](../../receiver/dockerstatsreceiver/README.md#docker-socket-permissions).

For more information, see [issue #11791](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/11791).

### Heroku metadata

When [Heroku dyno metadata is active](https://devcenter.heroku.com/articles/dyno-metadata), 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](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/cloud-provider/heroku.md) under the [OpenTelemetry specification semantic conventions](https://github.com/open-telemetry/semantic-conventions).

The list of the populated resource attributes can be found at [Heroku Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/heroku/documentation.md).

```yaml theme={null}
processors:
  resource_detection/heroku:
    detectors: [env, heroku]
    timeout: 2s
    override: false
```

### GCP Metadata

Uses the [Google Cloud Client Libraries for Go](https://github.com/googleapis/google-cloud-go)
to read resource information from the [metadata server](https://cloud.google.com/compute/docs/storing-retrieving-metadata) 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:

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/gcp/documentation.md).

#### 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; 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](https://docs.aws.amazon.com/sdk-for-go/api/aws/ec2metadata/) to read resource information
from the [EC2 instance metadata API](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) to retrieve related resource attributes:

The list of the populated resource attributes can be found at [EC2 Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/aws/ec2/documentation.md).

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`](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeTags.html) 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)](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html),
which does not require any IAM permissions but requires [instance metadata tags to be enabled](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html#allow-access-to-tags-in-IMDS) 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:

```yaml theme={null}
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](https://github.com/awsdocs/aws-cli-user-guide/blob/a2393582590b64bd2a1d9978af15b350e1f9eb8e/doc_source/cli-configure-proxy.md#using-a-proxy-on-amazon-ec2-instances). 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](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/configure-retries-timeouts.html)

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:

```yaml theme={null}
processors:
  resource_detection/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:

```yaml theme={null}
processors:
  resource_detection/ec2:
    detectors: ["ec2"]
    ec2:
      fail_on_missing_metadata: true
```

### Amazon ECS

Queries the [Task Metadata Endpoint](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-metadata-endpoint.html) (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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/aws/ecs/documentation.md).

Example:

```yaml theme={null}
processors:
  resource_detection/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](https://docs.aws.amazon.com/elasticbeanstalk/latest/dg/environment-configuration-debugging.html).

The list of the populated resource attributes can be found at [Elastic Beanstalk Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/aws/elasticbeanstalk/documentation.md).

Example:

```yaml theme={null}
processors:
  resource_detection/elastic_beanstalk:
    detectors: [env, elastic_beanstalk]
    timeout: 2s
    override: false
```

### Amazon EKS

This detector reads resource information from the [EC2 instance metadata service](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) 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](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#-strong-kubernetes-api-v1-25-strong-)
and [EC2 API](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html) 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](https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html).

The list of the populated resource attributes can be found at [EKS Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/aws/eks/documentation.md).

Example:

```yaml theme={null}
processors:
  resource_detection/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:

```yaml theme={null}
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](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html).
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:

```yaml theme={null}
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.

```yaml theme={null}
        env:
          - name: K8S_NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
```

### AWS Lambda

Uses the AWS Lambda [runtime environment variables](https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html#configuration-envvars-runtime)
to retrieve related resource attributes.

The list of the populated resource attributes can be found at [Lambda Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/aws/lambda/documentation.md).

Example:

```yaml theme={null}
processors:
  resource_detection/lambda:
    detectors: [env, lambda]
    timeout: 0.2s
    override: false
```

### Azure

Queries the [Azure Instance Metadata Service](https://aka.ms/azureimds) to retrieve related attributes.

The list of the populated resource attributes can be found at [Azure Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/azure/documentation.md).

Example:

```yaml theme={null}
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:

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/azure/aks/documentation.md).

```yaml theme={null}
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:

```yaml theme={null}
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.

### Consul

Queries a [consul agent](https://www.consul.io/docs/agent) and reads its [configuration endpoint](https://www.consul.io/api-docs/agent#read-configuration) to retrieve related resource attributes:

The list of the populated resource attributes can be found at [Consul Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/consul/documentation.md).

In addition to:

* *exploded consul metadata* - reads all key:value pairs in [consul metadata](https://www.consul.io/docs/agent/options#_node_meta) into label:labelvalue pairs.

```yaml theme={null}
processors:
  resource_detection/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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/kubeadm/documentation.md).

***

### 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](https://docs.oracle.com/en-us/iaas/Content/Compute/Tasks/gettingmetadata.htm)
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/oraclecloud/documentation.md).

Example:

```yaml theme={null}
processors:
  resource_detection/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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/oraclecloud/documentation.md) for detailed attribute definitions.

***

The following permissions are required:

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/k8sapi/documentation.md).

The following permissions are required:

```yaml theme={null}
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:

```yaml theme={null}
processors:
  resource_detection:
    detectors: [k8s_api]
```

and add this to your workload:

```yaml theme={null}
        env:
          - name: K8S_NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
```

#### Example using a custom variable `node_from_env_var` option:

```yaml theme={null}
processors:
  resource_detection:
    detectors: [k8s_api]
    k8s_api:
      node_from_env_var: "my_custom_var"
```

and add this to your workload:

```yaml theme={null}
        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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/openshift/documentation.md).

The following permissions are required:

```yaml theme={null}
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:

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector/blob/main/config/configtls/README.md) 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:

```yaml theme={null}
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](https://docs.hetzner.cloud/reference/cloud#server-metadata) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/hetzner/documentation.md).

Hetzner custom configuration example:

```yaml theme={null}
processors:
  resource_detection/hetzner:
    detectors: ["hetzner"]
```

### Akamai

Uses the [Akamai metadata API](https://techdocs.akamai.com/cloud-computing/docs/metadata-service-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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/akamai/documentation.md).

Akamai custom configuration example:

```yaml theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/scaleway/documentation.md).

Scaleway custom configuration example:

```yaml theme={null}
processors:
  resource_detection/scaleway:
    detectors: ["scaleway"]
```

### Upcloud

Uses the [Upcloud metadata API](https://upcloud.com/docs/guides/upcloud-metadata-service/) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/upcloud/documentation.md).

Upcloud custom configuration example:

```yaml theme={null}
processors:
  resource_detection/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:

```yaml theme={null}
processors:
  resource_detection/upcloud:
    detectors: ["upcloud"]
    upcloud:
      fail_on_missing_metadata: true
```

### Vultr

Uses the [Vultr metadata API](https://www.vultr.com/metadata/) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/vultr/documentation.md).

Vultr custom configuration example:

```yaml theme={null}
processors:
  resource_detection/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:

```yaml theme={null}
processors:
  resource_detection/vultr:
    detectors: ["vultr"]
    vultr:
      fail_on_missing_metadata: true
```

### Digital Ocean

Uses the [Digital Ocean metadata API](https://docs.digitalocean.com/reference/api/metadata/) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/digitalocean/documentation.md).

Akamai custom configuration example:

```yaml theme={null}
processors:
  resource_detection/digitalocean:
    detectors: ["digitalocean"]
```

### Openstack Nova

Uses the [OpenStack Nova metadata API](https://docs.openstack.org/nova/latest/user/metadata.html) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/openstack/nova/documentation.md).

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:

```yaml theme={null}
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.*$
```

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:

```yaml theme={null}
processors:
  resource_detection/nova:
    detectors: ["nova"]
    nova:
      fail_on_missing_metadata: true
```

### Alibaba Cloud ECS

Uses the [Alibaba Cloud metadata API](https://www.alibabacloud.com/help/en/ecs/user-guide/view-instance-metadata/?spm=a2c63.p38356.help-menu-25365.d_0_1_3_4_6.7d2848cfJpcLdU#393b14378evdm) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/alibaba/ecs/documentation.md).

Alibaba Cloud ECS custom configuration example:

```yaml theme={null}
processors:
  resource_detection/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:

```yaml theme={null}
processors:
  resource_detection/alibaba_ecs:
    detectors: ["alibaba_ecs"]
    alibaba_ecs:
      fail_on_missing_metadata: true
```

### Tencent Cloud CVM

Uses the [Tencent Cloud metadata API](https://www.tencentcloud.com/document/product/213/4934) 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/tencent/cvm/documentation.md).

Tencent Cloud CVM custom configuration example:

```yaml theme={null}
processors:
  resource_detection/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:

```yaml theme={null}
processors:
  resource_detection/tencent_cvm:
    detectors: ["tencent_cvm"]
    tencent_cvm:
      fail_on_missing_metadata: true
```

### IBM Cloud VPC

Queries the [IBM Cloud VPC Instance Metadata Service](https://cloud.ibm.com/apidocs/vpc-metadata/latest#get-instance) to retrieve resource attributes from the instance.

The list of the populated resource attributes can be found at [IBM Cloud VPC Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/ibmcloud/vpc/documentation.md).

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](https://cloud.ibm.com/docs/vpc?topic=vpc-imd-configure-service\&interface=ui#secure-access-ui)
> state is toggled while the collector is running, update the `protocol` configuration
> value accordingly and restart the collector.

Example:

```yaml theme={null}
processors:
  resource_detection/ibmcloud_vpc:
    detectors: [env, ibmcloud_vpc]
    timeout: 2s
    override: false
```

IBM Cloud VPC custom configuration example:

```yaml theme={null}
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](https://sldn.softlayer.com/reference/services/SoftLayer_Resource_Metadata/) to retrieve resource attributes from the instance.

The list of the populated resource attributes can be found at [IBM Cloud Classic Detector Resource Attributes](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/internal/ibmcloud/classic/documentation.md).

Example:

```yaml theme={null}
processors:
  resource_detection/ibmcloud_classic:
    detectors: [env, ibmcloud_classic]
    timeout: 2s
    override: false
```

## Configuration

```yaml theme={null}

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:

```yaml theme={null}
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).

## 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:

```bash theme={null}
go test -bench=. -benchmem
```

For the latest benchmark results, see the [GitHub Actions workflow runs](https://github.com/open-telemetry/opentelemetry-collector-contrib/actions/workflows/build-and-test.yml).

## 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](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/config.go)
with detailed sample configurations in [testdata/config.yaml](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor/testdata/config.yaml).

## Configuration

### config.yaml (testdata)

```yaml theme={null}
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/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/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)

```yaml theme={null}
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-07-06*