Menu

This is documentation for the next version of Alloy. For the latest stable release, go to the latest version.

Documentationbreadcrumb arrow Grafana Alloybreadcrumb arrow Referencebreadcrumb arrow Componentsbreadcrumb arrow otelcolbreadcrumb arrow otelcol.processor.resourcedetection
Open source

otelcol.processor.resourcedetection

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

Note

otelcol.processor.resourcedetection is a wrapper over the upstream OpenTelemetry Collector Contrib resourcedetection processor. If necessary, bug reports or feature requests are redirected to the upstream repository.

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

Usage

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

Arguments

otelcol.processor.resourcedetection supports the following arguments:

NameTypeDescriptionDefaultRequired
detectorslist(string)An ordered list of named detectors used to detect resource information.["env"]no
overrideboolConfigures whether existing resource attributes should be overridden or preserved.trueno
timeoutdurationTimeout by which all specified detectors must complete."5s"no

detectors could contain the following values:

  • env
  • ec2
  • ecs
  • eks
  • elasticbeanstalk
  • lambda
  • azure
  • aks
  • consul
  • docker
  • gcp
  • heroku
  • system
  • openshift
  • kubernetes_node

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

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

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

The following order is recommended for AWS:

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

Blocks

The following blocks are supported inside the definition of otelcol.processor.resourcedetection:

HierarchyBlockDescriptionRequired
outputoutputConfigures where to send received telemetry data.yes
ec2ec2no
ecsecsno
ekseksno
elasticbeanstalkelasticbeanstalkno
lambdalambdano
azureazureno
aksaksno
consulconsulno
dockerdockerno
gcpgcpno
herokuherokuno
systemsystemno
openshiftopenshiftno
kubernetes_nodekubernetes_nodeno
debug_metricsdebug_metricsConfigures the metrics that this component generates to monitor its state.no

output

The output block configures a set of components to forward resulting telemetry data to.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
logslist(otelcol.Consumer)List of consumers to send logs to.[]no
metricslist(otelcol.Consumer)List of consumers to send metrics to.[]no
traceslist(otelcol.Consumer)List of consumers to send traces to.[]no

You must specify the output block, but all its arguments are optional. By default, telemetry data is dropped. Configure the metrics, logs, and traces arguments accordingly to send telemetry data to other components.

debug_metrics block

The debug_metrics block configures the metrics that this component generates to monitor its state.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
disable_high_cardinality_metricsbooleanWhether to disable certain high cardinality metrics.trueno
levelstringControls the level of detail for metrics emitted by the wrapped collector."detailed"no

disable_high_cardinality_metrics is the Grafana Alloy equivalent to the telemetry.disableHighCardinalityMetrics feature gate in the OpenTelemetry Collector. It removes attributes that could cause high cardinality metrics. For example, attributes with IP addresses and port numbers in metrics about HTTP and gRPC connections are removed.

Note

If configured, disable_high_cardinality_metrics only applies to otelcol.exporter.* and otelcol.receiver.* components.

level is the Alloy equivalent to the telemetry.metrics.level feature gate in the OpenTelemetry Collector. Possible values are "none", "basic", "normal" and "detailed".

ec2

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

The ec2 block supports the following attributes:

AttributeTypeDescriptionDefaultRequired
tagslist(string)A list of regular expressions to match against tag keys of an EC2 instance.[]no

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

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

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

The ec2 block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no
ec2 > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.account.idToggles the cloud.account.id resource attribute.
Sets enabled to true by default.
no
cloud.availability_zoneToggles the cloud.availability_zone resource attribute.
Sets enabled to true by default.
no
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
cloud.regionToggles the cloud.region resource attribute.
Sets enabled to true by default.
no
host.idToggles the host.id resource attribute.
Sets enabled to true by default.
no
host.image.idToggles the host.image.id resource attribute.
Sets enabled to true by default.
no
host.nameToggles the host.name resource attribute.
Sets enabled to true by default.
no
host.typeToggles the host.type resource attribute.
Sets enabled to true by default.
no

ecs

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

The ecs block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

ecs > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
aws.ecs.cluster.arnToggles the aws.ecs.cluster.arn resource attribute.
Sets enabled to true by default.
no
aws.ecs.launchtypeToggles the aws.ecs.launchtype resource attribute.
Sets enabled to true by default.
no
aws.ecs.task.arnToggles the aws.ecs.task.arn resource attribute.
Sets enabled to true by default.
no
aws.ecs.task.familyToggles the aws.ecs.task.family resource attribute.
Sets enabled to true by default.
no
aws.ecs.task.idToggles the aws.ecs.task.id resource attribute.
Sets enabled to true by default.
no
aws.ecs.task.revisionToggles the aws.ecs.task.revision resource attribute.
Sets enabled to true by default.
no
aws.log.group.arnsToggles the aws.log.group.arns resource attribute.
Sets enabled to true by default.
no
aws.log.group.namesToggles the aws.log.group.names resource attribute.
Sets enabled to true by default.
no
aws.log.stream.arnsToggles the aws.log.stream.arns resource attribute.
Sets enabled to true by default.
no
aws.log.stream.namesToggles the aws.log.stream.names resource attribute.
Sets enabled to true by default.
no
cloud.account.idToggles the cloud.account.id resource attribute.
Sets enabled to true by default.
no
cloud.availability_zoneToggles the cloud.availability_zone resource attribute.
Sets enabled to true by default.
no
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
cloud.regionToggles the cloud.region resource attribute.
Sets enabled to true by default.
no

eks

The eks block adds resource attributes for Amazon EKS.

The eks block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

eks > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
k8s.cluster.nameToggles the k8s.cluster.name resource attribute.
Sets enabled to false by default.
no

Example values:

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

elasticbeanstalk

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

The elasticbeanstalk block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

elasticbeanstalk > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
deployment.envirToggles the deployment.envir resource attribute.
Sets enabled to true by default.
no
service.instanceToggles the service.instance resource attribute.
Sets enabled to true by default.
no
service.versionToggles the service.version resource attribute.
Sets enabled to true by default.
no

Example values:

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

lambda

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

The lambda block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

lambda > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
aws.log.group.namesToggles the aws.log.group.names resource attribute.
Sets enabled to true by default.
no
aws.log.stream.namesToggles the aws.log.stream.names resource attribute.
Sets enabled to true by default.
no
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
cloud.regionToggles the cloud.region resource attribute.
Sets enabled to true by default.
no
faas.instanceToggles the faas.instance resource attribute.
Sets enabled to true by default.
no
faas.max_memoryToggles the faas.max_memory resource attribute.
Sets enabled to true by default.
no
faas.nameToggles the faas.name resource attribute.
Sets enabled to true by default.
no
faas.versionToggles the faas.version resource attribute.
Sets enabled to true by default.
no

Cloud semantic conventions:

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

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

  • faas.name: $AWS_LAMBDA_FUNCTION_NAME
  • faas.version: $AWS_LAMBDA_FUNCTION_VERSION
  • faas.instance: $AWS_LAMBDA_LOG_STREAM_NAME
  • faas.max_memory: $AWS_LAMBDA_FUNCTION_MEMORY_SIZE

AWS Logs semantic conventions:

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

azure

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

The azure block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

The azure block supports the following attributes:

AttributeTypeDescriptionDefaultRequired
tagslist(string)A list of regex’s to match tag keys to add as resource attributes can be specified.[]no

azure > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
azure.resourcegroup.nameToggles the azure.resourcegroup.name resource attribute.
Sets enabled to true by default.
no
azure.vm.nameToggles the azure.vm.name resource attribute.
Sets enabled to true by default.
no
azure.vm.scaleset.nameToggles the azure.vm.scaleset.name resource attribute.
Sets enabled to true by default.
no
azure.vm.sizeToggles the azure.vm.size resource attribute.
Sets enabled to true by default.
no
cloud.account.idToggles the cloud.account.id resource attribute.
Sets enabled to true by default.
no
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
cloud.regionToggles the cloud.region resource attribute.
Sets enabled to true by default.
no
host.idToggles the host.id resource attribute.
Sets enabled to true by default.
no
host.nameToggles the host.name resource attribute.
Sets enabled to true by default.
no

Example values:

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

aks

The aks block adds resource attributes related to Azure AKS.

The aks block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

aks > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
k8s.cluster.nameToggles the k8s.cluster.name resource attribute.
Sets enabled to false by default.
no

Example values:

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

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

Example:

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

The cluster name is detected if it 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, because Azure will not allow users to create multiple clusters with the same infrastructure resource group name.

consul

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

The consul block supports the following attributes:

AttributeTypeDescriptionDefaultRequired
addressstringThe address of the Consul server""no
datacenterstringDatacenter to use. If not provided, the default agent datacenter is used.""no
tokensecretA per-request ACL token which overrides the Consul agent’s default (empty) token.""no
namespacestringThe name of the namespace to send along for the request.""no
metalist(string)Allowlist of Consul Metadata keys to use as resource attributes.[]no

token is only required if Consul’s ACL System is enabled.

The consul block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

consul > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.regionToggles the cloud.region resource attribute.
Sets enabled to true by default.
no
host.idToggles the host.id resource attribute.
Sets enabled to true by default.
no
host.nameToggles the host.name resource attribute.
Sets enabled to true by default.
no

docker

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

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

The docker block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

docker > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
host.nameToggles the host.name resource attribute.
Sets enabled to true by default.
no
os.typeToggles the os.type resource attribute.
Sets enabled to true by default.
no

gcp

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

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

The gcp block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

gcp > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.account.idToggles the cloud.account.id resource attribute.
Sets enabled to true by default.
no
cloud.availability_zoneToggles the cloud.availability_zone resource attribute.
Sets enabled to true by default.
no
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
cloud.regionToggles the cloud.region resource attribute.
Sets enabled to true by default.
no
faas.idToggles the faas.id resource attribute.
Sets enabled to true by default.
no
faas.instanceToggles the faas.instance resource attribute.
Sets enabled to true by default.
no
faas.nameToggles the faas.name resource attribute.
Sets enabled to true by default.
no
faas.versionToggles the faas.version resource attribute.
Sets enabled to true by default.
no
gcp.cloud_run.job.executionToggles the gcp.cloud_run.job.execution resource attribute.
Sets enabled to true by default.
no
gcp.cloud_run.job.task_indexToggles the gcp.cloud_run.job.task_index resource attribute.
Sets enabled to true by default.
no
gcp.gce.instance.hostnameToggles the gcp.gce.instance.hostname resource attribute.
Sets enabled to false by default.
no
gcp.gce.instance.nameToggles the gcp.gce.instance.name resource attribute.
Sets enabled to false by default.
no
host.idToggles the host.id resource attribute.
Sets enabled to true by default.
no
host.nameToggles the host.name resource attribute.
Sets enabled to true by default.
no
host.typeToggles the host.type resource attribute.
Sets enabled to true by default.
no
k8s.cluster.nameToggles the k8s.cluster.name resource attribute.
Sets enabled to true by default.
no

Google Compute Engine (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

Google Kubernetes Engine (GKE) metadata

  • cloud.provider: "gcp"
  • cloud.platform: "gcp_kubernetes_engine"
  • cloud.account.id: project id
  • cloud.region: only for regional GKE clusters; e.g. "us-central1"
  • cloud.availability_zone: only for zonal GKE clusters; e.g. "us-central1-c"
  • k8s.cluster.name
  • host.id: instance id
  • host.name: instance name; only when workload identity is disabled

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

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

Google Cloud Run Services metadata

  • cloud.provider: "gcp"
  • cloud.platform: "gcp_cloud_run"
  • cloud.account.id: project id
  • cloud.region: e.g. "us-central1"
  • faas.id: instance id
  • faas.name: service name
  • faas.version: service revision

Cloud Run Jobs metadata

  • cloud.provider: "gcp"
  • cloud.platform: "gcp_cloud_run"
  • cloud.account.id: project id
  • cloud.region: e.g. "us-central1"
  • faas.id: instance id
  • faas.name: service name
  • gcp.cloud_run.job.execution: e.g. "my-service-ajg89"
  • gcp.cloud_run.job.task_index: e.g. "0"

Google Cloud Functions metadata

  • cloud.provider: "gcp"
  • cloud.platform: "gcp_cloud_functions"
  • cloud.account.id: project id
  • cloud.region: e.g. "us-central1"
  • faas.id: instance id
  • faas.name: function name
  • faas.version: function version

Google App Engine metadata

  • cloud.provider: "gcp"
  • cloud.platform: "gcp_app_engine"
  • cloud.account.id: project id
  • cloud.region: e.g. "us-central1"
  • cloud.availability_zone: e.g. "us-central1-c"
  • faas.id: instance id
  • faas.name: service name
  • faas.version: service version

heroku

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

The heroku block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

heroku > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
heroku.app.idToggles the heroku.app.id resource attribute.
Sets enabled to true by default.
no
heroku.dyno.idToggles the heroku.dyno.id resource attribute.
Sets enabled to true by default.
no
heroku.release.commitToggles the heroku.release.commit resource attribute.
Sets enabled to true by default.
no
heroku.release.creation_timestampToggles the heroku.release.creation_timestamp resource attribute.
Sets enabled to true by default.
no
service.instance.idToggles the service.instance.id resource attribute.
Sets enabled to true by default.
no
service.nameToggles the service.name resource attribute.
Sets enabled to true by default.
no
service.versionToggles the service.version resource attribute.
Sets enabled to true by default.
no

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 variableResource attribute
HEROKU_APP_IDheroku.app.id
HEROKU_APP_NAMEservice.name
HEROKU_DYNO_IDservice.instance.id
HEROKU_RELEASE_CREATED_ATheroku.release.creation_timestamp
HEROKU_RELEASE_VERSIONservice.version
HEROKU_SLUG_COMMITheroku.release.commit

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

system

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

Note

Use the Docker detector if running Alloy as a Docker container.

The system block supports the following attributes:

AttributeTypeDescriptionDefaultRequired
hostname_sourceslist(string)A priority list of sources from which the hostname will be fetched.["dns", "os"]no

The valid options for hostname_sources are:

  • "dns": Uses multiple sources to get the fully qualified domain name. Firstly, 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": Provides the hostname provided by the local machine’s kernel.
  • "cname": Provides the canonical name, as provided by net.LookupCNAME in the Go standard library. Note: this hostname source may produce unreliable results on Windows.
  • "lookup": Does a reverse DNS lookup of the current host’s IP address.

In case of an error in fetching a hostname from a source, the next source from the list of hostname_sources will be considered.

The system block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

system > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
host.archToggles the host.arch resource attribute.
Sets enabled to false by default.
no
host.cpu.cache.l2.sizeToggles the host.cpu.cache.l2.size resource attribute.
Sets enabled to false by default.
no
host.cpu.familyToggles the host.cpu.family resource attribute.
Sets enabled to false by default.
no
host.cpu.model.idToggles the host.cpu.model.id resource attribute.
Sets enabled to false by default.
no
host.cpu.model.nameToggles the host.cpu.model.name resource attribute.
Sets enabled to false by default.
no
host.cpu.steppingToggles the host.cpu.stepping resource attribute.
Sets enabled to false by default.
no
host.cpu.vendor.idToggles the host.cpu.vendor.id resource attribute.
Sets enabled to false by default.
no
host.idToggles the host.id resource attribute.
Sets enabled to false by default.
no
host.ipToggles the host.ip resource attribute.
Sets enabled to false by default.
no
host.macToggles the host.mac resource attribute.
Sets enabled to false by default.
no
host.nameToggles the host.name resource attribute.
Sets enabled to true by default.
no
os.descriptionToggles the os.description resource attribute.
Sets enabled to false by default.
no
os.typeToggles the os.type resource attribute.
Sets enabled to true by default.
no

openshift

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

The openshift block supports the following attributes:

AttributeTypeDescriptionDefaultRequired
addressstringAddress of the OpenShift API server.See belowno
tokenstringToken used to identify against the OpenShift API server.""no

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

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

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

The openshift block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no
tlsTLS settings for the connection with the OpenShift API.yes

openshift > tls

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

The following arguments are supported:

NameTypeDescriptionDefaultRequired
ca_filestringPath to the CA file.no
ca_pemstringCA PEM-encoded text to validate the server with.no
cert_filestringPath to the TLS certificate.no
cert_pemstringCertificate PEM-encoded text for client authentication.no
insecure_skip_verifybooleanIgnores insecure server TLS certificates.no
include_system_ca_certs_poolbooleanWhether to load the system certificate authorities pool alongside the certificate authority.falseno
insecurebooleanDisables TLS when connecting to the configured server.no
key_filestringPath to the TLS certificate key.no
key_pemsecretKey PEM-encoded text for client authentication.no
max_versionstringMaximum acceptable TLS version for connections."TLS 1.3"no
min_versionstringMinimum acceptable TLS version for connections."TLS 1.2"no
cipher_suiteslist(string)A list of TLS cipher suites that the TLS transport can use.[]no
reload_intervaldurationThe duration after which the certificate is reloaded."0s"no
server_namestringVerifies the hostname of server certificates when set.no

If the server doesn’t support TLS, you must set the insecure argument to true.

To disable tls for connections to the server, set the insecure argument to true.

If reload_interval is set to "0s", the certificate never reloaded.

The following pairs of arguments are mutually exclusive and can’t both be set simultaneously:

  • ca_pem and ca_file
  • cert_pem and cert_file
  • key_pem and key_file

If cipher_suites is left blank, a safe default list is used. See the Go TLS documentation for a list of supported cipher suites.

openshift > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
cloud.platformToggles the cloud.platform resource attribute.
Sets enabled to true by default.
no
cloud.providerToggles the cloud.provider resource attribute.
Sets enabled to true by default.
no
cloud.regionToggles the cloud.region resource attribute.
Sets enabled to true by default.
no
k8s.cluster.nameToggles the k8s.cluster.name resource attribute.
Sets enabled to true by default.
no

kubernetes_node

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

The kubernetes_node block supports the following attributes:

AttributeTypeDescriptionDefaultRequired
auth_typestringConfigures how to authenticate to the K8s API server."none"no
contextstringOverride the current context when auth_type is set to "kubeConfig".""no
node_from_env_varstringThe name of an environment variable from which to retrieve the node name."K8S_NODE_NAME"no

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

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

auth_type can be set to one of the following:

  • none: no authentication.
  • serviceAccount: use the standard service account token provided to the Alloy pod.
  • kubeConfig: use credentials from ~/.kube/config.

The kubernetes_node block supports the following blocks:

BlockDescriptionRequired
resource_attributesConfigures which resource attributes to add.no

kubernetes_node > resource_attributes

The resource_attributes block supports the following blocks:

BlockDescriptionRequired
k8s.node.nameToggles the k8s.node.name resource attribute.
Sets enabled to true by default.
no
k8s.node.uidToggles the k8s.node.uid resource attribute.
Sets enabled to true by default.
no

Common configuration

Resource attribute config

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

The following attributes are supported:

AttributeTypeDescriptionDefaultRequired
enabledboolToggles whether to add the resource attribute to the span, log, or metric resource.See belowno

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

Sets enabled to true by default.

… or:

Sets enabled to false by default.

Exported fields

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

NameTypeDescription
inputotelcol.ConsumerA value that other components can use to send telemetry data to.

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

  • logs
  • metrics
  • traces

Component health

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

Debug information

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

Examples

env detector

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

alloy
otelcol.processor.resourcedetection "default" {
  detectors = ["env"]

  output {
    logs    = [otelcol.exporter.otlp.default.input]
    metrics = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

env and ec2

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

alloy
otelcol.processor.resourcedetection "default" {
  detectors = ["env", "ec2"]

  output {
    logs    = [otelcol.exporter.otlp.default.input]
    metrics = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

ec2 with default resource attributes

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

alloy
otelcol.processor.resourcedetection "default" {
  detectors = ["ec2"]

  output {
    logs    = [otelcol.exporter.otlp.default.input]
    metrics = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

ec2 with explicit resource attributes

alloy
otelcol.processor.resourcedetection "default" {
  detectors = ["ec2"]
  ec2 {
    tags = ["^tag1$", "^tag2$", "^label.*$"]
    resource_attributes {
      cloud.account.id  { enabled = true }
      cloud.availability_zone  { enabled = true }
      cloud.platform  { enabled = true }
      cloud.provider  { enabled = true }
      cloud.region  { enabled = true }
      host.id  { enabled = true }
      host.image.id  { enabled = false }
      host.name  { enabled = false }
      host.type  { enabled = false }
    }
  }

  output {
    logs    = [otelcol.exporter.otlp.default.input]
    metrics = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

kubernetes_node

This example uses the default node_from_env_var option of K8S_NODE_NAME.

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

alloy
otelcol.processor.resourcedetection "default" {
  detectors = ["kubernetes_node"]

  output {
    logs    = [otelcol.exporter.otlp.default.input]
    metrics = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

You need to add this to your workload:

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

kubernetes_node with a custom environment variable

This example uses a custom node_from_env_var set to my_custom_var.

alloy
otelcol.processor.resourcedetection "default" {
  detectors = ["kubernetes_node"]
  kubernetes_node {
    node_from_env_var = "my_custom_var"
  }

  output {
    logs    = [otelcol.exporter.otlp.default.input]
    metrics = [otelcol.exporter.otlp.default.input]
    traces  = [otelcol.exporter.otlp.default.input]
  }
}

You need to add this to your workload:

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

Compatible components

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

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

Note

Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.