resourcedetectionprocessor

README

Resource Detection Processor

Status
Stability	development: profiles
	beta: traces, metrics, logs
Distributions	contrib, k8s
Issues
Code coverage
Code Owners	@Aneurysm9, @dashpole, @paulojmdias | Seeking more code owners!

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 component 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.

On GKE, the machine type of the node is not available from the metadata server, so the detector fetches host.type from the Compute API when the host.type resource attribute is enabled (the default). This requires the runtime identity to have the compute.instances.get permission (covered by roles/compute.viewer); without it, the attribute is skipped and the failure is logged. To avoid the API call entirely, disable the attribute with resource_attributes: { host.type: { enabled: false } }.

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)
* host.type (machine type; requires the `compute.instances.get` permission, skipped otherwise)

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.

Note: When fail_on_missing_metadata is true, this detector returns an error if the instance ID or the instance identity document cannot be retrieved from IMDS. When false (default), those failures are logged and an empty resource is returned. This matters on hosts whose metadata service implements the EC2-compatible meta-data tree but not the AWS-specific dynamic/instance-identity tree, such as OpenStack Nova based clouds. A dedicated OpenStack Nova detector is also available. The same applies to the hostname: when fail_on_missing_metadata is true, a hostname that cannot be retrieved results in an error, otherwise the failure is logged and the resource is returned without the host.name attribute.

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.

Azure App Service

Uses the Azure App Service injected environment variables to retrieve related resource attributes.

Note: Azure Functions apps run on the same App Service infrastructure but are not detected by this detector.

The list of the populated resource attributes can be found at Azure App Service Detector Resource Attributes.

Example:

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

Note: When fail_on_missing_metadata is true, this detector returns an error if the WEBSITE_SITE_NAME, WEBSITE_RESOURCE_GROUP or WEBSITE_OWNER_NAME environment variables are not set (not running on Azure App Service), or if FUNCTIONS_WORKER_RUNTIME is set (running as an Azure Functions app), instead of silently returning an empty resource.

Azure Functions

Uses the Azure Functions injected environment variables to retrieve related resource attributes. Detection is enabled when either FUNCTIONS_WORKER_RUNTIME or FUNCTIONS_EXTENSION_VERSION is set.

The list of populated resource attributes can be found at Azure Functions Detector Resource Attributes.

Example:

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

Azure Functions Flex Consumption plans do not expose WEBSITE_RESOURCE_GROUP, so azure.resource_group.name and cloud.resource_id will be absent.

deployment.environment.name is disabled by default. Azure sets WEBSITE_SLOT_NAME to Production on apps without deployment slots regardless of the actual user's intent. Users should enable this attribute if they are using deployment slots, want the Production label, or are setting their own value for the environment.

If this detector is deployed as a sidecar, consider setting override to false to prevent overwriting values such as service.name.

Note: When fail_on_missing_metadata is true, this detector returns an error if neither FUNCTIONS_WORKER_RUNTIME nor FUNCTIONS_EXTENSION_VERSION is set (not running on Azure Functions), 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 the key:value pairs allowlisted in meta from consul metadata into label:labelvalue pairs.

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

The consul detector accepts the following settings. Unset fields fall back to the Consul API client defaults, including the CONSUL_HTTP_* environment variables.

Name	Type	Required	Default	Docs
address	string	No	127.0.0.1:8500	Address of the Consul agent.
datacenter	string	No	agent's datacenter	Datacenter to query.
token	string	No		Per-request ACL token that overrides the agent's default token. Only required when the Consul ACL system is enabled.
token_file	string	No		File containing the ACL token. Read once at startup. Only required when the Consul ACL system is enabled.
namespace	string	No		Namespace sent with each request.
meta	map	No		Allowlist of node metadata keys to emit as resource attributes. Keys not listed here are dropped.

processors:
  resource_detection/consul:
    detectors: [consul]
    consul:
      address: "127.0.0.1:8500"
      datacenter: "dc1"
      token_file: /etc/consul/token
      meta:
        rack: ""
        zone: ""

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.

Digital Ocean 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

# a list of resource detectors to run, valid options are: "env", "system", "gcp", "ec2", "ecs", "elastic_beanstalk", "eks", "lambda", "azure", "aks", "azureappservice", "azurecontainerapps", "azurefunctions", "heroku", "openshift", "dynatrace", "consul", "docker", "k8s_api", "k8snode" (deprecated, use "k8s_api"), "kubeadm", "hetzner", "akamai", "scaleway", "vultr", "oraclecloud", "digitalocean", "nova", "upcloud", "alibaba_ecs", "tencent_cvm", "ibmcloud_vpc", "ibmcloud_classic"
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>
# bounds detection time (see Retry configuration); defaults to 5s
timeout: <duration>
# retry settings for failed detections, see Retry configuration
retry: <configretry.BackOffConfig>

The processor also accepts the confighttp client settings at the top level (for example tls or headers). timeout applies to every detector; the other HTTP client settings are currently used only by the ec2 detector.

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 supported signals. The benchmarks measure the performance of the processor under different configurations:

• Traces: BenchmarkConsumeTracesDefault and BenchmarkConsumeTracesAll
• Metrics: BenchmarkConsumeMetricsDefault and BenchmarkConsumeMetricsAll
• Logs: BenchmarkConsumeLogsDefault and BenchmarkConsumeLogsAll
• Profiles: BenchmarkConsumeProfilesDefault and BenchmarkConsumeProfilesAll

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 processor are documented in config.go with detailed sample configurations in testdata/config.yaml.

Documentation

Overview

package resourcedetectionprocessor implements a processor which 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.

Index

• func NewFactory() processor.Factory
• type Config
  • func (cfg *Config) Validate() error
• type DetectorConfig
  • func (d *DetectorConfig) GetConfigFromType(detectorType internal.DetectorType) internal.DetectorConfig

Functions

func NewFactory

func NewFactory() processor.Factory

NewFactory creates a new factory for ResourceDetection processor.

Types

type Config

type Config struct {
	// Detectors is an ordered list of named detectors that should be
	// run to attempt to detect resource information.
	Detectors []string `mapstructure:"detectors"`
	// Override indicates whether any existing resource attributes
	// should be overridden or preserved. Defaults to true.
	Override bool `mapstructure:"override"`
	// DetectorConfig is a list of settings specific to all detectors
	DetectorConfig DetectorConfig `mapstructure:",squash"`
	// HTTP client settings for the detector
	// Timeout default is 5s
	ClientConfig confighttp.ClientConfig `mapstructure:",squash"`
	// If > 0, periodically re-run detection for all configured detectors.
	// When 0 (default), no periodic refresh occurs.
	RefreshInterval time.Duration `mapstructure:"refresh_interval"`
	// FailOnMissingMetadata controls whether network-based detectors treat an
	// unreachable metadata service as a hard failure. When true, affected detectors
	// return an error instead of silently returning an empty resource, enabling the
	// processor's retry mechanism to wait until the metadata service becomes available
	// (e.g., during GKE/AKS node startup races).
	// Supersedes the per-detector fail_on_missing_metadata fields (now deprecated).
	// Default: false (backward compatible).
	FailOnMissingMetadata bool `mapstructure:"fail_on_missing_metadata"`
	// Retry controls retry/backoff for each detection attempt. Set Enabled=false
	// to perform a single attempt per detector with no retries.
	Retry configretry.BackOffConfig `mapstructure:"retry"`
}

Config defines configuration for Resource processor.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate rejects configurations that would let a hung detector block the pipeline forever: with retry enabled, at least one of the HTTP client timeout or the retry budget must be finite so detection always terminates.

type DetectorConfig

type DetectorConfig struct {
	// AlibabaECSConfig contains user-specified configurations for the Alibaba Cloud ECS detector
	AlibabaECSConfig alibabaecs.Config `mapstructure:"alibaba_ecs"`

	// EC2Config contains user-specified configurations for the EC2 detector
	EC2Config ec2.Config `mapstructure:"ec2"`

	// ECSConfig contains user-specified configurations for the ECS detector
	ECSConfig ecs.Config `mapstructure:"ecs"`

	// EKSConfig contains user-specified configurations for the EKS detector
	EKSConfig eks.Config `mapstructure:"eks"`

	// Elasticbeanstalk contains user-specified configurations for the elasticbeanstalk detector
	ElasticbeanstalkConfig elasticbeanstalk.Config `mapstructure:"elasticbeanstalk"`

	// Lambda contains user-specified configurations for the lambda detector
	LambdaConfig lambda.Config `mapstructure:"lambda"`

	// Azure contains user-specified configurations for the azure detector
	AzureConfig azure.Config `mapstructure:"azure"`

	// Aks contains user-specified configurations for the aks detector
	AksConfig aks.Config `mapstructure:"aks"`

	// AzureAppServiceConfig contains user-specified configurations for the Azure App Service detector
	AzureAppServiceConfig appservice.Config `mapstructure:"azureappservice"`

	// AzureContainerAppsConfig contains user-specified configurations for the Azure Container Apps detector
	AzureContainerAppsConfig containerapps.Config `mapstructure:"azurecontainerapps"`

	// AzureFunctionsConfig contains user-specified configurations for the Azure Functions detector
	AzureFunctionsConfig functions.Config `mapstructure:"azurefunctions"`

	// ConsulConfig contains user-specified configurations for the Consul detector
	ConsulConfig consul.Config `mapstructure:"consul"`

	// DigitalOceanConfig contains user-specified configurations for the digitalocean detector
	DigitalOceanConfig digitalocean.Config `mapstructure:"digitalocean"`

	// DockerConfig contains user-specified configurations for the docker detector
	DockerConfig docker.Config `mapstructure:"docker"`

	// GcpConfig contains user-specified configurations for the gcp detector
	GcpConfig gcp.Config `mapstructure:"gcp"`

	// HerokuConfig contains user-specified configurations for the heroku detector
	HerokuConfig heroku.Config `mapstructure:"heroku"`

	// HetznerConfig contains user-specified configurations for the hetzner detector
	HetznerConfig hetzner.Config `mapstructure:"hetzner"`

	// IBMCloudClassicConfig contains user-specified configurations for the IBM Cloud Classic detector
	IBMCloudClassicConfig ibmcloudclassic.Config `mapstructure:"ibmcloud_classic"`

	// IBMCloudVPCConfig contains user-specified configurations for the IBM Cloud VPC detector
	IBMCloudVPCConfig ibmcloudvpc.Config `mapstructure:"ibmcloud_vpc"`

	// SystemConfig contains user-specified configurations for the System detector
	SystemConfig system.Config `mapstructure:"system"`

	// OpenShift contains user-specified configurations for the OpenShift detector
	OpenShiftConfig openshift.Config `mapstructure:"openshift"`

	// OpenStackNovaConfig contains user-specified configurations for the OpenStackNova detector
	OpenStackNovaConfig nova.Config `mapstructure:"nova"`

	// OracleCloud contains user-specified configurations for the OracleCloud detector
	OracleCloudConfig oraclecloud.Config `mapstructure:"oraclecloud"`

	// K8SAPIConfig contains user-specified configurations for the K8S API detector
	K8SAPIConfig k8sapi.Config `mapstructure:"k8s_api"`

	// K8SNodeConfig contains user-specified configurations for the K8SNode detector (deprecated: use K8SAPIConfig)
	K8SNodeConfig k8sapi.Config `mapstructure:"k8snode"`

	// Kubeadm contains user-specified configurations for the Kubeadm detector
	KubeadmConfig kubeadm.Config `mapstructure:"kubeadm"`

	// AkamaiConfig contains user-specified configurations for the akamai detector
	AkamaiConfig akamai.Config `mapstructure:"akamai"`

	// ScalewayConfig contains user-specified configurations for the scaleway detector
	ScalewayConfig scaleway.Config `mapstructure:"scaleway"`

	// TencentCVMConfig contains user-specified configurations for the Tencent Cloud CVM detector
	TencentCVMConfig tencentcvm.Config `mapstructure:"tencent_cvm"`

	// UpcloudConfig contains user-specified configurations for the upcloud detector
	UpcloudConfig upcloud.Config `mapstructure:"upcloud"`

	// VultrConfig contains user-specified configurations for the vultr detector
	VultrConfig vultr.Config `mapstructure:"vultr"`
}

DetectorConfig contains user-specified configurations unique to all individual detectors

func (*DetectorConfig) GetConfigFromType

func (d *DetectorConfig) GetConfigFromType(detectorType internal.DetectorType) internal.DetectorConfig