otelcol on Grafana Labs

otelcol.auth.basic

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.auth.basic`

otelcol.auth.basic exposes a handler that other otelcol components can use to authenticate requests using basic authentication.

This component supports both server and client authentication.

Note
otelcol.auth.basic is a wrapper over the upstream OpenTelemetry Collector basicauth extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.auth.basic components by giving them different labels.

Usage

otelcol.auth.basic "<LABEL>" {
  username = "<USERNAME>"
  password = "<PASSWORD>"
}

Arguments

Caution
Don’t use the top-level username and password arguments for new configurations as they are deprecated. Use the client_auth block for client authentication and the htpasswd block for server authentication instead.

You can use the following arguments with otelcol.auth.basic:

Name	Type	Description	Default	Required
`password`	`secret`	(Deprecated) Password to use for basic authentication requests.		no
`username`	`string`	(Deprecated) Username to use for basic authentication requests.		no

Blocks

You can use the following block with otelcol.auth.basic:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`client_auth`

The client_auth block configures credentials that client extensions (such as exporters) use to authenticate to servers.

Name	Type	Description	Default	Required
`password`	`secret`	Password to use for basic authentication requests.	`""`	no
`password_file`	`string`	Path to a file containing the password. If set, takes precedence over `password`.	`""`	no
`username`	`string`	Username to use for basic authentication requests.	`""`	no
`username_file`	`string`	Path to a file containing the username. If set, takes precedence over `username`.	`""`	no

Note
When you specify both the client_auth block and the deprecated top-level username and password attributes, the client_auth block takes precedence and Alloy ignores the top-level attributes for client authentication.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

disable_high_cardinality_metrics is the 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.

`htpasswd`

The htpasswd block configures how server extensions (such as receivers) authenticate incoming requests using the htpasswd format.

Name	Type	Description	Default	Required
`file`	`string`	Path to the `htpasswd` file to use for basic authentication requests.	`""`	no
`inline`	`string`	The `htpasswd` file content in inline format.	`""`	no

You can specify either file, inline, or both. When you use inline, the format should be username:password with each user on a new line.

Note
When you specify both the htpasswd block and the deprecated top-level username and password attributes, Alloy automatically appends the deprecated credentials to the inline content. This allows authentication using credentials from both the htpasswd configuration and the deprecated attributes. If the same username appears in both the file and inline content, including appended deprecated credentials, the entry in the inline content takes precedence.

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.basic is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.basic doesn’t expose any component-specific debug information.

Examples

This section includes examples to help you configure basic authentication for exporters and receivers.

Forward signals to exporters

This example configures otelcol.exporter.otlp to use basic authentication:

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.basic.creds.handler
  }
}

otelcol.auth.basic "creds" {
  username = "demo"
  password = sys.env("API_KEY")
}

Authenticating requests for receivers

These examples show how to perform basic authentication using the client_auth block for exporters or the htpasswd block for receivers.

Use client authentication

This example configures otelcol.exporter.otlphttp to use basic authentication with a single username and password combination:

otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"
  }

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

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = `https://otlp-gateway-prod-gb-south-0.grafana.net/otlp`
    auth     = otelcol.auth.basic.creds.handler
  }
}

otelcol.auth.basic "creds" {
  client_auth {
    username = sys.env("OTLP_USERNAME")
    password = sys.env("OTLP_API_KEY")
  }
}

Note
To migrate from the deprecated username and password attributes, move them into the client_auth block for client authentication.

Use htpasswd file

This example configures otelcol.receiver.otlp to use basic authentication using an htpasswd file containing the users to use for basic authentication:

otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"

    auth = otelcol.auth.basic.creds.handler
  }

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

otelcol.exporter.debug "default" {}

otelcol.auth.basic "creds" {
  htpasswd {
    file = "/etc/alloy/.htpasswd"
  }
}

Use htpasswd inline content

This example shows how to specify htpasswd content directly in the configuration:

otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"

    auth = otelcol.auth.basic.creds.handler
  }

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

otelcol.exporter.debug "default" {}

otelcol.auth.basic "creds" {
  htpasswd {
    inline = "user1:password1\nuser2:password2"
  }
}

Note
To make the migration from the deprecated username and password attributes easier, you can specify both the deprecated attributes and the htpasswd block in the same configuration. Alloy appends the deprecated attributes to the htpasswd content.
Alloy
otelcol.receiver.otlp "example" {
  grpc {
    endpoint = "127.0.0.1:4317"

    auth = otelcol.auth.basic.creds.handler
  }

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

otelcol.exporter.debug "default" {}

otelcol.auth.basic "creds" {
  username = "demo"
  password = sys.env("API_KEY")

  htpasswd {
    file = "/etc/alloy/.htpasswd"
  }
}

otelcol.auth.bearer

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.auth.bearer`

otelcol.auth.bearer exposes a handler that other otelcol components can use to authenticate requests using bearer token authentication.

This component supports both server and client authentication.

Note
otelcol.auth.bearer is a wrapper over the upstream OpenTelemetry Collector bearertokenauth extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.auth.bearer components by giving them different labels.

Usage

otelcol.auth.bearer "<LABEL>" {
  token = "<TOKEN>"
}

Arguments

You can use the following arguments with otelcol.auth.bearer:

Name	Type	Description	Default	Required
`token`	`secret`	Bearer token to use for authenticating requests.		yes
`header`	`string`	Specifies the auth header name.	`"Authorization"`	no
`scheme`	`string`	Authentication scheme name.	`"Bearer"`	no

When sending the token, the value of scheme is prepended to the token value. The string is then sent out as either a header for HTTP or as metadata for gRPC.

If you use a file to store the token, you can use local.file to retrieve the token value from the file.

Blocks

You can use the following block with otelcol.auth.bearer:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.bearer is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.bearer doesn’t expose any component-specific debug information.

Examples

Default scheme via gRPC transport

The following example configures otelcol.exporter.otlp to use a bearer token authentication.

If you assume that the value of the API_KEY environment variable is SECRET_API_KEY, then the Authorization RPC metadata is set to Bearer SECRET_API_KEY.

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.bearer.creds.handler
  }
}

otelcol.auth.bearer "creds" {
  token = sys.env("<API_KEY>")
}

Custom scheme via HTTP transport

The following example configures otelcol.exporter.otlphttp to use a bearer token authentication.

If you assume that the value of the API_KEY environment variable is SECRET_API_KEY, then the Authorization HTTP header is set to MyScheme SECRET_API_KEY.

otelcol.exporter.otlphttp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.bearer.creds.handler
  }
}

otelcol.auth.bearer "creds" {
  token = sys.env("<API_KEY>")
  scheme = "MyScheme"
}

otelcol.auth.headers

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.auth.headers`

otelcol.auth.headers exposes a handler that other otelcol components can use to authenticate requests using custom headers.

This component only supports client authentication.

Note
otelcol.auth.headers is a wrapper over the upstream OpenTelemetry Collector headerssetter extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.auth.headers components by giving them different labels.

Usage

otelcol.auth.headers "<LABEL>" {
  header {
    key   = "<HEADER_NAME>"
    value = "<HEADER_VALUE>"
  }
}

Arguments

The otelcol.auth.headers component doesn’t support any arguments. You can configure this component with blocks.

Blocks

You can use the following blocks with otelcol.auth.headers:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`header`

Required

The header block defines a custom header to attach to requests. It’s valid to provide multiple header blocks to set more than one header.

Name	Type	Description	Default	Required
`key`	`string`	Name of the header to set.		yes
`action`	`string`	An action to perform on the header.	`"upsert"`	no
`from_attribute`	`string`	Authentication attribute name used to retrieve header value.		no
`from_context`	`string`	Metadata name used to retrieve header value.		no
`value`	`string` or `secret`	Value of the header.		no

The supported values for action are:

insert: Inserts the new header if it doesn’t exist.
update: Updates the header value if it exists.
upsert: Inserts a header if it doesn’t exist and updates the header if it exists.
delete: Deletes the header.

Exactly one of value, from_context, or from_attribute must be provided for each header block.

The value attribute sets the value of the header directly. Alternatively, you can use from_context to dynamically retrieve the header value from request metadata, or you can use from_attribute to dynamically retrieve the header value from request authentication metadata.

For from_context to work, other components in the pipeline also need to be configured appropriately:

If an otelcol.processor.batch is present in the pipeline, it must be configured to preserve client metadata. Do this by adding the value that from_context needs to the metadata_keys of the batch processor.
otelcol receivers must be configured with include_metadata set to true so that metadata keys are available to the pipeline.

from_attribute metadata can’t, at this time, be preserved through an otelcol.processor.batch component, and is only provided from the otelcol.auth.basic extension.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.headers is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.headers doesn’t expose any component-specific debug information.

Example

This example configures otelcol.exporter.otlphttp to use custom headers:

otelcol.receiver.otlp "default" {
  http {
    include_metadata = true
  }
  grpc {
    include_metadata = true
  }

  output {
    metrics = [otelcol.processor.batch.default.input]
    logs    = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  // Preserve the tenant_id metadata.
  metadata_keys = ["tenant_id"]

  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
    logs    = [otelcol.exporter.otlphttp.production.input]
    traces  = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.auth.headers "creds" {
  header {
    key          = "X-Scope-OrgID"
    from_context = "tenant_id"
  }

  header {
    key   = "User-ID"
    value = "user_id"
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("<OTLP_SERVER_ENDPOINT>")
    auth     = otelcol.auth.headers.creds.handler
  }
}

otelcol.auth.oauth2

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.auth.oauth2`

otelcol.auth.oauth2 exposes a handler that other otelcol components can use to authenticate requests using OAuth 2.0.

This component only supports client authentication.

The authorization tokens can be used by HTTP and gRPC based OpenTelemetry exporters. This component can fetch and refresh expired tokens automatically. Refer to the OAuth 2.0 Authorization Framework for more information about the Auth 2.0 Client Credentials flow.

Note
otelcol.auth.oauth2 is a wrapper over the upstream OpenTelemetry Collector oauth2client extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.auth.oauth2 components by giving them different labels.

Usage

otelcol.auth.oauth2 "<LABEL>" {
    client_id     = "<CLIENT_ID>"
    client_secret = "<CLIENT_SECRET>"
    token_url     = "<TOKEN_URL>"
}

Arguments

You can use the following arguments with otelcol.auth.oauth2:

Name	Type	Description	Default	Required
`token_url`	`string`	The server endpoint URL from which to get tokens.	`""`	yes
`audience`	`string`	JWT audience claim for JWT bearer grant. Defaults to `token_url` when empty.	`""`	no
`claims`	`map(any)`	Additional JWT claims for JWT bearer grant.	`{}`	no
`client_certificate_key`	`secret`	JWT bearer private key.	`""`	no
`client_certificate_key_file`	`string`	Path to a file containing the JWT bearer private key.	`""`	no
`client_certificate_key_id`	`string`	Key ID included in JWT bearer grant requests.	`""`	no
`client_id`	`string`	The client identifier issued to the client.	`""`	no
`client_id_file`	`string`	Path to a file containing the client identifier.	`""`	no
`client_secret`	`secret`	The secret string associated with the client identifier.	`""`	no
`client_secret_file`	`string`	Path to a file containing the client secret.	`""`	no
`endpoint_params`	`map(list(string))`	Additional parameters that are sent to the token endpoint.	`{}`	no
`expiry_buffer`	`duration`	Time before token expiry when refresh should happen.	`"0s"`	no
`grant_type`	`string`	OAuth2 grant type. Valid values: `"client_credentials"` or `"urn:ietf:params:oauth:grant-type:jwt-bearer"`.	`"client_credentials"`	no
`iss`	`string`	JWT issuer claim for JWT bearer grant. Defaults to `client_id` when empty.	`""`	no
`scopes`	`list(string)`	Requested permissions associated for the client.	`[]`	no
`signature_algorithm`	`string`	JWT signing algorithm for JWT bearer grant. Valid values: `RS256`, `RS384`, `RS512`.	`"RS256"`	no
`timeout`	`duration`	The timeout on the client connecting to `token_url`.	`"0s"`	no

The timeout argument is used both for requesting initial tokens and for refreshing tokens. "0s" implies no timeout.

At least one of the client_id and client_id_file pair of arguments must be set. If both are set, client_id_file takes precedence.

If grant_type is client_credentials (default), at least one of client_secret or client_secret_file must be set. If both are set, client_secret_file takes precedence.

If grant_type is urn:ietf:params:oauth:grant-type:jwt-bearer, at least one of client_certificate_key or client_certificate_key_file must be set. If both are set, client_certificate_key_file takes precedence.

Blocks

You can use the following blocks with otelcol.auth.oauth2:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`tls`

The tls block configures TLS settings used for connecting to the token client. If the tls block isn’t provided, TLS won’t be used for communication.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

The curve_preferences argument determines the set of elliptic curves to prefer during a handshake in preference order. If not provided, a default list is used. The set of elliptic curves available are X25519, P521, P256, and P384.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.oauth2 is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.oauth2 doesn’t expose any component-specific debug information.

Example

This example configures otelcol.exporter.otlp to use OAuth 2.0 for authentication:

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.oauth2.creds.handler
  }
}

otelcol.auth.oauth2 "creds" {
    client_id     = "someclientid"
    client_secret = "someclientsecret"
    token_url     = "https://example.com/oauth2/default/v1/token"
}

Here is another example with some optional attributes specified:

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.oauth2.creds.handler
  }
}

otelcol.auth.oauth2 "creds" {
    client_id       = "someclientid2"
    client_secret   = "someclientsecret2"
    token_url       = "https://example.com/oauth2/default/v1/token"
    endpoint_params = {"audience" = ["someaudience"]}
    scopes          = ["api.metrics"]
    timeout         = "3600s"
}

otelcol.auth.sigv4

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.auth.sigv4`

otelcol.auth.sigv4 exposes a handler that other otelcol components can use to authenticate requests to AWS services using the AWS Signature Version 4 (SigV4) protocol. For more information about SigV4 refer to the AWS documentation about Signing AWS API requests.

This component only supports client authentication.

Note
otelcol.auth.sigv4 is a wrapper over the upstream OpenTelemetry Collector sigv4auth extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.auth.sigv4 components by giving them different labels.

Note
Alloy must have valid AWS credentials as used by the AWS SDK for Go.

Usage

otelcol.auth.sigv4 "<LABEL>" {
}

Arguments

You can use the following arguments with otelcol.auth.sigv4:

Name	Type	Description	Default	Required
`region`	`string`	The AWS region to sign with.	`""`	no
`service`	`string`	The AWS service to sign with.	`""`	no

If region and service are left empty, their values are inferred from the URL of the exporter using the following rules:

If the exporter URL starts with aps-workspaces and service is empty, service will be set to aps.
If the exporter URL starts with search- and service is empty, service will be set to es.
If the exporter URL starts with either aps-workspaces or search- and region is empty, region will be set to the value between the first and second . character in the exporter URL.

If none of the above rules apply, then region and service must be specified.

A list of valid AWS regions can be found on Amazon’s documentation for Regions, Availability Zones, and Local Zones.

Blocks

You can use the following blocks with otelcol.auth.sigv4:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`assume_role`

The assume_role block specifies the configuration needed to assume a role.

Name	Type	Description	Default	Required
`arn`	`string`	The Amazon Resource Name (ARN) of a role to assume.	`""`	no
`session_name`	`string`	The name of a role session.	`""`	no
`sts_region`	`string`	The AWS region where STS is used to assume the configured role.	`""`	no

If the assume_role block is specified in the configuration and sts_region isn’t set, then sts_region will default to the value for region.

For cross region authentication, region and sts_region can be set to different values.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`handler`	`capsule(otelcol.Handler)`	A value that other components can use to authenticate requests.

Component health

otelcol.auth.sigv4 is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.auth.sigv4 doesn’t expose any component-specific debug information.

Examples

Infer the “region” and “service” from an “aps-workspaces” exporter endpoint

In this example the exporter endpoint starts with aps-workspaces. service is inferred to be aps and region is inferred to be us-east-1.

otelcol.exporter.otlp "example" {
  client {
    endpoint = "https://aps-workspaces.us-east-1.amazonaws.com/workspaces/ws-XXX/api/v1/remote_write"
    auth     = otelcol.auth.sigv4.creds.handler
  }
}

otelcol.auth.sigv4 "creds" {
}

Infer the “region” and “service” from a “search-” exporter endpoint

In this example the exporter endpoint starts with search-. service is inferred to be es and region is inferred to be us-east-1.

otelcol.exporter.otlp "example" {
  client {
    endpoint = "https://search-my-domain.us-east-1.es.amazonaws.com/_search?q=house"
    auth     = otelcol.auth.sigv4.creds.handler
  }
}

otelcol.auth.sigv4 "creds" {
}

Specify “region” and “service” explicitly

In this example the exporter endpoint doesn’t begin with search- or with aps-workspaces. You must explicitly specify region and service.

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.sigv4.creds.handler
  }
}

otelcol.auth.sigv4 "creds" {
    region = "example_region"
    service = "example_service"
}

Specify “region” and “service” explicitly and adding a “role” to assume

In this example, the configuration assumes a role. sts_region hasn’t been provided, so it will default to the value of region which is example_region.

otelcol.exporter.otlp "example" {
  client {
    endpoint = "my-otlp-grpc-server:4317"
    auth     = otelcol.auth.sigv4.creds.handler
  }
}

otelcol.auth.sigv4 "creds" {
  region  = "example_region"
  service = "example_service"

  assume_role {
    session_name = "role_session_name"
  }
}

otelcol.connector.count

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.connector.count`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.connector.count accepts spans, span events, metrics, data points, and log records from other otelcol components and generates metrics that count the received telemetry data.

Note
otelcol.connector.count is a wrapper over the upstream OpenTelemetry Collector Contrib count connector. Bug reports or feature requests are redirected to the upstream repository if necessary.

You can specify multiple otelcol.connector.count components by giving them different labels.

Usage

otelcol.connector.count "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

The otelcol.connector.count component doesn’t support any arguments. You can configure this component with blocks.

Blocks

You can use the following blocks with otelcol.connector.count:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`spans`

The spans block configures a custom metric for counting spans.

You can specify multiple spans blocks to define different metrics.

If you don’t define any spans blocks, the connector emits a default metric named trace.span.count.

Name	Type	Description	Default	Required
`conditions`	`list(string)`	OTTL expressions for filtering spans.	`[]`	no
`description`	`string`	Metric description.	`""`	no
`name`	`string`	Metric name.	Uses default name based on telemetry type.	no

The conditions argument accepts a list of OTTL expressions that filter which spans to count. If any condition matches, the connector counts the span. If you don’t specify conditions, the connector counts all spans.

`spanevents`

The spanevents block configures a custom metric for counting span events.

You can specify multiple spanevents blocks to define different metrics.

If you don’t define any spanevents blocks, the connector emits a default metric named trace.span.event.count.

This block shares the same configuration structure as [spans][spans]. Refer to the [spans][spans] block documentation for the complete list of supported arguments and blocks.

`metrics`

The metrics block configures a custom metric for counting metrics.

You can specify multiple metrics blocks to define different metrics.

If you don’t define any metrics blocks, the connector emits a default metric named metric.count.

This block shares the same configuration structure as [spans][spans]. Refer to the [spans][spans] block documentation for the complete list of supported arguments and blocks.

`datapoints`

The datapoints block configures a custom metric for counting data points.

You can specify multiple datapoints blocks to define different metrics.

If you don’t define any datapoints blocks, the connector emits a default metric named metric.datapoint.count.

This block shares the same configuration structure as [spans][spans]. Refer to the [spans][spans] block documentation for the complete list of supported arguments and blocks.

`logs`

The logs block configures a custom metric for counting log records.

You can specify multiple logs blocks to define different metrics.

If you don’t define any logs blocks, the connector emits a default metric named log.record.count.

This block shares the same configuration structure as [spans][spans]. Refer to the [spans][spans] block documentation for the complete list of supported arguments and blocks.

`attributes`

The attributes block specifies an attribute to use for grouping counted telemetry data.

Each unique combination of attribute values generates a separate data point on the metric.

You can specify multiple attributes blocks within spans, spanevents, metrics, datapoints, or logs blocks to group by multiple attributes.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	Attribute key name.		yes
`default_value`	`any`	Default value if the attribute doesn’t exist.		no

Attribute precedence: span/log/metric attributes > scope attributes > resource attributes.

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(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`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for traces, metrics, and logs.

he component counts all telemetry received through input according to the configured blocks and emits metrics to the components specified in output.

Component health

otelcol.connector.count is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.connector.count doesn’t expose any component-specific debug information.

Examples

Default configuration

Use the count connector with minimal configuration to count all telemetry data using default metric names.

otelcol.connector.count "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

This configuration generates the following default metrics:

trace.span.count - Count of all spans
trace.span.event.count - Count of all span events
metric.count - Count of all metrics
metric.datapoint.count - Count of all data points
log.record.count - Count of all log records

Custom metrics with conditions and attributes

Create custom count metrics with filtering conditions and group counts by specific attributes.

otelcol.connector.count "default" {
  // Count only HTTP GET spans
  spans {
    name        = "http_get_requests"
    description = "Number of HTTP GET requests"
    conditions  = [
      "attributes[\"http.method\"] == \"GET\"",
    ]
  }

  // Count spans grouped by service and environment
  spans {
    name        = "spans_by_service"
    description = "Spans per service and environment"
    attributes {
      key           = "service.name"
      default_value = "unknown"
    }
    attributes {
      key           = "env"
      default_value = "production"
    }
  }

  // Count error and fatal logs only
  logs {
    name        = "error_logs"
    description = "Error and fatal log records"
    conditions  = [
      "severity_number >= 17",
    ]
  }

  // Count logs by environment
  logs {
    name        = "logs_by_env"
    description = "Log records per environment"
    attributes {
      key = "env"
    }
  }

  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

Complete pipeline with Prometheus export

Count spans, logs, and metrics, then export to Prometheus using the delta to cumulative processor.

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "127.0.0.1:4317"
  }

  http {
    endpoint = "127.0.0.1:4318"
  }

  output {
    traces  = [otelcol.connector.count.default.input]
    metrics = [otelcol.connector.count.default.input]
    logs    = [otelcol.connector.count.default.input]
  }
}

otelcol.connector.count "default" {
  spans {
    name        = "traces_total"
    description = "Total number of spans received"
  }

  spans {
    name        = "http_get_spans"
    description = "HTTP GET requests"
    conditions  = [
      "attributes[\"http.method\"] == \"GET\"",
    ]
  }

  spans {
    name        = "spans_by_service"
    description = "Spans grouped by service"
    attributes {
      key           = "service.name"
      default_value = "unknown"
    }
  }

  logs {
    name        = "logs_total"
    description = "Total number of logs received"
  }

  logs {
    name        = "error_logs"
    description = "Error level logs"
    conditions  = [
      "severity_number >= 17",
    ]
  }

  metrics {
    name        = "metrics_total"
    description = "Total number of metrics received"
  }

  output {
    metrics = [otelcol.processor.deltatocumulative.default.input]
  }
}

// Convert delta metrics to cumulative for Prometheus compatibility
otelcol.processor.deltatocumulative "default" {
  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to                       = [prometheus.remote_write.default.receiver]
  add_metric_suffixes              = false
  resource_to_telemetry_conversion = true
}

prometheus.remote_write "default" {
  endpoint {
    url = "http://localhost:9090/api/v1/write"
  }
}

Technical details

otelcol.connector.count uses the count connector from OpenTelemetry Collector Contrib.

All generated metrics use the Sum data type with Delta aggregation temporality.

Note
Prometheus doesn’t natively support delta metrics. Use otelcol.processor.deltatocumulative to convert delta metrics to cumulative before sending to Prometheus.

Compatible components

otelcol.connector.count can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

otelcol.connector.count has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.connector.host_info

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.connector.host_info`

otelcol.connector.host_info accepts span data from other otelcol components and generates usage metrics.

Note
otelcol.connector.host_info is a custom component unrelated to any connectors from the upstream OpenTelemetry Collector.

Usage

otelcol.connector.host_info "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.connector.host_info:

Name	Type	Description	Default	Required
`host_identifiers`	`list(string)`	Ordered list of resource attributes used to identify unique hosts.	`["host.id"]`	no
`metrics_flush_interval`	`duration`	How often to flush generated metrics.	`"60s"`	no

Blocks

You can use the following blocks with otelcol.connector.host_info:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no

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

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer traces telemetry data. It doesn’t accept metrics and logs.

Example

The following example accepts traces, adds the host.id resource attribute via the otelcol.processor.resourcedetection component, creates usage metrics from these traces, and writes the metrics to Mimir.

otelcol.receiver.otlp "otlp" {
  http {}
  grpc {}

  output {
    traces = [otelcol.processor.resourcedetection.otlp_resources.input]
  }
}

otelcol.processor.resourcedetection "otlp_resources" {
  detectors = ["system"]
  system {
    hostname_sources = [ "os" ]
    resource_attributes {
      host.id {
        enabled = true
      }
    }
  }
  output {
    traces = [otelcol.connector.host_info.default.input]
  }
}

otelcol.connector.host_info "default" {
  output {
    metrics = [otelcol.exporter.prometheus.otlp_metrics.input]
  }
}

otelcol.exporter.prometheus "otlp_metrics" {
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  endpoint {
    url = "https://prometheus-xxx.grafana.net/api/prom/push"
    basic_auth {
      username = sys.env("<PROMETHEUS_USERNAME>")
      password = sys.env("<GRAFANA_CLOUD_API_KEY>")
    }
  }
}

Compatible components

otelcol.connector.host_info can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

otelcol.connector.host_info has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.connector.servicegraph

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.connector.servicegraph`

otelcol.connector.servicegraph accepts span data from other otelcol components and outputs metrics representing the relationship between various services in a system. A metric represents an edge in the service graph. Those metrics can then be used by a data visualization application, for example, Grafana, to draw the service graph.

Note
otelcol.connector.servicegraph is a wrapper over the upstream OpenTelemetry Collector servicegraph connector. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.connector.servicegraph components by giving them different labels.

This component is based on the Grafana Tempo service graph processor.

Service graphs are useful for a number of use-cases:

Infer the topology of a distributed system. As distributed systems grow, they become more complex. Service graphs can help you understand the structure of the system.
Provide a high level overview of the health of your system. Service graphs show error rates, latencies, and other relevant data.
Provide a historic view of a system’s topology. Distributed systems change very frequently, and service graphs offer a way of seeing how these systems have evolved over time.

Since otelcol.connector.servicegraph has to process both sides of an edge, it needs to process all spans of a trace to function properly. If spans of a trace are spread out over multiple Alloy instances, spans can’t be paired reliably. A solution to this problem is using otelcol.exporter.loadbalancing in front of Alloy instances running otelcol.connector.servicegraph.

Usage

otelcol.connector.servicegraph "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.connector.servicegraph:

Name	Type	Description	Default	Required
`cache_loop`	`duration`	Configures how often to delete series which have not been updated.	`"1m"`	no
`database_name_attribute`	`string`	(Deprecated) The attribute name used to identify the database name from span attributes.	`"db.name"`	no
`database_name_attributes`	`list(string)`	The list of attribute names used to identify the database name from span attributes.	`["db.name"]`	no
`dimensions`	`list(string)`	A list of dimensions to add with the default dimensions.	`[]`	no
`exponential_histogram_max_size`	`list(string)`	the maximum number of buckets per positive or negative number range.	`[]`	no
`latency_histogram_buckets`	`list(duration)`	Buckets for latency histogram metrics.	`["2ms", "4ms", "6ms", "8ms", "10ms", "50ms", "100ms", "200ms", "400ms", "800ms", "1s", "1400ms", "2s", "5s", "10s", "15s"]`	no
`metrics_flush_interval`	`duration`	The interval at which metrics are flushed to downstream components.	`"60s"`	no
`store_expiration_loop`	`duration`	The time to expire old entries from the store periodically.	`"2s"`	no
`virtual_node_extra_label`	`bool`	Adds an extra `virtual_node` label with an optional value of `client` or `server`, indicating which node is the uninstrumented one.	`false`	no
`virtual_node_peer_attributes`	`list(string)`	The list of attributes used to identify virtual node peer.	`["peer.service", "db.name", "db.system"]`	no

Service graphs work by inspecting traces and looking for spans with parent-children relationship that represent a request. otelcol.connector.servicegraph uses OpenTelemetry semantic conventions to detect a myriad of requests. The following requests are supported:

A direct request between two services, where the outgoing and the incoming span must have a Span Kind value of client and server respectively.
A request across a messaging system, where the outgoing and the incoming span must have a Span Kind value of producer and consumer respectively.
A database request, where spans have a Span Kind with a value of client, as well as an attribute with a key of db.name.

Every span which can be paired up to form a request is kept in an in-memory store:

If the TTL of the span expires before it can be paired, it’s deleted from the store. TTL is configured in the [store][] block.
If the span is paired prior to its expiration, a metric is recorded and the span is deleted from the store.

The following metrics are emitted by the processor:

Metric	Type	Labels	Description
`traces_service_graph_dropped_spans_total`	Counter	`client`, `server`, `connection_type`	Total count of dropped spans
`traces_service_graph_request_client`	Histogram	`client`, `server`, `connection_type`	Number of seconds for a request between two nodes as seen from the client
`traces_service_graph_request_failed_total`	Counter	`client`, `server`, `connection_type`	Total count of failed requests between two nodes
`traces_service_graph_request_server`	Histogram	`client`, `server`, `connection_type`	Number of seconds for a request between two nodes as seen from the server
`traces_service_graph_request_total`	Counter	`client`, `server`, `connection_type`	Total count of requests between two nodes
`traces_service_graph_unpaired_spans_total`	Counter	`client`, `server`, `connection_type`	Total count of unpaired spans

Duration is measured both from the client and the server sides.

The latency_histogram_buckets argument controls the buckets for traces_service_graph_request_server and traces_service_graph_request_client.

Each emitted metrics series have a client and a server label corresponding with the service doing the request and the service receiving the request. The value of the label is derived from the service.name resource attribute of the two spans.

The connection_type label may not be set. If it’s set, its value will be either messaging_system or database.

Additional labels can be included using the dimensions configuration option:

Those labels will have a prefix to mark where they originate (client or server span kinds). The client_ prefix relates to the dimensions coming from spans with a Span Kind of client. The server_ prefix relates to the dimensions coming from spans with a Span Kind of server.
Firstly the resource attributes will be searched. If the attribute isn’t found, the span attributes will be searched.

When metrics_flush_interval is set to 0s, metrics will be flushed on every received batch of traces.

The attributes in database_name_attributes are tried in order, selecting the first match.

virtual_node_peer_attributes is useful when an OTel-instrumented client sends a request to a service that isn’t OTel-instrumented. Normally, otelcol.connector.servicegraph can’t pair the client span with the server span. When an edge expires, otelcol.connector.servicegraph checks if it has peer attributes listed in virtual_node_peer_attributes. If it finds an attribute, otelcol.connector.servicegraph aggregates the metrics with a virtual node.

If no client span is found and virtual_node_peer_attributes is not an empty list, then the service span will be paired with a virtual node called client="user". This is useful when a client that isn’t OTel-instrumented (like a web browser) sends a request to an OTel-instrumented service. Without a virtual node, the client span is missing, and the server span expires without being paired.

Attributes configured in the virtual_node_peer_attributes argument are ordered by priority, with earlier attributes having higher priority. An empty list disables the creation of a virtual node.

Blocks

You can use the following blocks with otelcol.connector.servicegraph:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`store`

The store block configures the in-memory store for spans.

Name	Type	Description	Default	Required
`max_items`	`number`	Maximum number of items to keep in the store.	`1000`	no
`ttl`	`duration`	The time to live for spans in the store.	`"2s"`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer traces telemetry data. It doesn’t accept metrics and logs.

Component health

otelcol.connector.servicegraph is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.connector.servicegraph doesn’t expose any component-specific debug information.

Example

The example below accepts traces, creates service graph metrics from them, and writes the metrics to Mimir. The traces are written to Tempo.

otelcol.connector.servicegraph also adds a label to each metric with the value of the “http.method” span/resource attribute.

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4320"
  }

  output {
    traces  = [otelcol.connector.servicegraph.default.input,otelcol.exporter.otlphttp.grafana_cloud_traces.input]
  }
}

otelcol.connector.servicegraph "default" {
  dimensions = ["http.method"]
  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "https://prometheus-xxx.grafana.net/api/prom/push"

    basic_auth {
      username = sys.env("<PROMETHEUS_USERNAME>")
      password = sys.env("<GRAFANA_CLOUD_API_KEY>")
    }
  }
}

otelcol.exporter.otlphttp "grafana_cloud_traces" {
  client {
    endpoint = `https://otlp-gateway-prod-gb-south-0.grafana.net/otlp`
    auth     = otelcol.auth.basic.grafana_cloud_traces.handler
  }
}

otelcol.auth.basic "grafana_cloud_traces" {
  username = sys.env("<TEMPO_USERNAME>")
  password = sys.env("<GRAFANA_CLOUD_API_KEY>")
}

Some of the metrics in Mimir may look like this:

traces_service_graph_request_total{client="shop-backend",failed="false",server="article-service",client_http_method="DELETE",server_http_method="DELETE"}
traces_service_graph_request_failed_total{client="shop-backend",client_http_method="POST",failed="false",server="auth-service",server_http_method="POST"}

Compatible components

otelcol.connector.servicegraph can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

otelcol.connector.servicegraph has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.connector.spanlogs

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.connector.spanlogs`

otelcol.connector.spanlogs accepts traces telemetry data from other otelcol components and outputs logs telemetry data for each span, root, or process. This allows you to automatically build a mechanism for trace discovery.

Note
otelcol.connector.spanlogs is a custom component unrelated to any components from the OpenTelemetry Collector. It’s based on the automatic_logging component in the traces subsystem of Grafana Agent Static.

You can specify multiple otelcol.connector.spanlogs components by giving them different labels.

Usage

otelcol.connector.spanlogs "<LABEL>" {
  output {
    logs    = [...]
  }
}

Arguments

You can use the following arguments with otelcol.connector.spanlogs:

Name	Type	Description	Default	Required
`event_attributes`	`list(string)`	Additional event attributes to log.	`[]`	no
`events`	`bool`	Log one line for every span event.	`false`	no
`labels`	`list(string)`	A list of keys that will be logged as labels.	`[]`	no
`process_attributes`	`list(string)`	Additional process attributes to log.	`[]`	no
`processes`	`bool`	Log one line for every process.	`false`	no
`roots`	`bool`	Log one line for every root span of a trace.	`false`	no
`span_attributes`	`list(string)`	Additional span attributes to log.	`[]`	no
`spans`	`bool`	Log one line per span.	`false`	no

The values listed in labels should be the values of either span, process, or event attributes.

Warning
Setting either spans or events to true could lead to a high volume of logs.

Blocks

You can use the following blocks with otelcol.connector.spanlogs:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no

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

`overrides`

The overrides block configures overrides for keys that will be logged in the body of the log line.

The following arguments are supported:

Name	Type	Description	Default	Required
`duration_key`	`string`	Log key for the duration of the span.	`dur`	no
`logs_instance_tag`	`string`	Indicates if the log line is for a span, root, or process.	`traces`	no
`service_key`	`string`	Log key for the service name of the resource.	`svc`	no
`span_name_key`	`string`	Log key for the name of the span.	`span`	no
`status_key`	`string`	Log key for the status of the span.	`status`	no
`trace_id_key`	`string`	Log key for the trace ID of the span.	`tid`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.connector.spanlogs is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.connector.spanlogs doesn’t expose any component-specific debug information.

Example

The following configuration sends logs derived from spans to Loki.

Additionally, otelcol.processor.attributes is configured with a “hint” so that otelcol.exporter.loki promotes the span’s “attribute1” attribute to a Loki label.

otelcol.receiver.otlp "default" {
  grpc {}

  output {
    traces = [otelcol.connector.spanlogs.default.input]
  }
}

otelcol.connector.spanlogs "default" {
  spans              = true
  roots              = true
  processes          = true
  events             = true
  labels             = ["attribute1", "res_attribute1"]
  span_attributes    = ["attribute1"]
  process_attributes = ["res_attribute1"]
  event_attributes   = ["log.severity", "log.message"]

  output {
    logs = [otelcol.processor.attributes.default.input]
  }
}

otelcol.processor.attributes "default" {
  action {
    key = "loki.attribute.labels"
    action = "insert"
    value = "attribute1"
  }

  output {
    logs = [otelcol.exporter.loki.default.input]
  }
}

otelcol.exporter.loki "default" {
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100"
  }
}

For an input trace like this:

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "res_attribute1",
            "value": { "intValue": "78" }
          },
          {
            "key": "unused_res_attribute1",
            "value": { "stringValue": "str" }
          },
          {
            "key": "res_account_id",
            "value": { "intValue": "2245" }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
              "span_id": "086e83747d0e381e",
              "name": "TestSpan",
              "attributes": [
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "unused_attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "account_id",
                  "value": { "intValue": "2245" }
                }
              ],
              "events": [
                {
                  "name": "log",
                  "attributes": [
                    {
                      "key": "log.severity",
                      "value": { "stringValue": "INFO" }
                    },
                    {
                      "key": "log.message",
                      "value": { "stringValue": "TestLogMessage" }
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

The output log coming out of otelcol.connector.spanlogs looks like this:

{
  "resourceLogs": [
    {
      "scopeLogs": [
        {
          "log_records": [
            {
              "body": {
                "stringValue": "span=TestSpan dur=0ns attribute1=78 svc=TestSvcName res_attribute1=78 tid=7bba9f33312b3dbb8b2c2c62bb7abe2d"
              },
              "attributes": [
                {
                  "key": "traces",
                  "value": { "stringValue": "span" }
                },
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "res_attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            },
            {
              "body": {
                "stringValue": "span=TestSpan dur=0ns attribute1=78 svc=TestSvcName res_attribute1=78 tid=7bba9f33312b3dbb8b2c2c62bb7abe2d"
              },
              "attributes": [
                {
                  "key": "traces",
                  "value": { "stringValue": "root" }
                },
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "res_attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            },
            {
              "body": {
                "stringValue": "svc=TestSvcName res_attribute1=78 tid=7bba9f33312b3dbb8b2c2c62bb7abe2d"
              },
              "attributes": [
                {
                  "key": "traces",
                  "value": { "stringValue": "process" }
                },
                {
                  "key": "res_attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            },
            {
              "body": { "stringValue": "span=TestSpan dur=0ns attribute1=78 svc=TestSvcName res_attribute1=78 tid=7bba9f33312b3dbb8b2c2c62bb7abe2d log.severity=INFO log.message=TestLogMessage" },
              "attributes": [
                {
                  "key": "traces",
                  "value": { "stringValue": "event" }
                },
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "res_attribute1",
                  "value": { "intValue": "78" }
                },
                {
                  "key": "log.severity",
                  "value": { "stringValue": "INFO" }
                },
                {
                  "key": "log.message",
                  "value": { "stringValue": "TestLogMessage" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Compatible components

otelcol.connector.spanlogs can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

otelcol.connector.spanlogs has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.connector.spanmetrics

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.connector.spanmetrics`

otelcol.connector.spanmetrics accepts span data from other otelcol components and aggregates Request, Error, and Duration (R.E.D) OpenTelemetry metrics from the spans:

Request counts are computed as the number of spans seen per unique set of dimensions, including Errors. Multiple metrics can be aggregated if, for instance, a user wishes to view call counts just on service.name and span.name.

Requests are tracked using a calls metric with a status.code datapoint attribute set to Ok:
text
```
calls { service.name="shipping", span.name="get_shipping/{shippingId}", span.kind="SERVER", status.code="Ok" }
```
Error counts are computed from the number of spans with an Error status code.

Errors are tracked using a calls metric with a status.code datapoint attribute set to Error:
text
```
calls { service.name="shipping", span.name="get_shipping/{shippingId}, span.kind="SERVER", status.code="Error" }
```
Duration is computed from the difference between the span start and end times and inserted into the relevant duration histogram time bucket for each unique set dimensions.

Span durations are tracked using a duration histogram metric:
text
```
duration { service.name="shipping", span.name="get_shipping/{shippingId}", span.kind="SERVER", status.code="Ok" }
```

Note
otelcol.connector.spanmetrics is a wrapper over the upstream OpenTelemetry Collector spanmetrics connector. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.connector.spanmetrics components by giving them different labels.

Usage

otelcol.connector.spanmetrics "<LABEL>" {
  histogram {
    ...
  }

  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.connector.spanmetrics:

Name	Type	Description	Default	Required
`aggregation_temporality`	`string`	Configures whether to reset the metrics after flushing.	`"CUMULATIVE"`	no
`dimensions_cache_size`	`number`	(Deprecated: use `aggregation_cardinality_limit` instead) How many dimensions to cache.	`0`	no
`exclude_dimensions`	`list(string)`	List of dimensions to be excluded from the default set of dimensions.	`[]`	no
`metric_timestamp_cache_size`	`number`	Controls the size of a cache used to keep track of the last time a metric was flushed.	`1000`	no
`metrics_expiration`	`duration`	Time period after which metrics are considered stale and are removed from the cache.	`"0s"`	no
`metrics_flush_interval`	`duration`	How often to flush generated metrics.	`"60s"`	no
`namespace`	`string`	Metric namespace.	`"traces.span.metrics"`	no
`resource_metrics_cache_size`	`number`	The size of the cache holding metrics for a service.	`1000`	no
`resource_metrics_key_attributes`	`list(string)`	Limits the resource attributes used to create the metrics.	`[]`	no
`aggregation_cardinality_limit`	`number`	The maximum number of unique combinations of dimensions that will be tracked for metrics aggregation.	`0`	no
`include_instrumentation_scope`	`list(string)`	A list of instrumentation scope names to include from the traces.	`[]`	no

The supported values for aggregation_temporality are:

"CUMULATIVE": The metrics won’t be reset after they’re flushed.
"DELTA": The metrics will be reset after they’re flushed.

If namespace is set, the generated metric name will be added a namespace. prefix.

Setting metrics_expiration to "0s" means that the metrics will never expire.

resource_metrics_cache_size is mostly relevant for cumulative temporality. It helps avoid issues with increasing memory and with incorrect metric timestamp resets.

metric_timestamp_cache_size is only relevant for delta temporality span metrics. It controls the size of a cache used to keep track of the last time a metric was flushed. When a metric is evicted from the cache, its next data point will indicate a “reset” in the series. Downstream components converting from delta to cumulative may handle these resets by setting cumulative counters back to 0.

resource_metrics_key_attributes can be used to avoid situations where resource attributes may change across service restarts, causing metric counters to break (and duplicate). A resource doesn’t need to have all of the attributes. The list must include enough attributes to properly identify unique resources or risk aggregating data from more than one service and span. For example, ["service.name", "telemetry.sdk.language", "telemetry.sdk.name"].

When the aggregation_cardinality_limit limit is reached, additional unique combinations will be dropped but registered under a new entry with otel.metric.overflow="true". A value of 0 means no limit is applied.

Blocks

You can use the following blocks with otelcol.connector.spanmetrics:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

You must specify either an [exponential][exponential] or an [explicit][explicit] block. You can’t specify both blocks in the same configuration.

`histogram`

Required

The histogram block configures the histogram derived from spans’ durations.

The following attributes are supported:

Name	Type	Description	Default	Required
`disable`	`bool`	Disable all histogram metrics.	`false`	no
`unit`	`string`	Configures the histogram units.	`"ms"`	no

The supported values for unit are:

"ms": milliseconds
"s": seconds

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`dimension`

The dimension block configures dimensions to be added in addition to the default ones.

The default dimensions are:

service.name
span.name
span.kind
status.code

The default dimensions are always added if not listed in exclude_dimensions. If no additional dimensions are specified, only the default ones will be added.

The following attributes are supported:

Name	Type	Description	Default	Required
`name`	`string`	Span attribute or resource attribute to look up.		yes
`default`	`string`	Value to use if the attribute is missing.		no

otelcol.connector.spanmetrics looks for the name attribute in the span’s collection of attributes. If it’s not found, the resource attributes will be checked.

If the attribute is missing in both the span and resource attributes:

If default isn’t set, the dimension will be omitted.
If default is set, the dimension will be added and its value will be set to the value of default.

`calls_dimension`

The attributes and behavior of the calls_dimension block match the [dimension][dimension] block.

`events`

The events block configures the events metric, which tracks span events.

The following attributes are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables all events metric.	`false`	no

At least one nested dimension block is required if enabled is set to true.

`exemplars`

The exemplars block configures how to attach exemplars to histograms.

The following attributes are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	Configures whether to add exemplars to histograms.	`false`	no
`max_per_data_point`	`number`	The maximum number of exemplars to attach to a single metric data point.	`5`	no

max_per_data_point can help with reducing memory consumption.

`exponential`

The exponential block configures a histogram with exponential buckets.

The following attributes are supported:

Name	Type	Description	Default	Required
`max_size`	`number`	Maximum number of buckets per positive or negative number range.	`160`	no

`explicit`

The explicit block configures a histogram with explicit buckets.

The following attributes are supported:

Name	Type	Description	Default	Required
`buckets`	`list(duration)`	List of histogram buckets.	`["2ms", "4ms", "6ms", "8ms", "10ms", "50ms", "100ms", "200ms", "400ms", "800ms", "1s", "1400ms", "2s", "5s", "10s", "15s"]`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer traces telemetry data. It doesn’t accept metrics and logs.

Handle resource attributes

otelcol.connector.spanmetrics is an OTLP-native component. As such, it aims to preserve the resource attributes of spans.

For example, assume that there are two incoming resources spans with the same service.name and k8s.pod.name resource attributes.

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "k8s.pod.name",
            "value": { "stringValue": "first" }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
              "span_id": "086e83747d0e381e",
              "name": "TestSpan",
              "attributes": [
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "k8s.pod.name",
            "value": { "stringValue": "first" }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
              "span_id": "086e83747d0e381b",
              "name": "TestSpan",
              "attributes": [
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

otelcol.connector.spanmetrics will preserve the incoming service.name and k8s.pod.name resource attributes by attaching them to the output metrics resource. Only one metric resource will be created, because both span resources have identical resource attributes.

{
  "resourceMetrics": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "k8s.pod.name",
            "value": { "stringValue": "first" }
          }
        ]
      },
      "scopeMetrics": [
        {
          "scope": { "name": "spanmetricsconnector" },
          "metrics": [
            {
              "name": "calls",
              "sum": {
                "dataPoints": [
                  {
                    "attributes": [
                      {
                        "key": "service.name",
                        "value": { "stringValue": "TestSvcName" }
                      },
                      {
                        "key": "span.name",
                        "value": { "stringValue": "TestSpan" }
                      },
                      {
                        "key": "span.kind",
                        "value": { "stringValue": "SPAN_KIND_UNSPECIFIED" }
                      },
                      {
                        "key": "status.code",
                        "value": { "stringValue": "STATUS_CODE_UNSET" }
                      }
                    ],
                    "startTimeUnixNano": "1702582936761872000",
                    "timeUnixNano": "1702582936761872012",
                    "asInt": "2"
                  }
                ],
                "aggregationTemporality": 2,
                "isMonotonic": true
              }
            }
          ]
        }
      ]
    }
  ]
}

Now, assume that otelcol.connector.spanmetrics receives two incoming resource spans, each with a different value for the k8s.pod.name recourse attribute.

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "k8s.pod.name",
            "value": { "stringValue": "first" }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
              "span_id": "086e83747d0e381e",
              "name": "TestSpan",
              "attributes": [
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "k8s.pod.name",
            "value": { "stringValue": "second" }
          }
        ]
      },
      "scopeSpans": [
        {
          "spans": [
            {
              "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
              "span_id": "086e83747d0e381b",
              "name": "TestSpan",
              "attributes": [
                {
                  "key": "attribute1",
                  "value": { "intValue": "78" }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

To preserve the values of all resource attributes, otelcol.connector.spanmetrics will produce two resource metrics. Each resource metric will have a different value for the k8s.pod.name recourse attribute. This way none of the resource attributes will be lost during the generation of metrics.

{
  "resourceMetrics": [
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "k8s.pod.name",
            "value": { "stringValue": "first" }
          }
        ]
      },
      "scopeMetrics": [
        {
          "scope": {
            "name": "spanmetricsconnector"
          },
          "metrics": [
            {
              "name": "calls",
              "sum": {
                "dataPoints": [
                  {
                    "attributes": [
                      {
                        "key": "service.name",
                        "value": { "stringValue": "TestSvcName" }
                      },
                      {
                        "key": "span.name",
                        "value": { "stringValue": "TestSpan" }
                      },
                      {
                        "key": "span.kind",
                        "value": { "stringValue": "SPAN_KIND_UNSPECIFIED" }
                      },
                      {
                        "key": "status.code",
                        "value": { "stringValue": "STATUS_CODE_UNSET" }
                      }
                    ],
                    "startTimeUnixNano": "1702582936761872000",
                    "timeUnixNano": "1702582936761872012",
                    "asInt": "1"
                  }
                ],
                "aggregationTemporality": 2,
                "isMonotonic": true
              }
            }
          ]
        }
      ]
    },
    {
      "resource": {
        "attributes": [
          {
            "key": "service.name",
            "value": { "stringValue": "TestSvcName" }
          },
          {
            "key": "k8s.pod.name",
            "value": { "stringValue": "second" }
          }
        ]
      },
      "scopeMetrics": [
        {
          "scope": {
            "name": "spanmetricsconnector"
          },
          "metrics": [
            {
              "name": "calls",
              "sum": {
                "dataPoints": [
                  {
                    "attributes": [
                      {
                        "key": "service.name",
                        "value": { "stringValue": "TestSvcName" }
                      },
                      {
                        "key": "span.name",
                        "value": { "stringValue": "TestSpan" }
                      },
                      {
                        "key": "span.kind",
                        "value": { "stringValue": "SPAN_KIND_UNSPECIFIED" }
                      },
                      {
                        "key": "status.code",
                        "value": { "stringValue": "STATUS_CODE_UNSET" }
                      }
                    ],
                    "startTimeUnixNano": "1702582936761872000",
                    "timeUnixNano": "1702582936761872012",
                    "asInt": "1"
                  }
                ],
                "aggregationTemporality": 2,
                "isMonotonic": true
              }
            }
          ]
        }
      ]
    }
  ]
}

Component health

otelcol.connector.spanmetrics is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.connector.spanmetrics doesn’t expose any component-specific debug information.

Examples

Explicit histogram and extra dimensions

In the example below, http.status_code and http.method are additional dimensions on top of:

service.name
span.name
span.kind
status.code

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    traces  = [otelcol.connector.spanmetrics.default.input]
  }
}

otelcol.connector.spanmetrics "default" {
  // Since a default is not provided, the http.status_code dimension will be omitted
  // if the span does not contain http.status_code.
  dimension {
    name = "http.status_code"
  }

  // If the span is missing http.method, the connector will insert
  // the http.method dimension with value 'GET'.
  dimension {
    name = "http.method"
    default = "GET"
  }

  dimensions_cache_size = 333

  aggregation_temporality = "DELTA"

  histogram {
    unit = "s"
    explicit {
      buckets = ["333ms", "777s", "999h"]
    }
  }

  // The period on which all metrics (whose dimension keys remain in cache) will be emitted.
  metrics_flush_interval = "33s"

  namespace = "test.namespace"

  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Send metrics via a Prometheus remote write

The generated metrics can be sent to a Prometheus-compatible database such as Grafana Mimir. However, extra steps are required to make sure all metric samples are received. This is because otelcol.connector.spanmetrics aims to preserve resource attributes in the metrics which it outputs.

Unfortunately, the Prometheus data model has no notion of resource attributes. This means that if otelcol.connector.spanmetrics outputs metrics with identical metric attributes, but different resource attributes, otelcol.exporter.prometheus converts the metrics into the same metric series. This problem can be solved by doing either of the following:

Recommended approach: Prior to otelcol.connector.spanmetrics, remove all resource attributes from the incoming spans which aren’t needed by otelcol.connector.spanmetrics.

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    traces  = [otelcol.processor.transform.default.input]
  }
}

// Remove all resource attributes except the ones which
// the otelcol.connector.spanmetrics needs.
// If this is not done, otelcol.exporter.prometheus may fail to
// write some samples due to an "err-mimir-sample-duplicate-timestamp" error.
// This is because the spanmetricsconnector will create a new
// metrics resource scope for each traces resource scope.
otelcol.processor.transform "default" {
  error_mode = "ignore"

  trace_statements {
    context = "resource"
    statements = [
      // We keep only the "service.name" and "special.attr" resource attributes,
      // because they are the only ones which otelcol.connector.spanmetrics needs.
      //
      // There is no need to list "span.name", "span.kind", and "status.code"
      // here because they are properties of the span (and not resource attributes):
      // https://github.com/open-telemetry/opentelemetry-proto/blob/v1.0.0/opentelemetry/proto/trace/v1/trace.proto
      `keep_keys(attributes, ["service.name", "special.attr"])`,
    ]
  }

  output {
    traces  = [otelcol.connector.spanmetrics.default.input]
  }
}

otelcol.connector.spanmetrics "default" {
  histogram {
    explicit {}
  }

  dimension {
    name = "special.attr"
  }
  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

Or, after otelcol.connector.spanmetrics, copy each of the resource attributes as a metric datapoint attribute. This has the advantage that the resource attributes will be visible as metric labels. However, the cardinality of the metrics may be much higher, which could increase the cost of storing and querying them. The example below uses the merge_maps OTTL function.

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    traces  = [otelcol.connector.spanmetrics.default.input]
  }
}

otelcol.connector.spanmetrics "default" {
  histogram {
    explicit {}
  }

  dimension {
    name = "special.attr"
  }
  output {
    metrics = [otelcol.processor.transform.default.input]
  }
}

// Insert resource attributes as metric data point attributes.
otelcol.processor.transform "default" {
  error_mode = "ignore"

  metric_statements {
    context = "datapoint"
    statements = [
      // "insert" means that a metric datapoint attribute will be inserted
      // only if an attribute with the same key does not already exist.
      `merge_maps(attributes, resource.attributes, "insert")`,
    ]
  }

  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

If the resource attributes aren’t treated in either of the ways described above, an error such as this one could be logged by prometheus.remote_write: the sample has been rejected because another sample with the same timestamp, but a different value, has already been ingested (err-mimir-sample-duplicate-timestamp).

Note
In order for a Prometheus target_info metric to be generated, the incoming spans resource scope attributes must contain service.name and service.instance.id attributes.

The target_info metric will be generated for each resource scope, while OpenTelemetry metric names and attributes will be normalized to be compliant with Prometheus naming rules.

Troubleshoot high cardinality span metrics

High cardinality issues in span metrics commonly manifest in APM dashboards as an excessive number of service operations with non-unique names. Examples include URIs with unique identifiers such as GET /product/1YMWWN1N4O or HTTP parameters with random values such as GET /?_ga=GA1.2.569539246.1760114706. These patterns render operation lists difficult to interpret and ineffective for monitoring purposes.

This issue stems from violations of OpenTelemetry semantic conventions, which require span names to have low cardinality. Refer to HTTP span name specs for more information. Beyond degrading APM interfaces with numerous non-meaningful operation names, this problem causes metric time series explosion, resulting in significant performance degradation and increased costs.

otelcol.connector.spanmetrics provides an optional circuit breaker through the aggregation_cardinality_limit attribute, disabled by default, to mitigate cardinality explosion. While this feature addresses performance and cost concerns, it doesn’t resolve the underlying issue of semantically meaningless operation names.

Fix high cardinality span name issues

The ideal long-term solution is to modify the OpenTelemetry instrumentation code to comply with semantic conventions. This prevents the generation of non-compliant high cardinality span names.

However, deploying updated instrumentation libraries can be time-consuming. You often need an immediate interim solution to restore observability backend functionality.

Address high cardinality span names in the ingestion pipeline

An effective short-term solution is to implement a layer that sanitizes span names within the observability ingestion pipeline. You can use otelcol.processor.transform’s set_semconv_span_name() function immediately before otelcol.connector.spanmetrics to enforce semantic conventions on span names.

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    traces = [otelcol.processor.transform.sanitize_spans.input]
  }
}

otelcol.processor.transform "sanitize_spans" {
  error_mode = "ignore"

  trace_statements {
    context = "span"
    statements = [
      // Sanitize all span names to prevent span metrics cardinality explosion
      // caused by non-compliant high cardinality span names
      `set_semconv_span_name("1.37.0")`,
    ]
  }

  output {
    traces = [otelcol.connector.spanmetrics.default.input]
  }
}

otelcol.connector.spanmetrics "default" {
  histogram {
    explicit {}
  }

  output {
    metrics = [otelcol.exporter.otlphttp.observability_backend.input]
  }
}

otelcol.exporter.otlphttp "observability_backend" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Aggressive span name cleanup may be overly restrictive for instrumentation libraries with incomplete resource attributes. For instance, the cleanup may reduce HTTP service operations to generic names like GET and POST when HTTP spans lack the http.route attribute. This information loss can impact the monitoring of critical business operations.

To preserve operation granularity, you can manually set the http.route attribute when you need detailed operation names. You can typically derive the missing http.route value through pattern matching on other span attributes such as http.target or url.full.

The following example configuration prevents cardinality explosion while preserving meaningful operation names on a service webshop/frontend:

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    traces = [otelcol.processor.transform.sanitize_spans.input]
  }
}

// Sanitize spans to prevent span metrics cardinality explosion caused by
// non-compliant high cardinality span names:
// 1. Fix incomplete semconv of critical operation spans to keep meaningful
//    span metrics operation names, adding missing `http.route` and
//    `http.request.method`.
// 2. Sanitize all span names, note that http server spans lacking
//    `http.route` will default to operations `GET`, `POST`, etc.
otelcol.processor.transform "sanitize_spans" {
  error_mode = "ignore"

  // 1. Fix incomplete semconv on the critical http operations of the `frontend` service
  trace_statements {
    context    = "span"
    conditions = [
      `span.kind == SPAN_KIND_SERVER and resource.attributes["service.name"] == "frontend" and resource.attributes["service.namespace"] == "webshop" and span.attributes["http.route"] == nil`,
    ]
    statements = [
      // e.g. /api/checkout
      `set(span.attributes["http.route"], "/api/checkout") where IsMatch(span.attributes["http.target"], "\\/api\\/checkout")`,
      // e.g. /api/products/1YMWWN1N4O
      `set(span.attributes["http.route"], "/api/products/{productId}") where IsMatch(span.attributes["http.target"], "\\/api\\/products\\/.*")`,
    ]
  }

  // 1. Fix incomplete semconv on the critical http operations of other services...

  // 2. Sanitize all span names to prevent span metrics cardinality explosion.
  //    Unsanitized span names, when different, are kept in the `unsanitized_span_name` attribute
  trace_statements {
    context = "span"
    statements = [
      `set_semconv_span_name("1.37.0", "unsanitized_span_name")`,
    ]
  }

  output {
    traces = [otelcol.connector.spanmetrics.default.input]
  }
}

otelcol.connector.spanmetrics "default" {
  histogram {
    explicit {}
  }

  output {
    metrics = [otelcol.exporter.otlphttp.observability_backend.input]
  }
}

otelcol.exporter.otlphttp "observability_backend" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Address high cardinality span names in the instrumentation code

The preferred long-term solution is to ensure span names and attributes comply with OpenTelemetry Semantic Conventions directly in the instrumentation code.

Custom web frameworks are a common source of high cardinality span names. While default OpenTelemetry instrumentation, for example, Java Servlet, may assign generic span names like GET /my-web-fwk/*, your framework has access to more specific routing information. Overwrite span attributes in your framework code to create compliant, low-cardinality span names that preserve operational granularity.

Example: Custom Web Framework in Java

Consider a custom web framework that intercepts the generic route /my-web-fwk/* and dispatches requests like /my-web-fwk/product/123456ABCD or /my-web-fwk/user/john.doe.

The default Java Servlet instrumentation produces vague span names (GET /my-web-fwk/*), while directly using request URIs creates high cardinality (GET /my-web-fwk/product/123456ABCD).

The solution is to override span attributes with templated route patterns like /my-web-fwk/product/{productId} or /my-web-fwk/user/{userId}:

@WebServlet(urlPatterns = "/my-web-fwk/*")
public class MyWebFrameworkServlet extends HttpServlet {

    @Override
    protected void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        // Default Servlet instrumentation sets vague span names: `GET /my-web-fwk/*` (and `http.route=/my-web-fwk/*`)
        // Using the request URI directly would cause high cardinality and violate semantic conventions
        // Instead, use the framework's low-cardinality routing information below

        // Example routing logic
        String uri = request.getRequestURI();
        MyWebOperation myWebOperation = getWebOperation(uri);

        // Fix span details to add details while complying with semantic conventions and maintaining low cardinality
        String httpRoute = "/my-web-fwk/" + myWebOperation.getSubHttpRoute();
        Span.current().setAttribute(HttpAttributes.HTTP_ROUTE, httpRoute);
        Span.current().updateName(request.getMethod() + " " + httpRoute);

        // execute the web operation
        myWebOperation.execute(request, response);
    }
    ...
}

Compatible components

otelcol.connector.spanmetrics can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

otelcol.connector.spanmetrics has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.awss3

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.awss3`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.exporter.awss3 accepts telemetry data from other otelcol components and writes them to an AWS S3 bucket.

Note
otelcol.exporter.awss3 is a wrapper over the upstream OpenTelemetry Collector awss3 exporter. Bug reports or feature requests will be redirected to the upstream repository if necessary.

You can specify multiple otelcol.exporter.awss3 components by giving them different labels.

Usage

otelcol.exporter.awss3 "<LABEL>" {
  s3_uploader {
    region = "<AWS_REGION>"
    s3_bucket = "<S3_BUCKET_NAME>"
    s3_prefix = "<PREFIX_FOR_S3_KEY>"
  }
}

Arguments

You can use the following argument with otelcol.exporter.awss3:

Name	Type	Description	Default	Required
`timeout`	`duration`	Time to wait before marking a request as failed.	`"5s"`	no

Blocks

You can use the following blocks with otelcol.exporter.awss3:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`s3_uploader`

Required

The s3_uploader block configures the AWS S3 bucket details used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`s3_bucket`	`string`	The S3 bucket.		yes
`s3_prefix`	`string`	Prefix for the S3 key (directory inside the bucket), appended to `s3_base_prefix` if provided.		yes
`acl`	`string`	The canned ACL to use when uploading objects.	`"private"`	no
`compression`	`string`	File compression method, `none` or `gzip`	`"none"`	no
`disable_ssl`	`boolean`	Set this to `true` to disable SSL when sending requests.	`false`	no
`endpoint`	`string`	Overrides the endpoint used by the exporter instead of constructing it from `region` and `s3_bucket`.		no
`file_prefix`	`string`	The file prefix defined by the user.		no
`region`	`string`	The AWS region.	`"us-east-1"`	no
`retry_max_attempts`	`int`	The max number of attempts for retrying a request.	`3`	no
`retry_max_backoff`	`duration`	The max backoff delay that can occur before retrying a request.	`20s`	no
`retry_mode`	`string`	The retryer implementation.	`"standard"`	no
`role_arn`	`string`	The Role ARN to be assumed.		no
`s3_base_prefix`	`string`	Prefix for the S3 key (root directory inside the bucket).		no
`s3_force_path_style`	`boolean`	Set this to `true` to force the request to use path-style requests	`false`	no
`s3_partition_format`	`string`	Filepath formatting for the partition; Refer to `strftime` for format specification.	`"year=%Y/month=%m/day=%d/hour=%H/minute=%M"`	no
`s3_partition_timezone`	`string`	Timezone used for partition time. Local timezone is used if not configured.		no
`storage_class`	`string`	The storage class to use when uploading objects.	`"STANDARD"`	no

retry_mode must be one of standard, adaptive, or nop. If retry_mode is set to nop, the aws.NopRetryer implementation effectively disables the retry. Setting retry_max_attempts to 0 will allow the SDK to retry all retryable errors until the request succeeds, or a non-retryable error is returned.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`marshaler`

Marshaler determines the format of data sent to AWS S3. Currently, the following marshalers are implemented:

otlp_json (default): the OpenTelemetry Protocol format, represented as JSON.
otlp_proto: the OpenTelemetry Protocol format, represented as Protocol Buffers. A single protobuf message is written into each object.
sumo_ic: the Sumo Logic Installed Collector Archive format. This format is supported only for logs.
body: export the log body as string. This format is supported only for logs.

The following arguments are supported:

Name	Type	Description	Default	Required
`type`	`string`	Marshaler used to produce output data.	`"otlp_json"`	no

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

When enabled is true, data is first written to an in-memory buffer before sending it to the configured server. Batches sent to the component’s input exported field are added to the buffer as long as the number of unsent batches doesn’t exceed the configured queue_size.

queue_size determines how long an endpoint outage is tolerated. Assuming 100 requests/second, the default queue size 1000 provides about 10 seconds of outage tolerance. To calculate the correct value for queue_size, multiply the average number of outgoing requests per second by the time in seconds that outages are tolerated. A very high value can cause Out Of Memory (OOM) kills.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

The num_consumers argument controls how many readers read from the buffer and send data in parallel. Larger values of num_consumers allow data to be sent more quickly at the expense of increased network traffic.

If an otelcol.storage.* component is configured and provided in the queue’s storage argument, the queue uses the provided storage extension to provide a persistent queue and the queue is no longer stored in memory. Any data persisted will be processed on startup if Alloy is killed or restarted. Refer to the exporterhelper documentation in the OpenTelemetry Collector repository for more details.

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

Batching is disabled by default. To enable it, explicitly include batch {} in your Alloy configuration. You do not need to include a batch {} block in your otelcol.exporter if you already use a otelcol.processor.batch component, although batching in the exporter is the preferred method because it is more flexible.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

resource_attrs_to_s3 block

The following arguments are supported:

Name	Type	Description	Default	Required
`s3_bucket`	`string`	Configures which resource attribute’s value should be used as the S3 prefix.		yes
`s3_prefix`	`string`	Configures which resource attribute’s value should be used as the S3 bucket.		no

When s3_prefix or s3_bucket are set, they dynamically override the [s3_uploader][s3_uploader] attributes. If the specified resource attribute exists in the data, its value will be used. Otherwise, the [s3_uploader][s3_uploader] attribute will serve as the fallback.

Compression

none (default): File compression isn’t used.
gzip: Files are compressed with Gzip. This doesn’t support sumo_icmarshaler.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.awss3 is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.awss3 doesn’t expose any component-specific debug information.

Debug metrics

otelcol_exporter_queue_capacity (gauge): Fixed capacity of the retry queue (in batches).
otelcol_exporter_queue_size (gauge): Current size of the retry queue (in batches).
otelcol_exporter_send_failed_spans_total (counter): Number of spans in failed attempts to send to destination.
otelcol_exporter_sent_spans_total (counter): Number of spans successfully sent to destination.
rpc_client_duration_milliseconds (histogram): Measures the duration of inbound RPC.
rpc_client_request_size_bytes (histogram): Measures size of RPC request messages (uncompressed).
rpc_client_requests_per_rpc (histogram): Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.
rpc_client_response_size_bytes (histogram): Measures size of RPC response messages (uncompressed).
rpc_client_responses_per_rpc (histogram): Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.

Example

This example forwards scrape logs to an AWS S3 Bucket:

local.file_match "logs" {
  path_targets = [{
    __address__ = "localhost",
    __path__    = "/var/log/{syslog,messages,*.log}",
    instance    = constants.hostname,
    job         = "integrations/node_exporter",
  }]
}

loki.source.file "logs" {
  targets    = local.file_match.logs.targets
  forward_to = [otelcol.receiver.loki.default.receiver]
}

otelcol.receiver.loki "default" {
  output {
    logs = [otelcol.exporter.awss3.logs.input]
  }
}

otelcol.exporter.awss3 "logs" {
  s3_uploader {
    region = "us-east-1"
    s3_bucket = "logs_bucket"
    s3_prefix = "logs"
  }
}

Compatible components

otelcol.exporter.awss3 has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.datadog

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.datadog`

Community: This component is developed, maintained, and supported by the Alloy user community. Grafana doesn’t offer commercial support for this component. To enable and use community components, you must set the --feature.community-components.enabled flag to true.

Refer to Community components for more information.

otelcol.exporter.datadog accepts metrics and traces telemetry data from other otelcol components and sends it to Datadog.

Note
otelcol.exporter.datadog is a wrapper over the upstream OpenTelemetry Collector datadog exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.datadog components by giving them different labels.

Usage

otelcol.exporter.datadog "<LABEL>" {
    api {
        api_key = "<YOUR_API_KEY_HERE>"
    }
}

Arguments

You can use the following arguments with otelcol.exporter.datadog:

Name	Type	Description	Default	Required
`hostname`	`string`	The fallback hostname used for payloads without hostname-identifying attributes.		no
`hostname_detection_timeout`	`duration`	The timeout for hostname detection.	`25s`	no
`only_metadata`	`bool`	Whether to send only metadata.	`false`	no

If hostname is unset, the hostname is determined automatically. For more information, refer to the Datadog Fallback hostname logic documentation. This option won’t change the hostname applied to metrics or traces if they already have hostname-identifying attributes.

Blocks

You can use the following blocks with otelcol.exporter.datadog:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`api`

Required

The api block configures authentication with the Datadog API. This is required to send telemetry to Datadog. If you don’t provide the api block, you can’t send telemetry to Datadog.

The following arguments are supported:

Name	Type	Description	Default	Required
`api_key`	`secret`	API Key for Datadog		yes
`fail_on_invalid_key`	`bool`	Whether to exit at startup on an invalid API key	`false`	no
`site`	`string`	The site of the Datadog intake to send Agent data to.	`"datadoghq.com"`	no

`client`

The client block configures the HTTP client used by the component. Not all fields are supported by the Datadog Exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_keep_alives`	`bool`	Disable HTTP keep-alive.		no
`idle_conn_timeout`	`duration`	Time to wait before an idle connection closes itself.	`"45s"`	no
`insecure_skip_verify`	`bool`	Ignores insecure server TLS certificates.		no
`max_conns_per_host`	`int`	Limits the total (dialing,active, and idle) number of connections per host.		no
`max_idle_conns_per_host`	`int`	Limits the number of idle HTTP connections the host can keep open.	`5`	no
`max_idle_conns`	`int`	Limits the number of idle HTTP connections the client can keep open.	`100`	no
`read_buffer_size`	`string`	Size of the read buffer the HTTP client uses for reading server responses.		no
`timeout`	`duration`	Time to wait before marking a request as failed.	`"15s"`	no
`write_buffer_size`	`string`	Size of the write buffer the HTTP client uses for writing requests.		no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`host_metadata`

The host_metadata block configures the host metadata configuration. Host metadata is the information used to populate the infrastructure list and the host map, and provide host tags functionality within the Datadog app.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	Enable the host metadata functionality	`true`	no
`hostname_source`	`string`	Source for the hostname of host metadata.	`"config_or_system"`	no
`tags`	`list(string)`	List of host tags to be sent as part of the host metadata.		no

By default, the exporter only sends host metadata for a single host, whose name is chosen according to host_metadata::hostname_source.

Valid values for hostname_source are:

"first_resource" picks the host metadata hostname from the resource attributes on the first OTLP payload that gets to the exporter. If the first payload lacks hostname-like attributes, it will fallback to config_or_system behavior. Don’t use this hostname source if receiving data from multiple hosts.
"config_or_system" picks the host metadata hostname from the hostname setting, falling back to system and cloud provider APIs.

`logs`

The logs block configures the logs exporter settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`batch_wait`	`int`	The maximum time in seconds the logs agent waits to fill each batch of logs before sending.	`5`	no
`compression_level`	`int`	Accepts values from 0 (no compression) to 9 (maximum compression but higher resource usage). Only used if `use_compression` is set to `true`.	`6`	no
`endpoint`	`string`	The host of the Datadog intake server to send logs to.	`"https://http-intake.logs.datadoghq.com"`	no
`use_compression`	`bool`	Available when sending logs via HTTPS. Compresses logs if enabled.	`true`	no

If use_compression is disabled, compression_level has no effect.

If endpoint is unset, the value is obtained through the site parameter in the [api][] section.

`metrics`

The metrics block configures Metric specific exporter settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`delta_ttl`	`number`	The number of seconds values are kept in memory for calculating deltas.	`3600`	no
`endpoint`	`string`	The host of the Datadog intake server to send metrics to.	`"https://api.datadoghq.com"`	no

Any of the subset of resource attributes in the semantic mapping list are converted to Datadog conventions and set to metric tags whether resource_attributes_as_tags is enabled or not.

If endpoint is unset, the value is obtained through the site parameter in the [api][] section.

`exporter`

The exporter block configures the metric exporter settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`instrumentation_scope_metadata_as_tags`	`bool`	Set to `false` to not add metadata about the instrumentation scope that created a metric.	`true`	no
`resource_attributes_as_tags`	`bool`	Set to `true` to add resource attributes of a metric to its metric tags.	`false`	no

`histograms`

The histograms block configures the histogram settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`mode`	`string`	How to report histograms.	`"distributions"`	no
`send_aggregation_metrics`	`bool`	Whether to report sum, count, min, and max as separate histogram metrics.	`false`	no

Valid values for mode are:

"distributions" to report metrics as Datadog distributions (recommended).
"nobuckets" to not report bucket metrics.
"counters" to report one metric per histogram bucket.

`summaries`

The summaries block configures the summary settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`mode`	`string`	How to report summaries.	`"gauges"`	no

Valid values for mode are:

"noquantiles" to not report quantile metrics.
"gauges" to report one gauge metric per quantile.

`sums`

The sums block configures the sums settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`cumulative_monotonic_mode`	`string`	How to report cumulative monotonic sums.	`"to_delta"`	no
`initial_cumulative_monotonic_value`	`string`	How to report the initial value for cumulative monotonic sums.	`"auto"`	no

Valid values for cumulative_monotonic_mode are:

"to_delta" to calculate delta for sum in the client side and report as Datadog counts.
"raw_value" to report the raw value as a Datadog gauge.

Valid values for initial_cumulative_monotonic_value are:

"auto" reports the initial value if its start timestamp is set, and it happens after the process was started.
"drop" always drops the initial value.
"keep" always reports the initial value.

`retry_on_failure`

The retry_on_failure block configures how failed requests to Datadog are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

When enabled is true, failed batches are retried after a given interval. The initial_interval argument specifies how long to wait before the first retry attempt. If requests continue to fail, the time to wait before retrying increases by the factor specified by the multiplier argument, which must be greater than 1.0. The max_interval argument specifies the upper bound of how long to wait between retries.

The randomization_factor argument is useful for adding jitter between retrying Alloy instances. If randomization_factor is greater than 0, the wait time before retries is multiplied by a random factor in the range [ I - randomization_factor * I, I + randomization_factor * I], where I is the current interval.

If a batch hasn’t been sent successfully, it’s discarded after the time specified by max_elapsed_time elapses. If max_elapsed_time is set to "0s", failed requests are retried forever until they succeed.

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

`traces`

The traces block configures the trace exporter settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`compute_stats_by_span_kind`	`bool`	Enables APM stats computation based on `span.kind`	`true`	no
`compute_top_level_by_span_kind`	`bool`	Enables top-level span identification based on `span.kind`	`false`	no
`endpoint`	`string`	The host of the Datadog intake server to send traces to.	`"https://trace.agent.datadoghq.com"`	no
`ignore_resources`	`list(string)`	A blocklist of regular expressions can be provided to disable traces based on their resource name.		no
`peer_tags_aggregation`	`bool`	Enables aggregation of peer related tags in Datadog exporter	`false`	no
`peer_tags`	`list(string)`	List of supplementary peer tags that go beyond the defaults.		no
`span_name_as_resource_name`	`bool`	Use OpenTelemetry semantic convention for span naming	`true`	no
`span_name_remappings`	`map(string)`	A map of Datadog span operation name keys and preferred name values to update those names to.		no
`trace_buffer`	`number`	Specifies the number of outgoing trace payloads to buffer before dropping	`10`	no

If compute_stats_by_span_kind is disabled, only top-level and measured spans will have stats computed. If you are sending OTel traces and want stats on non-top-level spans, this flag must be set to true. If you are sending OTel traces and don’t want stats computed by span kind, you must disable this flag and disable compute_top_level_by_span_kind.

If endpoint is unset, the value is obtained through the site parameter in the [api][] section.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.datadog is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.datadog doesn’t expose any component-specific debug information.

Example

Forward Prometheus Metrics

This example forwards Prometheus metrics from Alloy through a receiver for conversion to Open Telemetry format before finally sending them to Datadog. If you are using the US Datadog APIs, the api field is required for the exporter to function.

prometheus.exporter.self "default" {
}

prometheus.scrape "metamonitoring" {
  targets    = prometheus.exporter.self.default.targets
  forward_to = [otelcol.receiver.prometheus.default.receiver]
}

otelcol.receiver.prometheus "default" {
  output {
    metrics = [otelcol.exporter.datadog.default.input]
  }
}


otelcol.exporter.datadog "default" {
    api {
        api_key = "API_KEY"
    }

     metrics {
        endpoint = "https://api.ap1.datadoghq.com"
        resource_attributes_as_tags = true
    }
}

Full OTel pipeline

This example forwards metrics and traces received in Datadog format to Alloy, converts them to OTel format, and exports them to Datadog.

otelcol.receiver.datadog "default" {
    output {
        metrics = [otelcol.exporter.otlphttp.default.input, otelcol.exporter.datadog.default input]
        traces  = [otelcol.exporter.otlphttp.default.input, otelcol.exporter.datadog.default.input]
    }
}

otelcol.exporter.otlphttp "default" {
    client {
        endpoint = "database:4317"
    }
}

otelcol.exporter.datadog "default" {
    client {
        timeout = "10s"
    }

    api {
        api_key             = "abc"
        fail_on_invalid_key = true
    }

    traces {
        endpoint             = "https://trace.agent.datadoghq.com"
        ignore_resources     = ["(GET|POST) /healthcheck"]
        span_name_remappings = {
            "instrumentation:express.server" = "express",
        }
    }

    metrics {
        delta_ttl = 1200
        endpoint  = "https://api.datadoghq.com"

        exporter {
            resource_attributes_as_tags = true
        }

        histograms {
            mode = "counters"
        }

        sums {
            initial_cumulative_monotonic_value = "keep"
        }

        summaries {
            mode = "noquantiles"
        }
    }
}

Compatible components

otelcol.exporter.datadog has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.debug

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.debug`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.exporter.debug accepts telemetry data from other otelcol components and writes them to the console (stderr). You can control the verbosity of the logs.

Note
otelcol.exporter.debug is a wrapper over the upstream OpenTelemetry Collector debug exporter. If necessary, bug reports or feature requests are redirected to the upstream repository.

You can specify multiple otelcol.exporter.debug components by giving them different labels.

Usage

otelcol.exporter.debug "<LABEL>" { }

Arguments

You can use the following arguments with otelcol.exporter.debug:

Name	Type	Description	Default	Required
`output_paths`	`list(string)`	Output destinations used when `use_internal_logger` is `false`.	`["stdout"]`	no
`sampling_initial`	`int`	Number of messages initially logged each second.	`2`	no
`sampling_thereafter`	`int`	Sampling rate after the initial messages are logged.	`1`	no
`use_internal_logger`	`bool`	Whether to use the internal logger or print directly to `stderr`.	`true`	no
`verbosity`	`string`	Verbosity of the generated logs.	`"basic"`	no

The verbosity argument must be one of:

"basic": A single-line summary of received data is logged to stderr, with a total count of telemetry records for every batch of received logs, metrics, or traces.
"normal": Produces the same output as "basic" verbosity.
"detailed": All details of every telemetry record are logged to stderr, typically writing multiple lines for every telemetry record.

The following example shows "basic" and "normal" output:

ts=2024-06-13T11:24:13.782957Z level=info msg=TracesExporter component_path=/ component_id=otelcol.exporter.debug.default "resource spans": 1, spans: 2

The following example shows "detailed" output:

ts=2024-06-13T11:24:13.782957Z level=info msg=TracesExporter component_path=/ component_id=otelcol.exporter.debug.default "resource spans"=1 spans=2
ts=2024-06-13T11:24:13.783101Z level=info msg="ResourceSpans #0
Resource SchemaURL: https://opentelemetry.io/schemas/1.4.0
Resource attributes:
     -> service.name: Str(telemetrygen)
ScopeSpans #0
ScopeSpans SchemaURL:
InstrumentationScope telemetrygen
Span #0
    Trace ID       : 3bde5d3ee82303571bba6e1136781fe4
    Parent ID      : 5e9dcf9bac4acc1f
    ID             : 2cf3ef2899aba35c
    Name           : okey-dokey
    Kind           : Server
    Start time     : 2023-11-11 04:49:03.509369393 +0000 UTC
    End time       : 2023-11-11 04:49:03.50949377 +0000 UTC
    Status code    : Unset
    Status message :
Attributes:
     -> net.peer.ip: Str(1.2.3.4)
     -> peer.service: Str(telemetrygen-client)
Span #1
    Trace ID       : 3bde5d3ee82303571bba6e1136781fe4
    Parent ID      :
    ID             : 5e9dcf9bac4acc1f
    Name           : lets-go
    Kind           : Client
    Start time     : 2023-11-11 04:49:03.50935117 +0000 UTC
    End time       : 2023-11-11 04:49:03.50949377 +0000 UTC
    Status code    : Unset
    Status message :
Attributes:
     -> net.peer.ip: Str(1.2.3.4)
     -> peer.service: Str(telemetrygen-server)
        {"kind": "exporter", "data_type": "traces", "name": "debug"}"

Note
All instances of \n in the "detailed" example have been replaced with new lines.

Setting use_internal_logger to false is useful if you would like to see actual new lines instead of \n in the collector logs. However, by not using the internal logger you wouldn’t see metadata in the log line such as component_id=otelcol.exporter.debug.default. Multiline logs may also be harder to parse.

The output_paths argument can be used only when use_internal_logger is false. Valid values include stdout, stderr, or file paths.

Blocks

You can use the following block with otelcol.exporter.debug:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.debug is only reported as unhealthy if given an invalid configuration.

Debug information

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

Example

This example receives OTLP metrics, logs, and traces and writes them to the console:

otelcol.receiver.otlp "default" {
    grpc {}
    http {}

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

otelcol.exporter.debug "default" {}

Compatible components

otelcol.exporter.debug has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.faro

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.faro`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.exporter.faro accepts logs and traces telemetry data from other otelcol components and sends it to Faro endpoint. Use this exporter to send telemetry data to Grafana Cloud Collector Endpoint for Frontend Observability or to any backend that supports Faro format, allowing you to gain insights into the end user experience of your web application.

Note
This component is necessary for Grafana Cloud Frontend Observability to work. For more information, refer to the Choose a component guide.

Note
otelcol.exporter.faro is a wrapper over the upstream OpenTelemetry Collector faro exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.faro components by giving them different labels.

Usage

otelcol.exporter.faro "<LABEL>" {
    client {
        endpoint = "<HOST>:<PORT>"
    }
}

Arguments

The otelcol.exporter.faro component doesn’t support any arguments. You can configure this component with blocks.

Blocks

You can use the following blocks with otelcol.exporter.faro:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`client`

Required

The client block configures the HTTP client used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	The target URL to send telemetry data to.		yes
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`disable_keep_alives`	`bool`	Disable HTTP keep-alive.	`false`	no
`force_attempt_http2`	`bool`	Force the HTTP client to try to use the HTTP/2 protocol.	`true`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`http2_ping_timeout`	`duration`	Timeout after which the connection will be closed if a response to Ping isn’t received.	`"15s"`	no
`http2_read_idle_timeout`	`duration`	Timeout after which a health check using ping frame will be carried out if no frame is received on the connection.	`"0s"`	no
`idle_conn_timeout`	`duration`	Time to wait before an idle connection closes itself.	`"90s"`	no
`max_conns_per_host`	`int`	Limits the total (dialing,active, and idle) number of connections per host.	`0`	no
`max_idle_conns_per_host`	`int`	Limits the number of idle HTTP connections the host can keep open.	`0`	no
`max_idle_conns`	`int`	Limits the number of idle HTTP connections the client can keep open.	`100`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`read_buffer_size`	`string`	Size of the read buffer the HTTP client uses for reading server responses.	`0`	no
`timeout`	`duration`	Time to wait before marking a request as failed.	`"30s"`	no
`write_buffer_size`	`string`	Size of the write buffer the HTTP client uses for writing requests.	`"512KiB"`	no

When setting headers, note that:

Certain headers such as Content-Length and Connection are automatically written when needed and values in headers may be ignored.
The Host header is automatically derived from the endpoint value. However, this automatic assignment can be overridden by explicitly setting a Host header in headers.

Setting disable_keep_alives to true will result in significant overhead establishing a new HTTP or HTTPS connection for every request. Before enabling this option, consider whether changes to idle connection settings can achieve your goal.

If http2_ping_timeout is unset or set to 0s, it will default to 15s.

If http2_read_idle_timeout is unset or set to 0s, then no health check will be performed.

Golang’s default HTTP transport attempts HTTP/2 by default, however some settings (max_conns_per_host, max_idle_conns_per_host, max_idle_conns) are only relevant for HTTP/1. The force_attempt_http2 attribute allows a user to only attempt HTTP/1.

By default, requests are compressed with Gzip. The compression argument controls which compression mechanism to use. Supported strings are:

"gzip"
"zlib"
"deflate"
"snappy"
"zstd"

If you set compression to "none" or an empty string "", the requests aren’t compressed.

`compression_params`

The compression_params block configures the advanced compression options.

The following arguments are supported:

Name	Type	Description	Default	Required
`level`	`int`	Configure compression level.		yes

For valid combinations of client.compression and client.compression_params.level, refer to the upstream documentation.

`cookies`

The cookies block allows the HTTP client to store cookies from server responses and reuse them in subsequent requests.

This could be useful in situations such as load balancers relying on cookies for sticky sessions and enforcing a maximum session age.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	The target URL to send telemetry data to.	`false`	no

`tls`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`retry_on_failure`

The retry_on_failure block configures how failed requests to the HTTP server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for logs and traces.

Component health

otelcol.exporter.faro is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.faro doesn’t expose any component-specific debug information.

Example

This example creates an exporter to send data to a Faro endpoint.

otelcol.exporter.faro "default" {
    client {
        endpoint = "<FARO_COLLECTOR_ADDRESS>"
    }
}

Replace the following:

<FARO_COLLECTOR_ADDRESS>: The address of the Faro-compatible server to send data to.

Compatible components

otelcol.exporter.faro has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.file

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.file`

otelcol.exporter.file accepts metrics, logs, and traces telemetry data from other otelcol components and writes it to files on disk. You can write data in JSON or Protocol Buffers proto format. You can optionally enable file rotation, compression, and separate output files based on a resource attribute.

Note
otelcol.exporter.file is a wrapper over the upstream OpenTelemetry Collector Contrib fileexporter exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.file components by giving them different labels.

Usage

otelcol.exporter.file "<LABEL>" {
  path = "<PATH>"
}

Arguments

You can use the following arguments with otelcol.exporter.file:

Name	Type	Description	Default	Required
`path`	`string`	Path to the file to write telemetry data.		yes
`append`	`bool`	Append to the file when `true`; truncate when `false`.	`false`	no
`compression`	`string`	Compression algorithm. Alloy supports only `"zstd"`.		no
`flush_interval`	`duration`	Time between flushes to disk. Must be greater than zero.	`"1s"`	no
`format`	`string`	Data format. Must be `"json"` or `"proto"`.	`"json"`	no

You can’t enable append and compression together.

Note
The upstream encoding argument isn’t supported. Use format instead.

Blocks

You can use the following blocks with otelcol.exporter.file:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

You can’t enable append and rotation together.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`group_by`

The group_by block writes telemetry to separate files based on a resource attribute.

Name	Type	Description	Default	Required
`enabled`	`bool`	Enable `group_by` behavior.	`false`	no
`max_open_files`	`int`	Maximum number of simultaneously open files.	`100`	no
`resource_attribute`	`string`	Resource attribute whose value replaces `*` in `path`.	`"fileexporter.path_segment"`	no

When group_by.enabled is true:

path must contain exactly one * character.
The exporter replaces the * with the resource_attribute value.
rotation settings don’t apply.

`rotation`

The rotation block configures rolling log file behavior.

Name	Type	Description	Default	Required
`localtime`	`bool`	Use local time instead of UTC in rotated filenames.	`false`	no
`max_backups`	`int`	Maximum number of rotated files to retain.	`100`	no
`max_days`	`int`	Maximum number of days to retain files. `0` keeps files indefinitely.	`0`	no
`max_megabytes`	`int`	Maximum size in megabytes before the file rotates.	`100`	no

Exported fields

otelcol.exporter.file doesn’t export any fields.

Component health

otelcol.exporter.file is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.file doesn’t expose any component-specific debug information.

Examples

The following examples demonstrate how you can use otelcol.exporter.file.

Basic file export

otelcol.exporter.file "default" {
  path = "/tmp/traces.json"
}

File export with rotation

otelcol.exporter.file "rotated" {
  path   = "/var/log/telemetry.json"
  format = "json"

  rotation {
    max_megabytes = 50
    max_days      = 7
    max_backups   = 10
    localtime     = true
  }
}

File export with compression

otelcol.exporter.file "compressed" {
  path        = "/tmp/traces.jsonl"
  format      = "proto"
  compression = "zstd"
}

Group by resource attribute

otelcol.exporter.file "grouped" {
  path = "/tmp/logs/*/service.log"
  
  group_by {
    enabled           = true
    resource_attribute = "service.name"
    max_open_files     = 50
  }
}

Complete pipeline

otelcol.receiver.otlp "default" {
  grpc {
    endpoint = "0.0.0.0:4317"
  }

  http {
    endpoint = "0.0.0.0:4318"
  }

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

otelcol.exporter.file "default" {
  path           = "/tmp/telemetry.json"
  format         = "json"
  flush_interval = "5s"

  rotation {
    max_megabytes = 100
    max_backups   = 5
  }
}

Technical details

The otelcol.exporter.file component writes telemetry data to files on disk in either JSON or Protocol Buffers format. It supports:

File rotation: Automatically rotate files based on size, age, or number of backups
Compression: Compress output files using zstd algorithm
Group by attributes: Write to different files based on resource attribute values
Flushing: Configurable flush intervals to control write frequency

File formats

JSON format: Each telemetry record is written as a separate line in JSON format (JSONL)
proto format: Binary Protocol Buffers format with length-prefixed messages

File naming with rotation

When rotation is enabled, rotated files are renamed with a timestamp:

Original: data.json
Rotated: data-2023-09-20T10-30-00.123.json

Group by functionality

When group_by is enabled, files are created dynamically based on resource attribute values:

Path template: /logs/*/app.log
Resource attribute service.name=frontend
Resulting file: /logs/frontend/app.log

Compatible components

otelcol.exporter.file has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.googlecloud

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.googlecloud`

Community: This component is developed, maintained, and supported by the Alloy user community. Grafana doesn’t offer commercial support for this component. To enable and use community components, you must set the --feature.community-components.enabled flag to true.

Refer to Community components for more information.

otelcol.exporter.googlecloud accepts metrics, traces, and logs from other otelcol components and sends it to Google Cloud.

Note
otelcol.exporter.googlecloud is a wrapper over the upstream OpenTelemetry Collector googlecloud exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.googlecloud components by giving them different labels.

Usage

otelcol.exporter.googlecloud "<LABEL>" {
}

Authenticating

Refer to the original Google Cloud Exporter document.

Arguments

You can use the following arguments with otelcol.exporter.googlecloud:

Name	Type	Description	Default	Required
`project`	`string`	GCP project identifier.	Fetch from credentials	no
`destination_project_quota`	`bool`	Counts quota for traces and metrics against the project to which the data is sent as opposed to the project associated with the Collector’s service account. For example, when setting `project_id` or using multi-project export.	`false`	no
`user_agent`	`string`	Override the user agent string sent on requests to Cloud Monitoring (currently only applies to metrics). Specify `{{version}}` to include the application version number.	`"opentelemetry-collector-contrib {{version}}"`	no

Blocks

You can use the following blocks with otelcol.exporter.googlecloud:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`impersonate`

The following arguments are supported:

Name	Type	Description	Default	Required
`target_principal`	`string`	TargetPrincipal is the email address of the service account to impersonate.		yes
`delegates`	`list(string)`	Delegates are the service account email addresses in a delegation chain. Each service account must be granted roles/iam.serviceAccountTokenCreator on the next service account in the chain.	`[]`	no
`subject`	`string`	Subject is the sub field of a JWT. This field should only be set if you need to impersonate as a user. This feature is useful when using domain wide delegation.	`""`	no

`log`

The following arguments are supported:

Name	Type	Description	Default	Required
`compression`	`string`	Compression format for Log gRPC requests. Supported values: [`gzip`].	`""` (no compression)	no
`default_log_name`	`string`	Defines a default name for log entries. If left unset, and a log entry doesn’t have the `gcp.log_name` attribute set, the exporter returns an error processing that entry.	`""`	no
`endpoint`	`string`	Endpoint where log data is sent.	`logging.googleapis.com:443`	no
`error_reporting_type`	`bool`	Enables automatically parsing error logs to a JSON payload containing the type value for GCP Error Reporting.	`false`	no
`grpc_pool_size`	`number`	Sets the size of the connection pool in the GCP client.	`1`	no
`resource_filters`	`list(object)`	If provided, resource attributes matching any filter is included in log labels. Can be defined by `prefix`, `regex`, or `prefix` AND `regex`. Each object must contain one of `prefix` or `regex` or both.	`[]`	no
`resource_filters` > `prefix`	`string`	Match resource keys by prefix.	`""`	no
`resource_filters` > `regex`	`string`	Match resource keys by regular expression.	`""`	no
`service_resource_labels`	`bool`	If true, the exporter copies the OTel service.name, service.namespace, and service.instance.id resource attributes into the GCM timeseries metric labels.	`true`	no
`use_insecure`	`bool`	If true, disables gRPC client transport security. Only has effect if Endpoint isn’t `""`.	`false`	no

`metric`

The following arguments are supported:

Name	Type	Description	Default	Required
`compression`	`string`	Compression format for Metrics gRPC requests. Supported values: [`gzip`].	`""` (no compression)	no
`create_metric_descriptor_buffer_size`	`number`	Buffer size for the channel which asynchronously calls CreateMetricDescriptor.	`10`	no
`create_service_timeseries`	`bool`	If true, this sends all timeseries using `CreateServiceTimeSeries`. Implicitly, this sets `skip_create_descriptor` to true.	`false`	no
`cumulative_normalization`	`bool`	If true, normalizes cumulative metrics without start times or with explicit reset points by subtracting subsequent points from the initial point. Since it caches starting points, it may result in increased memory usage.	`true`	no
`endpoint`	`string`	Endpoint where metric data is sent to.	`"monitoring.googleapis.com:443"`	no
`grpc_pool_size`	`number`	Sets the size of the connection pool in the GCP client.	`1`	no
`instrumentation_library_labels`	`bool`	If true, set the `instrumentation_source` and `instrumentation_version` labels.	`true`	no
`known_domains`	`list(string)`	If a metric belongs to one of these domains it doesn’t get a prefix.	`["googleapis.com", "kubernetes.io", "istio.io", "knative.dev"]`	no
`prefix`	`string`	The prefix to add to metrics.	`"workload.googleapis.com"`	no
`resource_filters.prefix`	`string`	Match resource keys by prefix.	`""`	no
`resource_filters.regex`	`string`	Match resource keys by regular expression.	`""`	no
`resource_filters`	`list(object)`	If provided, resource attributes matching any filter is included in metric labels. Can be defined by `prefix`, `regex`, or `prefix` AND `regex`. Each object must contain one of `prefix` or `regex` or both.	`[]`	no
`service_resource_labels`	`bool`	If true, the exporter copies the OTel service.name, service.namespace, and service.instance.id resource attributes into the GCM timeseries metric labels.	`true`	no
`skip_create_descriptor`	`bool`	If set to true, don’t send metric descriptors to GCM.	`false`	no
`sum_of_squared_deviation`	`bool`	If true, enables calculation of an estimated sum of squared deviation. It’s an estimate, and isn’t exact.	`false`	no
`use_insecure`	`bool`	If true, disables gRPC client transport security. Only has effect if Endpoint isn’t `""`.	`false`	no

`experimental_wal`

The following arguments are supported:

Name	Type	Description	Default	Required
`directory`	`string`	Path to local directory for the WAL file.	`"./"`	yes
`max_backoff`	`string`	Max duration to retry requests on network errors (`UNAVAILABLE` or `DEADLINE_EXCEEDED`).	`"1h"`	no

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

`trace`

Name	Type	Description	Default	Required
`attribute_mappings`	`list(object)`	Determines how to map from OpenTelemetry attribute keys to Google Cloud Trace keys. By default, it changes HTTP and service keys so that they appear more prominently in the UI.	`[]`	no
`attribute_mappings` > `key`	`string`	The OpenTelemetry attribute key.	`""`	no
`attribute_mappings` > `replacement`	`string`	The attribute sent to Google Cloud Trace.	`""`	no
`endpoint`	`string`	Endpoint where trace data is sent.	`"cloudtrace.googleapis.com:443"`	no
`grpc_pool_size`	`int`	Sets the size of the connection pool in the GCP client. Defaults to a single connection.	`1`	no
`use_insecure`	`bool`	If true, disables gRPC client transport security. Only has effect if Endpoint isn’t `""`.	`false`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.googlecloud is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.googlecloud doesn’t expose any component-specific debug information.

Example

This example scrapes logs from local files through a receiver for conversion to OpenTelemetry format before finally sending them to Cloud Logging.

This configuration includes the recommended memory_limiter and batch plugins, which avoid high latency for reporting telemetry, and ensure that the collector itself will stay stable (not run out of memory) by dropping telemetry if needed.

local.file_match "logs" {
  path_targets = [{
    __address__ = "localhost",
    __path__    = "/var/log/{syslog,messages,*.log}",
    instance    = constants.hostname,
    job         = "integrations/node_exporter",
  }]
}

loki.source.file "logs" {
  targets    = local.file_match.logs.targets
  forward_to = [otelcol.receiver.loki.gcp.receiver]
}

otelcol.receiver.loki "gcp" {
  output {
    logs = [otelcol.processor.memory_limiter.gcp.input]
  }
}

otelcol.processor.memory_limiter "gcp" {
  check_interval = "1s"
  limit = "200MiB"

  output {
    metrics = [otelcol.processor.batch.gcp.input]
    logs = [otelcol.processor.batch.gcp.input]
    traces = [otelcol.processor.batch.gcp.input]
  }
}

otelcol.processor.batch "gcp" {
  output {
    metrics = [otelcol.exporter.googlecloud.default.input]
    logs = [otelcol.exporter.googlecloud.default.input]
    traces = [otelcol.exporter.googlecloud.default.input]
  }
}

otelcol.exporter.googlecloud "default" {
  project = "my-gcp-project"
  log {
    default_log_name = "opentelemetry.io/collector-exported-log"
  }
}

Compatible components

otelcol.exporter.googlecloud has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.googlecloudpubsub

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.googlecloudpubsub`

Community: This component is developed, maintained, and supported by the Alloy user community. Grafana doesn’t offer commercial support for this component. To enable and use community components, you must set the --feature.community-components.enabled flag to true.

Refer to Community components for more information.

otelcol.exporter.googlecloudpubsub accepts metrics, traces, and logs from other otelcol components and sends it to Google Cloud Pub/Sub Topic.

Note
otelcol.exporter.googlecloudpubsub is a wrapper over the upstream OpenTelemetry Collector googlecloudpubsub exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.googlecloudpubsub components by giving them different labels.

Usage

otelcol.exporter.googlecloudpubsub "<LABEL>" {
    project = "<PROJECT-ID>"
    topic   = "projects/<PROJECT-ID>/topics/<TOPIC-NAME>"
}

Authenticating

Refer to the Google Cloud Pub/Sub Exporter and Google Cloud Exporter documentation for more detailed information about authentication.

Arguments

You can use the following arguments with otelcol.exporter.googlecloudpubsub:

Name	Type	Description	Default	Required
`topic`	`string`	The topic name to send OTLP data over. The topic name should be a fully qualified resource name, for example, `projects/otel-project/topics/otlp`.	`""`	yes
`compression`	`string`	The compression used on the data sent to the topic. Only `gzip` is supported. Default is no compression.	`""`	no
`endpoint`	`string`	Override the default Pub/Sub endpoint. This is useful when connecting to the Pub/Sub emulator instance or switching between global and regional service endpoints.	`""`	no
`insecure`	`bool`	Allows performing insecure SSL connections and transfers. This is useful when connecting to a local emulator instance. Only has effect if you set `endpoint`.	`false`	no
`project`	`string`	Google Cloud Platform project identifier.	Fetch from credentials	no
`timeout`	`Duration`	Timeout for calls to the Pub/Sub API.	`"12s"`	no
`user_agent`	`string`	Override the user agent string on requests to Cloud Monitoring. This only applies to metrics. Specify `{{version}}` to include the application version number.	`"opentelemetry-collector-contrib {{version}}"`	no

Blocks

You can use the following blocks with otelcol.exporter.googlecloudpubsub:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`ordering`

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	Enables ordering.	`false`	no
`from_resource_attribute`	`string`	Resource attribute used as the ordering key. Required when `enabled` is `true`. If the resource attribute is missing or has an empty value, messages aren’t ordered for this resource.	`""`	no
`remove_resource_attribute`	`string`	Whether the ordering key resource attribute specified `from_resource_attribute` should be removed from the resource attributes.	`""`	no

`retry_on_failure`

The retry_on_failure block configures how failed requests to Datadog are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

`sending_queue`

The sending_queue block configures an in-memory buffer of batches before data is sent to the HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`watermark`

The following arguments are supported:

Name	Type	Description	Default	Required
`behavior`	`string`	`current` sets the `ce-time` attribute to the system clock, `earliest` sets the attribute to the smallest timestamp of all the messages.	`""`	no
`allow_drift`	`Duration`	The maximum difference the `ce-time` attribute can have from the system clock. If you set `allow_drift` to `0s` and `behavior` to `earliest`, the maximum drift from the clock is allowed.	`0s`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal , including metrics, logs, and traces.

Component health

otelcol.exporter.googlecloudpubsub is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.googlecloudpubsub doesn’t expose any component-specific debug information.

Example

This example scrapes logs from local files through a receiver for conversion to OpenTelemetry format before finally sending them to Pub/Sub.

This configuration includes the recommended memory_limiter and batch plugins, which avoid high reporting latency and ensure the collector stays stable by dropping telemetry when memory limits are reached.

local.file_match "logs" {
  path_targets = [{
    __address__ = "localhost",
    __path__    = "/var/log/{syslog,messages,*.log}",
    instance    = constants.hostname,
    job         = "integrations/node_exporter",
  }]
}

loki.source.file "logs" {
  targets    = local.file_match.logs.targets
  forward_to = [otelcol.receiver.loki.gcp.receiver]
}

otelcol.receiver.loki "gcp" {
  output {
    logs = [otelcol.processor.memory_limiter.gcp.input]
  }
}

otelcol.processor.memory_limiter "gcp" {
  check_interval = "1s"
  limit = "200MiB"

  output {
    metrics = [otelcol.processor.batch.gcp.input]
    logs = [otelcol.processor.batch.gcp.input]
    traces = [otelcol.processor.batch.gcp.input]
  }
}

otelcol.processor.batch "gcp" {
  output {
    metrics = [otelcol.exporter.googlecloudpubsub.default.input]
    logs = [otelcol.exporter.googlecloudpubsub.default.input]
    traces = [otelcol.exporter.googlecloudpubsub.default.input]
  }
}

otelcol.exporter.googlecloudpubsub "default" {
  project = "my-gcp-project"
  topic = "projects/<my-gcp-project>/topics/my-pubsub-topic"
}

Compatible components

otelcol.exporter.googlecloudpubsub has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.kafka

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.kafka`

otelcol.exporter.kafka accepts logs, metrics, and traces telemetry data from other otelcol components and sends it to Kafka.

It’s important to use otelcol.exporter.kafka together with otelcol.processor.batch to make sure otelcol.exporter.kafka doesn’t slow down due to sending Kafka a huge number of small payloads.

Note
otelcol.exporter.kafka is a wrapper over the upstream OpenTelemetry Collector kafka exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Multiple otelcol.exporter.kafka components can be specified by giving them different labels.

Usage

otelcol.exporter.kafka "LABEL" {
  protocol_version = "PROTOCOL_VERSION"
}

Arguments

You can use the following arguments with otelcol.exporter.kafka:

Name	Type	Description	Default	Required
`protocol_version`	`string`	Kafka protocol version to use.		yes
`brokers`	`list(string)`	Kafka brokers to connect to.	`["localhost:9092"]`	no
`allow_auto_topic_creation`	`bool`	Whether to allow automatic topic creation.	`true`	no
`client_id`	`string`	Consumer client ID to use. The ID will be used for all produce requests.	`"otel-collector"`	no
`conn_idle_timeout`	`duration`	Time after which idle connections are not reused and may be closed.	`"9m"`	no
`encoding`	`string`	(Deprecated) Encoding of payload read from Kafka.	`"otlp_proto"`	no
`include_metadata_keys`	`list(string)`	List of metadata keys to propagate as Kafka message headers.	`[]`	no
`partition_metrics_by_resource_attributes`	`bool`	Whether to include the hash of sorted resource attributes as the message partitioning key in metric messages sent to Kafka.	`false`	no
`partition_logs_by_resource_attributes`	`bool`	Whether to include the hash of sorted resource attributes as the message partitioning key in log messages sent to Kafka.	`false`	no
`partition_logs_by_trace_id`	`bool`	Whether to use the 16-bit hex string of the trace ID as the message partitioning key in log messages sent to Kafka.	`false`	no
`partition_traces_by_id`	`bool`	Whether to include the trace ID as the message key in trace messages sent to Kafka.	`false`	no
`resolve_canonical_bootstrap_servers_only`	`bool`	Whether to resolve then reverse-lookup broker IPs during startup.	`false`	no
`timeout`	`duration`	The timeout for every attempt to send data to the backend.	`"5s"`	no
`topic_from_attribute`	`string`	A resource attribute whose value should be used as the message’s topic.	`""`	no
`topic`	`string`	(Deprecated) Kafka topic to send to.	See below	no

Warning
The topic and encoding arguments are deprecated in favor of the [logs][logs], [metrics][metrics], and [traces][traces] blocks.

When topic_from_metadata_key is set in a signal-specific block, it will take precedence over topic_from_attribute and topic arguments. When topic_from_attribute is set, it will take precedence over the topic arguments in [logs][logs], [metrics][metrics], and [traces][traces] blocks.

partition_traces_by_id doesn’t have any effect on Jaeger encoding exporters since Jaeger exporters include trace ID as the message key by default.

partition_logs_by_resource_attributes and partition_logs_by_trace_id are mutually exclusive and can’t both be true.

include_metadata_keys specifies metadata keys to propagate as Kafka message headers. If one or more keys aren’t found in the metadata, they are ignored. The keys also partition the data before export if sending_queue.batch is defined.

Blocks

You can use the following blocks with otelcol.exporter.kafka:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`logs`

The logs block configures how to send logs to Kafka brokers.

Name	Type	Description	Default	Required
`encoding`	`string`	The encoding for logs. Refer to Supported encodings.	`"otlp_proto"`	no
`topic`	`string`	The name of the Kafka topic to which logs will be exported.	`"otlp_logs"`	no
`topic_from_metadata_key`	`string`	The name of the metadata key whose value should be used as the message’s topic. Takes precedence over `topic_from_attribute` and `topic` settings.	`""`	no

`metrics`

The metrics block configures how to send metrics to Kafka brokers.

Name	Type	Description	Default	Required
`encoding`	`string`	The encoding for metrics. Refer to Supported encodings.	`"otlp_proto"`	no
`topic`	`string`	The name of the Kafka topic to which metrics will be exported.	`"otlp_metrics"`	no
`topic_from_metadata_key`	`string`	The name of the metadata key whose value should be used as the message’s topic. Takes precedence over `topic_from_attribute` and `topic` settings.	`""`	no

`traces`

The traces block configures how to send traces to Kafka brokers.

Name	Type	Description	Default	Required
`encoding`	`string`	The encoding for traces. Refer to Supported encodings.	`"otlp_proto"`	no
`topic`	`string`	The name of the Kafka topic to which traces will be exported.	`"otlp_spans"`	no
`topic_from_metadata_key`	`string`	The name of the metadata key whose value should be used as the message’s topic. Takes precedence over `topic_from_attribute` and `topic` settings.	`""`	no

`authentication`

The authentication block holds the definition of different authentication mechanisms to use when connecting to Kafka brokers. It doesn’t support any arguments and is configured fully through inner blocks.

`kerberos`

The kerberos block configures Kerberos authentication against the Kafka broker.

The following arguments are supported:

Name	Type	Description	Default	Required
`config_file`	`string`	Path to Kerberos location, for example, `/etc/krb5.conf`.		no
`disable_fast_negotiation`	`bool`	Disable PA-FX-FAST negotiation.	`false`	no
`keytab_file`	`string`	Path to keytab file, for example, `/etc/security/kafka.keytab`.		no
`password`	`secret`	Kerberos password to authenticate with.		no
`realm`	`string`	Kerberos realm.		no
`service_name`	`string`	Kerberos service name.		no
`use_keytab`	`string`	Enables using keytab instead of password.		no
`username`	`string`	Kerberos username to authenticate as.		yes

When use_keytab is false, the password argument is required. When use_keytab is true, the file pointed to by the keytab_file argument is used for authentication instead. At most one of password or keytab_file must be provided.

disable_fast_negotiation is useful for Kerberos implementations which don’t support PA-FX-FAST (Pre-Authentication Framework - Fast) negotiation.

`plaintext`

Caution
The plaintext block has been deprecated. Use sasl with mechanism set to PLAIN instead.

The plaintext block configures plain text authentication against Kafka brokers.

The following arguments are supported:

Name	Type	Description	Default	Required
`password`	`secret`	Password to use for plain text authentication.		yes
`username`	`string`	Username to use for plain text authentication.		yes

`sasl`

The sasl block configures SASL authentication against Kafka brokers.

The following arguments are supported:

Name	Type	Description	Default	Required
`mechanism`	`string`	SASL mechanism to use when authenticating.		yes
`password`	`secret`	Password to use for SASL authentication.		yes
`username`	`string`	Username to use for SASL authentication.		yes
`version`	`number`	Version of the SASL Protocol to use when authenticating.	`0`	no

You can set the mechanism argument to one of the following strings:

"PLAIN"
"SCRAM-SHA-256"
"SCRAM-SHA-512"
"AWS_MSK_IAM_OAUTHBEARER"

When mechanism is set to "AWS_MSK_IAM_OAUTHBEARER", the aws_msk child block must also be provided.

You can set the version argument to either 0 or 1.

`aws_msk`

The aws_msk block configures extra parameters for SASL authentication when using the AWS_MSK_IAM_OAUTHBEARER mechanisms.

The following arguments are supported:

Name	Type	Description	Default	Required
`region`	`string`	AWS region the MSK cluster is based in.		yes

`tls`

The tls block configures TLS settings used for connecting to the Kafka brokers. If the tls block isn’t provided, TLS won’t be used for communication.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`metadata`

The metadata block configures how to retrieve and store metadata from the Kafka broker.

The following arguments are supported:

Name	Type	Description	Default	Required
`full`	`bool`	Whether to maintain a full set of metadata.	`true`	no
`refresh_interval`	`duration`	The frequency at which cluster metadata is refreshed.	`"10m"`	no

When full is set to false, the client does not make the initial request to broker at the startup.

Retrieving metadata may fail if the Kafka broker is starting up at the same time as the Alloy component. The retry child block can be provided to customize retry behavior.

`retry`

The retry block configures how to retry retrieving metadata when retrieval fails.

The following arguments are supported:

Name	Type	Description	Default	Required
`backoff`	`duration`	Time to wait between retries.	`"250ms"`	no
`max_retries`	`number`	How many times to reattempt retrieving metadata.	`3`	no

`producer`

The producer block configures how to retry retrieving metadata when retrieval fails.

The following arguments are supported:

Name	Type	Description	Default	Required
`compression`	`string`	The level of compression to use on messages.	`"none"`	no
`flush_max_messages`	`number`	The maximum number of messages in one request.	`10000`	no
`max_message_bytes`	`number`	The maximum permitted size of a message in bytes.	`1000000`	no
`required_acks`	`number`	Controls when a message is regarded as transmitted.	`1`	no

Refer to the Go sarama documentation for more information on required_acks.

compression could be set to either none, gzip, snappy, lz4, or zstd. Refer to the Go sarama documentation for more information.

`compression_params`

The compression_params block configures the producer compression parameters.

The following argument is supported:

Name	Type	Description	Default	Required
`level`	`int`	The level of compression to use on messages.	`0`	no

The following levels are valid combinations of compression and level:

Compression	Value	Description
`gzip`	`1`	BestSpeed
`gzip`	`9`	BestCompression
`gzip`	`-1`	DefaultCompression
`zstd`	`1`	SpeedFastest
`zstd`	`3`	SpeedDefault
`zstd`	`6`	SpeedBetterCompression
`zstd`	`11`	SpeedBestCompression

lz4 and snappy do not currently support compression levels in this component.

`retry_on_failure`

The retry_on_failure block configures how failed requests to Kafka are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Supported encodings

otelcol.exporter.kafka supports encoding extensions, as well as the following built-in encodings.

Available for all signals:

otlp_proto: Data is encoded as OTLP Protobuf.
otlp_json: Data is encoded as OTLP JSON.

Available only for traces:

jaeger_proto: The payload is serialized to a single Jaeger proto Span, and keyed by TraceID.
jaeger_json: The payload is serialized to a single Jaeger JSON Span using jsonpb, and keyed by TraceID.
zipkin_proto: The payload is serialized to Zipkin v2 proto Span.
zipkin_json: The payload is serialized to Zipkin v2 JSON Span.

Available only for logs:

raw: If the log record body is a byte array, it is sent as is. Otherwise, it is serialized to JSON. Resource and record attributes are discarded.

Component health

otelcol.exporter.kafka is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.kafka doesn’t expose any component-specific debug information.

Example

This example forwards telemetry data through a batch processor before finally sending it to Kafka:

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.batch.default.input]
    logs    = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.kafka.default.input]
    logs    = [otelcol.exporter.kafka.default.input]
    traces  = [otelcol.exporter.kafka.default.input]
  }
}

otelcol.exporter.kafka "default" {
  brokers          = ["localhost:9092"]
  protocol_version = "2.0.0"
}

Compatible components

otelcol.exporter.kafka has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.loadbalancing

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.loadbalancing`

otelcol.exporter.loadbalancing accepts logs and traces from other otelcol components and writes them over the network using the OpenTelemetry Protocol (OTLP) protocol.

Note
otelcol.exporter.loadbalancing is a wrapper over the upstream OpenTelemetry Collector loadbalancing exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.loadbalancing components by giving them different labels.

The decision which backend to use depends on the trace ID or the service name. The backend load doesn’t influence the choice. Even though this load-balancer won’t do round-robin balancing of the batches, the load distribution should be very similar among backends, with a standard deviation under 5% at the current configuration.

otelcol.exporter.loadbalancing is especially useful for backends configured with tail-based samplers which choose a backend based on the view of the full trace.

When a list of backends is updated, some of the signals will be rerouted to different backends. Around R/N of the “routes” will be rerouted differently, where:

A “route” is either a trace ID or a service name mapped to a certain backend.
“R” is the total number of routes.
“N” is the total number of backends.

This should be stable enough for most cases, and the larger the number of backends, the less disruption it should cause.

Usage

otelcol.exporter.loadbalancing "<LABEL>" {
  resolver {
    ...
  }
  protocol {
    otlp {
      client {}
    }
  }
}

Arguments

You can use the following arguments with otelcol.exporter.loadbalancing:

Name	Type	Description	Default	Required
`routing_key`	`string`	Routing strategy for load balancing.	`"traceID"`	no
`timeout`	`duration`	Time to wait before marking a request to the `otlp > protocol` exporter as failed.	`"0s"`	no

The routing_key attribute determines how to route signals across endpoints. Its value can be one of the following:

"service": spans, logs, and metrics with the same service.name will be exported to the same backend.

This is useful when using processors like the span metrics, so all spans for each service are sent to consistent Alloy instances for metric collection. Otherwise, metrics for the same services would be sent to different instances, making aggregations inaccurate.

"traceID": Spans and logs belonging to the same traceID will be exported to the same backend.
"resource": Metrics belonging to the same resource will be exported to the same backend.
"metric": Metrics with the same name will be exported to the same backend.
"streamID": Metrics with the same streamID will be exported to the same backend.

The loadbalancer configures the exporter for the signal types supported by the routing_key.

The timeout argument is similar to the top-level queue and retry blocks for otelcol.exporter.loadbalancing itself. It helps to re-route data into a new set of healthy backends. This is especially useful for highly elastic environments like Kubernetes, where the list of resolved endpoints changes frequently due to deployments and scaling events.

EXPERIMENTAL: Metrics support in otelcol.exporter.loadbalancing is an experimental feature. Experimental features are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental feature, you must set the stability.level flag to experimental.

Blocks

You can use the following blocks with otelcol.exporter.loadbalancing:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

There are two types of [queue][] and [retry][] blocks:

The queue and retry blocks under protocol > otlp. This is useful for temporary problems with a specific backend, like transient network issues.
The top-level queue and retry blocks for otelcol.exporter.loadbalancing. Those configuration options provide capability to re-route data into a new set of healthy backends. This is useful for highly elastic environments like Kubernetes, where the list of resolved endpoints changes frequently due to deployments and scaling events.

`resolver`

Required

The resolver block configures how to retrieve the endpoint to which this exporter will send data.

Inside the resolver block, either the [dns][dns] block or the [static][static] block should be specified. If both dns and static are specified, dns takes precedence.

`aws_cloud_map`

The aws_cloud_map block allows users to use otelcol.exporter.loadbalancing when using ECS over EKS in an AWS infrastructure.

The following arguments are supported:

Name	Type	Description	Default	Required
`namespace`	`string`	The CloudMap namespace where the service is registered.		yes
`service_name`	`string`	The name of the service which was specified when registering the instance.		yes
`health_status`	`string`	Ports to use with the IP addresses resolved from `service`.	`"HEALTHY"`	no
`interval`	`duration`	Resolver interval.	`"30s"`	no
`port`	`number`	Port to be used for exporting the traces to the addresses resolved from `service`.	`null`	no
`timeout`	`duration`	Resolver timeout.	`"5s"`	no

health_status can be set to either of:

HEALTHY: Only return instances that are healthy.
UNHEALTHY: Only return instances that are unhealthy.
ALL: Return all instances, regardless of their health status.
HEALTHY_OR_ELSE_ALL: Returns healthy instances, unless none are reporting a healthy state. In that case, return all instances. This is also called failing open.

If port isn’t set, a default port defined in CloudMap will be used.

Note
The aws_cloud_map resolver returns a maximum of 100 hosts. A feature request aims to cover pagination for this scenario.

`dns`

The dns block periodically resolves an IP address via the DNS hostname attribute. This IP address and the port specified via the port attribute will then be used by the gRPC exporter as the endpoint to which to export data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`hostname`	`string`	DNS hostname to resolve.		yes
`interval`	`duration`	Resolver interval.	`"5s"`	no
`port`	`string`	Port to be used with the IP addresses resolved from the DNS hostname.	`"4317"`	no
`timeout`	`duration`	Resolver timeout.	`"1s"`	no

`kubernetes`

You can use the kubernetes block to load balance across the pods of a Kubernetes service. The Kubernetes API notifies Alloy whenever a new Pod is added or removed from the service. The kubernetes resolver has a much faster response time than the dns resolver because it doesn’t require polling.

The following arguments are supported:

Name	Type	Description	Default	Required
`service`	`string`	Kubernetes service to resolve.		yes
`ports`	`list(number)`	Ports to use with the IP addresses resolved from `service`.	`[4317]`	no
`return_hostnames`	`bool`	Return hostnames instead of IPs.	`false`	no
`timeout`	`duration`	Resolver timeout.	`"1s"`	no

If no namespace is specified inside service, an attempt will be made to infer the namespace for this Alloy. If this fails, the default namespace will be used.

Each of the ports listed in ports will be used with each of the IPs resolved from service.

The “get”, “list”, and “watch” roles must be granted in Kubernetes for the resolver to work.

return_hostnames is useful in certain situations like using Istio in sidecar mode. To use this feature, the service argument must be a headless Service, pointing at a StatefulSet. Also, the service argument must be what’s specified under .spec.serviceName in the StatefulSet.

`static`

The static block configures a list of endpoints which this exporter will send data to.

The following arguments are supported:

Name	Type	Description	Default	Required
`hostnames`	`list(string)`	List of endpoints to export to.		yes

`protocol`

The protocol block configures protocol-related settings for exporting. At the moment only the OTLP protocol is supported.

`otlp`

The otlp block configures OTLP-related settings for exporting.

`client`

The client block configures the gRPC client used by the component. The endpoints used by the client block are the ones from the resolver block

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`authority`	`string`	Overrides the default `:authority` header in gRPC requests from the gRPC client.		no
`balancer_name`	`string`	Which gRPC client-side load balancer to use for requests.	`round_robin`	no
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`read_buffer_size`	`string`	Size of the read buffer the gRPC client to use for reading server responses.		no
`wait_for_ready`	`boolean`	Waits for gRPC connection to be in the `READY` state before sending data.	`false`	no
`write_buffer_size`	`string`	Size of the write buffer the gRPC client to use for writing requests.	`"512KiB"`	no

By default, requests are compressed with Gzip. The compression argument controls which compression mechanism to use. Supported strings are:

"gzip"
"zlib"
"deflate"
"snappy"
"zstd"

If you set compression to "none" or an empty string "", the requests aren’t compressed.

The supported values for balancer_name are listed in the gRPC documentation on Load balancing:

pick_first: Tries to connect to the first address. It uses the address for all RPCs if it connects, or if it fails, it tries the next address and keeps trying until one connection is successful. Because of this, all the RPCs are sent to the same backend.
round_robin: Connects to all the addresses it sees and sends an RPC to each backend one at a time in order. For example, the first RPC is sent to backend-1, the second RPC is sent to backend-2, and the third RPC is sent to backend-1.

The :authority header in gRPC specifies the host to which the request is being sent. It’s similar to the Host header in HTTP requests. By default, the value for :authority is derived from the endpoint URL used for the gRPC call. Overriding :authority could be useful when routing traffic using a proxy like Envoy, which makes routing decisions based on the value of the :authority header.

You can configure an HTTP proxy with the following environment variables:

HTTPS_PROXY
NO_PROXY

The HTTPS_PROXY environment variable specifies a URL to use for proxying requests. Connections to the proxy are established via the HTTP CONNECT method.

The NO_PROXY environment variable is an optional list of comma-separated hostnames for which the HTTPS proxy should not be used. Each hostname can be provided as an IP address (1.2.3.4), an IP address in CIDR notation (1.2.3.4/8), a domain name (example.com), or *. A domain name matches that domain and all subdomains. A domain name with a leading “.” (.example.com) matches subdomains only. NO_PROXY is only read when HTTPS_PROXY is set.

Because otelcol.exporter.loadbalancing uses gRPC, the configured proxy server must be able to handle and proxy HTTP/2 traffic.

`keepalive`

The keepalive block configures keepalive settings for gRPC client connections.

The following arguments are supported:

Name	Type	Description	Required
`ping_wait`	`duration`	How often to ping the server after no activity.	no
`ping_response_timeout`	`duration`	Time to wait before closing inactive connections if the server doesn’t respond to a ping.	no
`ping_without_stream`	`boolean`	Send pings even if there is no active stream request.	no

`tls`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

`queue`

The queue block configures an in-memory buffer of batches before data is sent to the gRPC server.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

`retry`

The retry block configures how failed requests to the gRPC server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

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

logs
traces

Choose a load balancing strategy

Different Alloy components require different load-balancing strategies. The use of otelcol.exporter.loadbalancing is only necessary for stateful components.

`otelcol.processor.tail_sampling`

All spans for a given trace ID must go to the same tail sampling Alloy instance.

This can be done by configuring otelcol.exporter.loadbalancing with routing_key = "traceID".
If you don’t configure routing_key = "traceID", the sampling decision may be incorrect. The tail sampler must have a full view of the trace when making a sampling decision. For example, a rate_limiting tail sampling strategy may incorrectly pass through more spans than expected if the spans for the same trace are spread out to more than one Alloy instance.

`otelcol.connector.spanmetrics`

All spans for a given service.name must go to the same spanmetrics Alloy.

This can be done by configuring otelcol.exporter.loadbalancing with routing_key = "service".
If you do not configure routing_key = "service", metrics generated from spans might be incorrect. For example, if similar spans for the same service.name end up on different Alloy instances, the two Alloy instances will have identical metric series for calculating span latency, errors, and number of requests. When both Alloy instances attempt to write the metrics to a database such as Mimir, the series may clash with each other. At best, this will lead to an error in Alloy and a rejected write to the metrics database. At worst, it could lead to inaccurate data due to overlapping samples for the metric series.

However, there are ways to scale otelcol.connector.spanmetrics without the need for a load balancer:

Each Alloy could add an attribute such as collector.id to make its series unique. Then, for example, you could use a sum by PromQL query to aggregate the metrics from different Alloys. Unfortunately, an extra collector.id attribute has a downside that the metrics stored in the database will have higher cardinality.
Spanmetrics could be generated in the backend database instead of in Alloy. For example, span metrics can be generated in Grafana Cloud by the Tempo traces database.

`otelcol.connector.servicegraph`

It’s challenging to scale otelcol.connector.servicegraph over multiple Alloy instances. For otelcol.connector.servicegraph to work correctly, each “client” span must be paired with a “server” span to calculate metrics such as span duration. If a “client” span goes to one Alloy, but a “server” span goes to another Alloy, then no single Alloy will be able to pair the spans and a metric won’t be generated.

otelcol.exporter.loadbalancing can solve this problem partially if it is configured with routing_key = "traceID". Each Alloy will then be able to calculate a service graph for each “client”/“server” pair in a trace. It’s possible to have a span with similar “server”/“client” values in a different trace, processed by another Alloy. If two different Alloy instances process similar “server”/“client” spans, they will generate the same service graph metric series. If the series from two Alloy are the same, this will lead to issues when writing them to the backend database. You could differentiate the series by adding an attribute such as "collector.id". The series from different Alloys can be aggregated using PromQL queries on the backed metrics database. If the metrics are stored in Grafana Mimir, cardinality issues due to "collector.id" labels can be solved using Adaptive Metrics.

A simpler, more scalable alternative to generating service graph metrics in Alloy is to generate them entirely in the backend database. For example, service graphs can be generated in Grafana Cloud by the Tempo traces database.

Mix stateful components

Different Alloy components may require a different routing_key for otelcol.exporter.loadbalancing. For example, otelcol.processor.tail_sampling requires routing_key = "traceID" whereas otelcol.connector.spanmetrics requires routing_key = "service". To load balance both types of components, two different sets of load balancers have to be set up:

One set of otelcol.exporter.loadbalancing with routing_key = "traceID", sending spans to Alloys doing tail sampling and no span metrics.
Another set of otelcol.exporter.loadbalancing with routing_key = "service", sending spans to Alloys doing span metrics and no service graphs.

Unfortunately, this can also lead to side effects. For example, if otelcol.connector.spanmetrics is configured to generate exemplars, the tail sampling Alloys might drop the trace that the exemplar points to. There is no coordination between the tail sampling Alloys and the span metrics Alloys to make sure trace IDs for exemplars are kept.

Component health

otelcol.exporter.loadbalancing is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.loadbalancing doesn’t expose any component-specific debug information.

Examples

Static resolver

This example accepts OTLP logs and traces over gRPC. It then sends them in a load-balanced way to "localhost:55690" or "localhost:55700".

otelcol.receiver.otlp "default" {
    grpc {}
    output {
        traces  = [otelcol.exporter.loadbalancing.default.input]
        logs    = [otelcol.exporter.loadbalancing.default.input]
    }
}

otelcol.exporter.loadbalancing "default" {
    resolver {
        static {
            hostnames = ["localhost:55690", "localhost:55700"]
        }
    }
    protocol {
        otlp {
            client {}
        }
    }
}

DNS resolver

When configured with a dns resolver, otelcol.exporter.loadbalancing will do a DNS lookup on regular intervals. Spans are exported to the addresses the DNS lookup returned.

otelcol.exporter.loadbalancing "default" {
    resolver {
        dns {
            hostname = "alloy-traces-sampling.grafana-cloud-monitoring.svc.cluster.local"
            port     = "34621"
            interval = "5s"
            timeout  = "1s"
        }
    }
    protocol {
        otlp {
            client {}
        }
    }
}

The following example shows a Kubernetes configuration that configures two groups of Alloy instances:

A pool of load-balancer Alloy instances:
- Spans are received from instrumented applications via otelcol.receiver.otlp
- Spans are exported via otelcol.exporter.loadbalancing.
A pool of sampling Alloy instances:
- The sampling Alloys run behind a headless service to enable the load-balancer Alloys to discover them.
- Spans are received from the load-balancer Alloys via otelcol.receiver.otlp
- Traces are sampled via otelcol.processor.tail_sampling.
- The traces are exported via otelcol.exporter.otlp to an OTLP-compatible database such as Tempo.

apiVersion: v1
kind: Namespace
metadata:
  name: grafana-cloud-monitoring
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: k6-trace-generator
  namespace: grafana-cloud-monitoring
spec:
  minReadySeconds: 10
  replicas: 1
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      name: k6-trace-generator
  template:
    metadata:
      labels:
        name: k6-trace-generator
    spec:
      containers:
      - env:
        - name: ENDPOINT
          value: alloy-traces-lb.grafana-cloud-monitoring.svc.cluster.local:9411
        image: ghcr.io/grafana/xk6-client-tracing:v0.0.2
        imagePullPolicy: IfNotPresent
        name: k6-trace-generator
---
apiVersion: v1
kind: Service
metadata:
  name: alloy-traces-lb
  namespace: grafana-cloud-monitoring
spec:
  clusterIP: None
  ports:
  - name: alloy-traces-otlp-grpc
    port: 9411
    protocol: TCP
    targetPort: 9411
  selector:
    name: alloy-traces-lb
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: alloy-traces-lb
  namespace: grafana-cloud-monitoring
spec:
  minReadySeconds: 10
  replicas: 1
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      name: alloy-traces-lb
  template:
    metadata:
      labels:
        name: alloy-traces-lb
    spec:
      containers:
      - args:
        - run
        - /etc/alloy/alloy_lb.alloy
        command:
        - /bin/alloy
        image: grafana/alloy:v1.0
        imagePullPolicy: IfNotPresent
        name: alloy-traces
        ports:
        - containerPort: 9411
          name: otlp-grpc
          protocol: TCP
        - containerPort: 34621
          name: alloy-lb
          protocol: TCP
        volumeMounts:
        - mountPath: /etc/alloy
          name: alloy-traces
      volumes:
      - configMap:
          name: alloy-traces
        name: alloy-traces
---
apiVersion: v1
kind: Service
metadata:
  name: alloy-traces-sampling
  namespace: grafana-cloud-monitoring
spec:
  clusterIP: None
  ports:
  - name: alloy-lb
    port: 34621
    protocol: TCP
    targetPort: alloy-lb
  selector:
    name: alloy-traces-sampling
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: alloy-traces-sampling
  namespace: grafana-cloud-monitoring
spec:
  minReadySeconds: 10
  replicas: 3
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      name: alloy-traces-sampling
  template:
    metadata:
      labels:
        name: alloy-traces-sampling
    spec:
      containers:
      - args:
        - run
        - /etc/alloy/alloy_sampling.alloy
        command:
        - /bin/alloy
        image: grafana/alloy:v1.0
        imagePullPolicy: IfNotPresent
        name: alloy-traces
        ports:
        - containerPort: 9411
          name: otlp-grpc
          protocol: TCP
        - containerPort: 34621
          name: alloy-lb
          protocol: TCP
        volumeMounts:
        - mountPath: /etc/alloy
          name: alloy-traces
      volumes:
      - configMap:
          name: alloy-traces
        name: alloy-traces
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: alloy-traces
  namespace: grafana-cloud-monitoring
data:
  alloy_lb.alloy: |
    otelcol.receiver.otlp "default" {
      grpc {
        endpoint = "0.0.0.0:9411"
      }
      output {
        traces = [otelcol.exporter.loadbalancing.default.input,otelcol.exporter.debug.default.input]
      }
    }

    otelcol.exporter.debug "default" {
      verbosity = "detailed"
    }

    otelcol.exporter.loadbalancing "default" {
      resolver {
        dns {
          hostname = "alloy-traces-sampling.grafana-cloud-monitoring.svc.cluster.local"
          port = "34621"
        }
      }
      protocol {
        otlp {
          client {
            tls {
              insecure = true
            }
          }
        }
      }
    }

  alloy_sampling.alloy: |
    otelcol.receiver.otlp "default" {
      grpc {
        endpoint = "0.0.0.0:34621"
      }
      output {
        traces = [otelcol.exporter.otlp.default.input,otelcol.exporter.debug.default.input]
      }
    }

    otelcol.exporter.debug "default" {
      verbosity = "detailed"
    }

    otelcol.exporter.otlp "default" {
      client {
        endpoint = "tempo-prod-06-prod-gb-south-0.grafana.net:443"
        auth     = otelcol.auth.basic.creds.handler
      }
    }

    otelcol.auth.basic "creds" {
      username = "111111"
      password = "pass"
    }

You must fill in the correct OTLP credentials prior to running the example. You can use k3d to start the example:

k3d cluster create alloy-lb-test
kubectl apply -f kubernetes_config.yaml

To delete the cluster, run:

k3d cluster delete alloy-lb-test

Kubernetes resolver

When you configure otelcol.exporter.loadbalancing with a kubernetes resolver, the Kubernetes API notifies Alloy whenever a new Pod is added or removed from the service. Spans are exported to the addresses from the Kubernetes API, combined with all the possible ports.

otelcol.exporter.loadbalancing "default" {
    resolver {
        kubernetes {
            service = "alloy-traces-headless"
            ports   = [ 34621 ]
        }
    }
    protocol {
        otlp {
            client {}
        }
    }
}

The following example shows a Kubernetes configuration that sets up two groups of Alloy instances:

A pool of load-balancer Alloys:
- Spans are received from instrumented applications via otelcol.receiver.otlp
- Spans are exported via otelcol.exporter.loadbalancing.
- The load-balancer Alloys will get notified by the Kubernetes API any time a Pod is added or removed from the pool of sampling Alloys.
A pool of sampling Alloyinstances:
- The sampling Alloy instances don’t need to run behind a headless service.
- Spans are received from the load-balancer Alloys via otelcol.receiver.otlp
- Traces are sampled via otelcol.processor.tail_sampling.
- The traces are exported via otelcol.exporter.otlp to a an OTLP-compatible database such as Tempo.

apiVersion: v1
kind: Namespace
metadata:
  name: grafana-cloud-monitoring
---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: alloy-traces
  namespace: grafana-cloud-monitoring
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: alloy-traces-role
  namespace: grafana-cloud-monitoring
rules:
- apiGroups:
  - ""
  resources:
  - endpoints
  verbs:
  - list
  - watch
  - get
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: alloy-traces-rolebinding
  namespace: grafana-cloud-monitoring
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: alloy-traces-role
subjects:
- kind: ServiceAccount
  name: alloy-traces
  namespace: grafana-cloud-monitoring
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: k6-trace-generator
  namespace: grafana-cloud-monitoring
spec:
  minReadySeconds: 10
  replicas: 1
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      name: k6-trace-generator
  template:
    metadata:
      labels:
        name: k6-trace-generator
    spec:
      containers:
      - env:
        - name: ENDPOINT
          value: alloy-traces-lb.grafana-cloud-monitoring.svc.cluster.local:9411
        image: ghcr.io/grafana/xk6-client-tracing:v0.0.2
        imagePullPolicy: IfNotPresent
        name: k6-trace-generator
---
apiVersion: v1
kind: Service
metadata:
  name: alloy-traces-lb
  namespace: grafana-cloud-monitoring
spec:
  clusterIP: None
  ports:
  - name: alloy-traces-otlp-grpc
    port: 9411
    protocol: TCP
    targetPort: 9411
  selector:
    name: alloy-traces-lb
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: alloy-traces-lb
  namespace: grafana-cloud-monitoring
spec:
  minReadySeconds: 10
  replicas: 1
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      name: alloy-traces-lb
  template:
    metadata:
      labels:
        name: alloy-traces-lb
    spec:
      containers:
      - args:
        - run
        - /etc/alloy/alloy_lb.alloy
        command:
        - /bin/alloy
        image: grafana/alloy:v1.0
        imagePullPolicy: IfNotPresent
        name: alloy-traces
        ports:
        - containerPort: 9411
          name: otlp-grpc
          protocol: TCP
        volumeMounts:
        - mountPath: /etc/alloy
          name: alloy-traces
      serviceAccount: alloy-traces
      volumes:
      - configMap:
          name: alloy-traces
        name: alloy-traces
---
apiVersion: v1
kind: Service
metadata:
  name: alloy-traces-sampling
  namespace: grafana-cloud-monitoring
spec:
  ports:
  - name: alloy-lb
    port: 34621
    protocol: TCP
    targetPort: alloy-lb
  selector:
    name: alloy-traces-sampling
  type: ClusterIP
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: alloy-traces-sampling
  namespace: grafana-cloud-monitoring
spec:
  minReadySeconds: 10
  replicas: 3
  revisionHistoryLimit: 1
  selector:
    matchLabels:
      name: alloy-traces-sampling
  template:
    metadata:
      labels:
        name: alloy-traces-sampling
    spec:
      containers:
      - args:
        - run
        - /etc/alloy/alloy_sampling.alloy
        command:
        - /bin/alloy
        image: grafana/alloy:v1.0
        imagePullPolicy: IfNotPresent
        name: alloy-traces
        ports:
        - containerPort: 34621
          name: alloy-lb
          protocol: TCP
        volumeMounts:
        - mountPath: /etc/alloy
          name: alloy-traces
      volumes:
      - configMap:
          name: alloy-traces
        name: alloy-traces
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: alloy-traces
  namespace: grafana-cloud-monitoring
data:
  alloy_lb.alloy: |
    otelcol.receiver.otlp "default" {
      grpc {
        endpoint = "0.0.0.0:9411"
      }
      output {
        traces = [otelcol.exporter.loadbalancing.default.input,otelcol.exporter.debug.default.input]
      }
    }

    otelcol.exporter.debug "default" {
      verbosity = "detailed"
    }

    otelcol.exporter.loadbalancing "default" {
      resolver {
        kubernetes {
          service = "alloy-traces-sampling"
          ports = ["34621"]
        }
      }
      protocol {
        otlp {
          client {
            tls {
              insecure = true
            }
          }
        }
      }
    }

  alloy_sampling.alloy: |
    otelcol.receiver.otlp "default" {
      grpc {
        endpoint = "0.0.0.0:34621"
      }
      output {
        traces = [otelcol.exporter.otlp.default.input,otelcol.exporter.debug.default.input]
      }
    }

    otelcol.exporter.debug "default" {
      verbosity = "detailed"
    }

    otelcol.exporter.otlp "default" {
      client {
        endpoint = "tempo-prod-06-prod-gb-south-0.grafana.net:443"
        auth     = otelcol.auth.basic.creds.handler
      }
    }

    otelcol.auth.basic "creds" {
      username = "111111"
      password = "pass"
    }

You must fill in the correct OTLP credentials prior to running the example. You can use k3d to start the example:

k3d cluster create alloy-lb-test
kubectl apply -f kubernetes_config.yaml

To delete the cluster, run:

k3d cluster delete alloy-lb-test

Compatible components

otelcol.exporter.loadbalancing has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.loki

Mon, 30 Mar 2026 15:47:22 +0000

`otelcol.exporter.loki`

otelcol.exporter.loki accepts OTLP-formatted logs from other otelcol components, converts them to Loki-formatted log entries, and forwards them to loki components.

Note
otelcol.exporter.loki is a custom component unrelated to the lokiexporter from the OpenTelemetry Collector.

The attributes of the OTLP log aren’t converted to Loki attributes by default. To convert them, the OTLP log should contain special “hint” attributes:

To convert OTLP resource attributes to Loki labels, use the loki.resource.labels hint attribute.
To convert OTLP log attributes to Loki labels, use the loki.attribute.labels hint attribute.

Labels will be translated to a Prometheus format, which is more constrained than the OTLP format. For examples on label translation, see the Convert OTLP attributes to Loki labels section.

Multiple otelcol.exporter.loki components can be specified by giving them different labels.

Usage

otelcol.exporter.loki "<LABEL>" {
  forward_to = [...]
}

Arguments

You can use the following argument with otelcol.exporter.loki:

Name	Type	Description	Default	Required
`forward_to`	`list(receiver)`	Where to forward converted Loki logs.		yes

Blocks

The otelcol.exporter.loki component doesn’t support any blocks. You can configure this component with arguments.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for logs. Other telemetry signals are ignored.

Logs sent to input are converted to Loki-compatible log entries and are forwarded to the forward_to argument in sequence.

Component health

otelcol.exporter.loki is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.loki doesn’t expose any component-specific debug information.

Examples

Basic usage

This example accepts OTLP logs over gRPC, transforms them and forwards the converted log entries to loki.write:

otelcol.receiver.otlp "default" {
  grpc {}

  output {
    logs = [otelcol.exporter.loki.default.input]
  }
}

otelcol.exporter.loki "default" {
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
    url = "loki:3100"
  }
}

Convert OTLP attributes to Loki labels

This example converts the following attributes to Loki labels:

The service.name and service.namespace OTLP resource attributes.
The event.domain and event.name OTLP log attributes.

Labels will be translated to a Prometheus format. For example:

OpenTelemetry Attribute	Prometheus Label
`name`	`name`
`host.name`	`host_name`
`host_name`	`host_name`
`name (of the host)`	`name__of_the_host_`
`2 cents`	`key_2_cents`
`__name`	`__name`
`_name`	`key_name`
`_name`	`_name` (if `PermissiveLabelSanitization` is enabled)

otelcol.receiver.otlp "default" {
  grpc {}

  output {
    logs = [otelcol.processor.attributes.default.input]
  }
}

otelcol.processor.attributes "default" {
  action {
    key = "loki.attribute.labels"
    action = "insert"
    value = "event.domain, event.name"
  }

  action {
    key = "loki.resource.labels"
    action = "insert"
    value = "service.name, service.namespace"
  }

  output {
    logs = [otelcol.exporter.loki.default.input]
  }
}

otelcol.exporter.loki "default" {
  forward_to = [loki.write.local.receiver]
}

loki.write "local" {
  endpoint {
      url = "loki:3100"
  }
}

Compatible components

otelcol.exporter.loki can accept arguments from the following components:

Components that export Loki LogsReceiver

otelcol.exporter.loki has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.otlp

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.otlp`

otelcol.exporter.otlp accepts telemetry data from other otelcol components and writes them over the network using the OTLP gRPC protocol.

Note
otelcol.exporter.otlp is a wrapper over the upstream OpenTelemetry Collector otlp exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.otlp components by giving them different labels.

Usage

otelcol.exporter.otlp "<LABEL>" {
  client {
    endpoint = "<HOST>:<PORT>"
  }
}

Arguments

You can use the following argument with otelcol.exporter.otlp:

Name	Type	Description	Default	Required
`timeout`	`duration`	Time to wait before marking a request as failed.	`"5s"`	no

Blocks

You can use the following blocks with otelcol.exporter.otlp:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`client`

Required

The client block configures the gRPC client used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to send telemetry data to.		yes
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`authority`	`string`	Overrides the default `:authority` header in gRPC requests from the gRPC client.		no
`balancer_name`	`string`	Which gRPC client-side load balancer to use for requests.	`"round_robin"`	no
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`read_buffer_size`	`string`	Size of the read buffer the gRPC client to use for reading server responses.		no
`wait_for_ready`	`boolean`	Waits for gRPC connection to be in the `READY` state before sending data.	`false`	no
`write_buffer_size`	`string`	Size of the write buffer the gRPC client to use for writing requests.	`"512KiB"`	no

By default, requests are compressed with Gzip. The compression argument controls which compression mechanism to use. Supported strings are:

"gzip"
"zlib"
"deflate"
"snappy"
"zstd"

If you set compression to "none" or an empty string "", the requests aren’t compressed.

The supported values for balancer_name are listed in the gRPC documentation on Load balancing:

pick_first: Tries to connect to the first address. It uses the address for all RPCs if it connects, or if it fails, it tries the next address and keeps trying until one connection is successful. Because of this, all the RPCs are sent to the same backend.
round_robin: Connects to all the addresses it sees and sends an RPC to each backend one at a time in order. For example, the first RPC is sent to backend-1, the second RPC is sent to backend-2, and the third RPC is sent to backend-1.

An HTTP proxy can be configured through the following environment variables:

HTTPS_PROXY
NO_PROXY

The HTTPS_PROXY environment variable specifies a URL to use for proxying requests. Connections to the proxy are established via the HTTP CONNECT method.

Because otelcol.exporter.otlp uses gRPC, the configured proxy server must be able to handle and proxy HTTP/2 traffic.

`keepalive`

The keepalive block configures keepalive settings for gRPC client connections.

The following arguments are supported:

Name	Type	Description	Required
`ping_wait`	`duration`	How often to ping the server after no activity.	no
`ping_response_timeout`	`duration`	Time to wait before closing inactive connections if the server doesn’t respond to a ping.	no
`ping_without_stream`	`boolean`	Send pings even if there is no active stream request.	no

`tls`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

Note
otelcol.exporter.otlp uses gRPC, which doesn’t allow you to send sensitive credentials like auth over insecure channels. Sending sensitive credentials over insecure non-TLS connections is supported by non-gRPC exporters such as otelcol.exporter.otlphttp.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`retry_on_failure`

The retry_on_failure block configures how failed requests to the gRPC server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.otlp is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.otlp doesn’t expose any component-specific debug information.

Debug metrics

otelcol_exporter_queue_capacity (gauge): Fixed capacity of the retry queue (in batches)
otelcol_exporter_queue_size (gauge): Current size of the retry queue (in batches)
otelcol_exporter_send_failed_spans_total (counter): Number of spans in failed attempts to send to destination.
otelcol_exporter_sent_spans_total (counter): Number of spans successfully sent to destination.
rpc_client_duration_milliseconds (histogram): Measures the duration of inbound RPC.
rpc_client_request_size_bytes (histogram): Measures size of RPC request messages (uncompressed).
rpc_client_requests_per_rpc (histogram): Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.
rpc_client_response_size_bytes (histogram): Measures size of RPC response messages (uncompressed).
rpc_client_responses_per_rpc (histogram): Measures the number of messages received per RPC. Should be 1 for all non-streaming RPCs.

Examples

The following examples show you how to create an exporter to send data to different destinations.

Send data to a local Tempo instance

You can create an exporter that sends your data to a local Grafana Tempo instance without TLS:

otelcol.exporter.otlp "tempo" {
    client {
        endpoint = "tempo:4317"
        tls {
            insecure             = true
            insecure_skip_verify = true
        }
    }
}

Send data to a managed service

You can create an otlp exporter that sends your data to a managed service, for example, Grafana Cloud. The Tempo username and Grafana Cloud API Key are injected in this example through environment variables.

otelcol.exporter.otlp "grafana_cloud_traces" {
    client {
        endpoint = "tempo-xxx.grafana.net/tempo:443"
        auth     = otelcol.auth.basic.grafana_cloud_traces.handler
    }
}
otelcol.auth.basic "grafana_cloud_traces" {
    username = sys.env("TEMPO_USERNAME")
    password = sys.env("GRAFANA_CLOUD_API_KEY")
}

Compatible components

otelcol.exporter.otlp has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.otlphttp

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.otlphttp`

otelcol.exporter.otlphttp accepts telemetry data from other otelcol components and writes them over the network using the OTLP HTTP protocol.

Note
otelcol.exporter.otlphttp is a wrapper over the upstream OpenTelemetry Collector otlphttp exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.otlphttp components by giving them different labels.

Usage

otelcol.exporter.otlphttp "<LABEL>" {
  client {
    endpoint = "<HOST>:<PORT>"
  }
}

Arguments

You can use the following arguments with otelcol.exporter.otlphttp:

Name	Type	Description	Default	Required
`encoding`	`string`	The encoding to use for messages. Should be either `"proto"` or `"json"`.	`"proto"`	no
`logs_endpoint`	`string`	The endpoint to send logs to.	`client.endpoint + "/v1/logs"`	no
`metrics_endpoint`	`string`	The endpoint to send metrics to.	`client.endpoint + "/v1/metrics"`	no
`traces_endpoint`	`string`	The endpoint to send traces to.	`client.endpoint + "/v1/traces"`	no

The default value depends on the endpoint field set in the required client block. If set, these arguments override the client.endpoint field for the corresponding signal.

Blocks

You can use the following blocks with otelcol.exporter.otlphttp:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`client`

Required

The client block configures the HTTP client used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	The target URL to send telemetry data to.		yes
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`disable_keep_alives`	`bool`	Disable HTTP keep-alive.	`false`	no
`force_attempt_http2`	`bool`	Force the HTTP client to try to use the HTTP/2 protocol.	`true`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`http2_ping_timeout`	`duration`	Timeout after which the connection will be closed if a response to Ping isn’t received.	`"15s"`	no
`http2_read_idle_timeout`	`duration`	Timeout after which a health check using ping frame will be carried out if no frame is received on the connection.	`"0s"`	no
`idle_conn_timeout`	`duration`	Time to wait before an idle connection closes itself.	`"90s"`	no
`max_conns_per_host`	`int`	Limits the total (dialing,active, and idle) number of connections per host.	`0`	no
`max_idle_conns_per_host`	`int`	Limits the number of idle HTTP connections the host can keep open.	`0`	no
`max_idle_conns`	`int`	Limits the number of idle HTTP connections the client can keep open.	`100`	no
`proxy_url`	`string`	HTTP proxy to send requests through.		no
`read_buffer_size`	`string`	Size of the read buffer the HTTP client uses for reading server responses.	`0`	no
`timeout`	`duration`	Time to wait before marking a request as failed.	`"30s"`	no
`write_buffer_size`	`string`	Size of the write buffer the HTTP client uses for writing requests.	`"512KiB"`	no

When setting headers, note that:

Certain headers such as Content-Length and Connection are automatically written when needed and values in headers may be ignored.
The Host header is automatically derived from the endpoint value. However, this automatic assignment can be overridden by explicitly setting a Host header in headers.

If http2_ping_timeout is unset or set to 0s, it will default to 15s.

If http2_read_idle_timeout is unset or set to 0s, then no health check will be performed.

By default, requests are compressed with Gzip. The compression argument controls which compression mechanism to use. Supported strings are:

"gzip"
"zlib"
"deflate"
"snappy"
"zstd"

If you set compression to "none" or an empty string "", the requests aren’t compressed.

`compression_params`

The compression_params block allows for configuration of advanced compression options.

The following arguments are supported:

Name	Type	Description	Default	Required
`level`	`int`	Configure compression level.		yes

For valid combinations of client.compression and client.compression_params.level, refer to the upstream documentation.

`cookies`

The cookies block allows the HTTP client to store cookies from server responses and reuse them in subsequent requests.

This could be useful in situations such as load balancers relying on cookies for sticky sessions and enforcing a maximum session age.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	The target URL to send telemetry data to.	`false`	no

`tls`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`retry_on_failure`

The retry_on_failure block configures how failed requests to the HTTP server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.otlphttp is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.otlphttp doesn’t expose any component-specific debug information.

Examples

Grafana Cloud

This example creates an exporter which can send OTLP logs, metrics, and traces to Grafana Cloud using basic authentication:

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = `https://otlp-gateway-prod-gb-south-0.grafana.net/otlp`
    auth     = otelcol.auth.basic.creds.handler
  }
}

otelcol.auth.basic "creds" {
  client_auth {
    username = sys.env("OTLP_USERNAME")
    password = sys.env("OTLP_API_KEY")
  }
}

Local Tempo database

This example creates an exporter to send data to a locally running Grafana Tempo without TLS:

otelcol.exporter.otlphttp "tempo" {
    client {
        endpoint = "http://tempo:4318"
        tls {
            insecure             = true
            insecure_skip_verify = true
        }
    }
}

Compatible components

otelcol.exporter.otlphttp has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.prometheus

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.prometheus`

otelcol.exporter.prometheus accepts OTLP-formatted metrics from other otelcol components, converts metrics to Prometheus-formatted metrics, and forwards the resulting metrics to prometheus components.

Note
otelcol.exporter.prometheus is a custom component unrelated to the prometheus exporter from OpenTelemetry Collector.

Conversion of metrics are done according to the OpenTelemetry Metrics Data Model specification.

You can specify multiple otelcol.exporter.prometheus components by giving them different labels.

Usage

otelcol.exporter.prometheus "<LABEL>" {
  forward_to = [...]
}

Arguments

You can use the following arguments with otelcol.exporter.prometheus:

Name	Type	Description	Default	Required
`forward_to`	`list(MetricsReceiver)`	Where to forward converted Prometheus metrics.		yes
`add_metric_suffixes`	`bool`	Whether to add type and unit suffixes to metric names.	`true`	no
`gc_frequency`	`duration`	How often to clean up stale metrics from memory.	`"5m"`	no
`honor_metadata`	`bool`	(Experimental) Whether to send metric metadata to downstream components.	`false`	no
`include_scope_info`	`bool`	Whether to include `otel_scope_info` metrics.	`false`	no
`include_scope_labels`	`bool`	Whether to include additional OTLP labels in all metrics.	`true`	no
`include_target_info`	`bool`	Whether to include `target_info` metrics.	`true`	no
`resource_to_telemetry_conversion`	`bool`	Whether to convert OTel resource attributes to Prometheus labels.	`false`	no

By default, OpenTelemetry resources are converted into target_info metrics. OpenTelemetry instrumentation scopes are converted into otel_scope_info metrics. Set the include_scope_info and include_target_info arguments to false, respectively, to disable the custom metrics.

Warning
EXPERIMENTAL: The honor_metadata argument is an experimental feature. If you enable this argument, resource consumption may increase, particularly if you ingest many metrics with different names. Some downstream components aren’t compatible with Prometheus metadata. The following components are compatible:

otelcol.receiver.prometheus

prometheus.remote_write only when configured for Remote Write v2.

prometheus.write_queue

When include_scope_labels is true the otel_scope_name and otel_scope_version labels are added to every converted metric sample.

When include_target_info is true, OpenTelemetry Collector resources are converted into target_info metrics.

Note
OTLP metrics can have a lot of resource attributes. Setting resource_to_telemetry_conversion to true would convert all of them to Prometheus labels, which may not be what you want. Instead of using resource_to_telemetry_conversion, most users need to use otelcol.processor.transform to convert OTLP resource attributes to OTLP metric datapoint attributes before using otelcol.exporter.prometheus. Refer to Create Prometheus labels from OTLP resource attributes for an example.

Blocks

You can use the following blocks with otelcol.exporter.prometheus:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for metrics. Other telemetry signals are ignored.

Metrics sent to the input are converted to Prometheus-compatible metrics and are forwarded to the forward_to argument.

The following are dropped during the conversion process:

Metrics that use the delta aggregation temporality.
Note
Prometheus doesn’t natively support delta metrics. If your Alloy instance ingests delta OTLP metrics, you can convert them to cumulative OTLP metrics with otelcol.processor.deltatocumulative before you use otelcol.exporter.prometheus.

Component health

otelcol.exporter.prometheus is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.prometheus doesn’t expose any component-specific debug information.

Example

Basic usage

This example accepts metrics over OTLP and forwards it using prometheus.remote_write:

otelcol.receiver.otlp "default" {
  grpc {}

  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

Create Prometheus labels from OTLP resource attributes

This example uses otelcol.processor.transform to add extra key1 and key2 OTLP metric datapoint attributes from the key1 and key2 OTLP resource attributes.

otelcol.exporter.prometheus then converts key1 and key2 to Prometheus labels along with any other OTLP metric datapoint attributes.

This avoids the need to set resource_to_telemetry_conversion to true, which could have created too many unnecessary metric labels.

otelcol.receiver.otlp "default" {
  grpc {}

  output {
    metrics = [otelcol.processor.transform.default.input]
  }
}

otelcol.processor.transform "default" {
  error_mode = "ignore"

  metric_statements {
    context = "datapoint"

    statements = [
      `set(attributes["key1"], resource.attributes["key1"])`,
      `set(attributes["key2"], resource.attributes["key2"])`,
    ]
  }

  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

Compatible components

otelcol.exporter.prometheus can accept arguments from the following components:

Components that export Prometheus MetricsReceiver

otelcol.exporter.prometheus has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.splunkhec

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.splunkhec`

Community: This component is developed, maintained, and supported by the Alloy user community. Grafana doesn’t offer commercial support for this component. To enable and use community components, you must set the --feature.community-components.enabled flag to true.

Refer to Community components for more information.

otelcol.exporter.splunkhec accepts metrics and traces telemetry data from other otelcol components and sends it to Splunk HEC.

Note
otelcol.exporter.splunkhec is a wrapper over the upstream OpenTelemetry Collector splunkhec exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.splunkhec components by giving them different labels.

Usage

otelcol.exporter.splunkhec "<LABEL>" {
    splunk {
        token = "<YOUR_SPLUNK_TOKEN>"
    }
    client {
        endpoint = "http://splunk.yourdomain.com:8088"
    }
}

Arguments

The otelcol.exporter.splunkhec component doesn’t support any arguments. You can configure this component with blocks.

Blocks

You can use the following blocks with otelcol.exporter.splunkhec:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`splunk`

Required

The splunk block configures Splunk HEC specific settings.

The following arguments are supported:

Name	Type	Description	Default	Required
`token`	`secret`	Splunk HEC Token.		yes
`disable_compression`	`bool`	Disable Gzip compression.	`false`	no
`export_raw`	`bool`	Send only the logs body when targeting HEC raw endpoint.	`false`	no
`health_check_enabled`	`bool`	Used to verify Splunk HEC health on exporter startup.	`true`	no
`health_path`	`string`	Path for the health API.	`"/services/collector/health"`	no
`index`	`string`	Splunk index name.	`""`	no
`log_data_enabled`	`bool`	Enable sending logs from the exporter. One of `log_data_enabled` or `profiling_data_enabled` must be `true`.	`true`	no
`max_content_length_logs`	`uint`	Maximum log payload size in bytes. Must be less than 838860800 (~800MB).	`2097152`	no
`max_content_length_metrics`	`uint`	Maximum metric payload size in bytes. Must be less than 838860800 (~800MB).	`2097152`	no
`max_content_length_traces`	`uint`	Maximum trace payload size in bytes. Must be less than 838860800 (~800MB).	`2097152`	no
`max_event_size`	`uint`	Maximum event payload size in bytes. Must be less than 838860800 (~800MB).	`5242880`	no
`profiling_data_enabled`	`bool`	Enable sending profiling data from the exporter. One of `log_data_enabled` or `profiling_data_enabled` must be `true`.	`true`	no
`sourcetype`	`string`	Splunk source type.	`""`	no
`source`	`string`	Splunk source.	`""`	no
`splunk_app_name`	`string`	Used to track telemetry for Splunk Apps by name.	`"Alloy"`	no
`splunk_app_version`	`string`	Used to track telemetry by App version.	`""`	no
`use_multi_metrics_format`	`bool`	Use multi-metrics format to save space during ingestion.	`false`	no

`batcher`

Warning
The batcher block is deprecated and will be removed in a future release. Use the sending_queue > batch block instead.

Name	Type	Description	Default	Required
`enabled`	`bool`	Whether to not enqueue batches before sending to the consumerSender.	`false`	no
`flush_timeout`	`duration`	The time after which a batch will be sent regardless of its size.	`"200ms"`	no
`max_size`	`uint`	The maximum size of a batch. If the batch exceeds this value, it’s broken up into smaller batches. Must be greater than or equal to `min_size`. Set this value to zero to disable the maximum size limit.	`0`	no
`min_size`	`uint`	The minimum size of a batch.	`8192`	no
`sizer`	`string`	The unit of measure for the batch size. Must be one of `items`, `bytes`, or `requests`.	`"items"`	no

`heartbeat`

Name	Type	Description	Default	Required
`interval`	`duration`	Time interval for the heartbeat interval, in seconds.	`"0s"`	no
`startup`	`bool`	Send heartbeat events on exporter startup.	`false`	no

`otel_to_hec_fields`

Name	Type	Description	Default	Required
`severity_number`	`string`	Maps severity number field to a specific HEC field.	`""`	no
`severity_text`	`string`	Maps severity text field to a specific HEC field.	`""`	no

`telemetry`

Name	Type	Description	Default	Required
`enabled`	`bool`	Enable telemetry inside the exporter.	`false`	no
`override_metrics_names`	`map(string)`	Override metrics for internal metrics in the exporter.		no

`client`

Required

The client block configures the HTTP client used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	The Splunk HEC endpoint to use.		yes
`force_attempt_http2`	`bool`	Force the HTTP client to try to use the HTTP/2 protocol.	`true`	no
`disable_keep_alives`	`bool`	Disable HTTP keep-alive.	`false`	no
`idle_conn_timeout`	`duration`	Time to wait before an idle connection closes itself.	`"45s"`	no
`insecure_skip_verify`	`bool`	Ignores insecure server TLS certificates.	`false`	no
`max_conns_per_host`	`int`	Limits the total (dialing,active, and idle) number of connections per host. Zero means no limit	`0`	no
`max_idle_conns_per_host`	`int`	Limits the number of idle HTTP connections the host can keep open.	`0`	no
`max_idle_conns`	`int`	Limits the number of idle HTTP connections the client can keep open.	`100`	no
`read_buffer_size`	`int`	Size of the read buffer the HTTP client uses for reading server responses.	`0`	no
`timeout`	`duration`	Time to wait before marking a request as failed.	`"15s"`	no
`write_buffer_size`	`int`	Size of the write buffer the HTTP client uses for writing requests.	`0`	no

`otel_attrs_to_hec_metadata`

The otel_attrs_to_hec_metadata block configures the mapping of resource attributes to HEC metadata fields. This allows resource attributes like host.name to be mapped to the top-level host field in the HEC JSON payload.

The following arguments are supported:

Name	Type	Description	Default	Required
`host`	`string`	Specifies the mapping of a specific unified model attribute value to the standard host field of a HEC event.	`"host.name"`	no
`index`	`string`	Specifies the mapping of a specific unified model attribute value to the standard index field of a HEC event.	`"com.splunk.index"`	no
`source`	`string`	Specifies the mapping of a specific unified model attribute value to the standard source field of a HEC event.	`"com.splunk.source"`	no
`sourcetype`	`string`	Specifies the mapping of a specific unified model attribute value to the standard sourcetype field of a HEC event.	`"com.splunk.sourcetype"`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`sending_queue`

The sending_queue block configures an in-memory buffer of batches before data is sent to the HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

`retry_on_failure`

The retry_on_failure block configures how failed requests to Splunk HEC are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

otelcol.exporter.splunkhec is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.splunkhec doesn’t expose any component-specific debug information.

Example

OpenTelemetry Receiver

This example forwards metrics, logs, and traces send to the otelcol.receiver.otlp.default receiver to the Splunk HEC exporter.

otelcol.receiver.otlp "default" {
    grpc {
        endpoint = "localhost:4317"
    }

    http {
        endpoint               = "localhost:4318"
        compression_algorithms = ["zlib"]
    }

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

otelcol.exporter.splunkhec "default" {
    client {
        endpoint                = "https://splunkhec.domain.com:8088/services/collector"
        timeout                 = "10s"
        max_idle_conns          = 200
        max_idle_conns_per_host = 200
        idle_conn_timeout       = "10s"
    }

    splunk {
        token              = "SPLUNK_TOKEN"
        source             = "otel"
        sourcetype         = "otel"
        index              = "metrics"
        splunk_app_name    = "OpenTelemetry-Collector Splunk Exporter"
        splunk_app_version = "v0.0.1"

        otel_to_hec_fields {
            severity_text   = "otel.log.severity.text"
            severity_number = "otel.log.severity.number"
        }

        heartbeat {
            interval = "30s"
        }

        telemetry {
            enabled                = true
            override_metrics_names = {
                otelcol_exporter_splunkhec_heartbeats_failed = "app_heartbeats_failed_total",
                otelcol_exporter_splunkhec_heartbeats_sent   = "app_heartbeats_success_total",
            }
            extra_attributes = {
                custom_key   = "custom_value",
                dataset_name = "SplunkCloudBeaverStack",
            }
        }
    }
}

Forward Prometheus Metrics

This example forwards Prometheus metrics from Alloy through a receiver for conversion to OpenTelemetry format before finally sending them to Splunk HEC.

prometheus.exporter.self "default" {
}

prometheus.scrape "metamonitoring" {
  targets    = prometheus.exporter.self.default.targets
  forward_to = [otelcol.receiver.prometheus.default.receiver]
}

otelcol.receiver.prometheus "default" {
  output {
    metrics = [otelcol.exporter.splunkhec.default.input]
  }
}


otelcol.exporter.splunkhec "default" {
    splunk {
        token = "SPLUNK_TOKEN"
    }
    client {
        endpoint = "http://splunkhec.domain.com:8088"
    }
}

Forward Loki logs

This example watches for files ending with .log in the path /var/log, tails these logs with Loki and forwards the logs to the configured Splunk HEC endpoint. The Splunk HEC exporter component is setup to send an heartbeat every 5 seconds.

local.file_match "local_files" {
    path_targets = [{"__path__" = "/var/log/*.log"}]
    sync_period  = "5s"
}

otelcol.receiver.loki "default" {
    output {
        logs = [otelcol.processor.resourcedetection.default.input]
    }
}

otelcol.processor.resourcedetection "default" {
    detectors = ["system"]

    system {
        hostname_sources = ["os", "dns"]
        resource_attributes {
            host.name {
                enabled = true
            }
        }
    }

    output {
        logs = [otelcol.exporter.splunkhec.default.input]
    }
}

loki.source.file "log_scrape" {
    targets       = local.file_match.local_files.targets
    forward_to    = [otelcol.receiver.loki.default.receiver]
    tail_from_end = false
}

otelcol.exporter.splunkhec "default" {
    retry_on_failure {
        enabled = false
    }

    client {
        endpoint                = "http://splunkhec.domain.com:8088"
        timeout                 = "5s"
        max_idle_conns          = 200
        max_idle_conns_per_host = 200
        idle_conn_timeout       = "10s"
        write_buffer_size       = 8000
    }

    sending_queue {
        enabled = false
    }

    // Configure mapping of resource attributes to HEC metadata fields
    otel_attrs_to_hec_metadata {
        host       = "host.name"           // Maps host.name resource attribute to top-level host field
        source     = "com.splunk.source"   // Maps com.splunk.source attribute to source field
        sourcetype = "com.splunk.sourcetype" // Maps com.splunk.sourcetype attribute to sourcetype field
        index      = "com.splunk.index"    // Maps com.splunk.index attribute to index field
    }

    splunk {
        token            = "SPLUNK_TOKEN"
        source           = "otel"
        sourcetype       = "otel"
        index            = "devnull"
        log_data_enabled = true

        heartbeat {
            interval = "5s"
        }

        batcher {
            flush_timeout = "200ms"
        }

        telemetry {
            enabled                = true
            override_metrics_names = {
                otelcol_exporter_splunkhec_heartbeats_failed = "app_heartbeats_failed_total",
                otelcol_exporter_splunkhec_heartbeats_sent   = "app_heartbeats_success_total",
            }
            extra_attributes = {
                host   = "myhost",
                dataset_name = "SplunkCloudBeaverStack",
            }
        }
    }
}

Compatible components

otelcol.exporter.splunkhec has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.exporter.syslog

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.exporter.syslog`

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. To enable and use a public preview component, you must set the stability.level flag to public-preview or below.

otelcol.exporter.syslog accepts logs from other otelcol components and writes them over the network using the syslog protocol. It supports syslog protocols RFC5424 and RFC3164 and can send data over TCP or UDP.

Note
otelcol.exporter.syslog is a wrapper over the upstream OpenTelemetry Collector syslog exporter. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.exporter.syslog components by giving them different labels.

Usage

otelcol.exporter.syslog "LABEL" {
  endpoint = "HOST"
}

Supported Attributes

The exporter creates one syslog message for each log record based on the following attributes of the log record. If an attribute is missing, the default value is used. The log’s timestamp field is used for the syslog message’s time. RFC3164 only supports a subset of the attributes supported by RFC5424, and the default values aren’t the same between the two protocols. Refer to the OpenTelemetry documentation for the exporter for more details.

Attribute name	Type	RFC5424 Default value	RFC3164 supported	RFC3164 Default value
`appname`	string	`-`	yes	empty string
`hostname`	string	`-`	yes	`-`
`message`	string	empty string	yes	empty string
`msg_id`	string	`-`	no
`priority`	int	`165`	yes	`165`
`proc_id`	string	`-`	no
`structured_data`	map	`-`	no
`version`	int	`1`	no

Arguments

You can use the following arguments with otelcol.exporter.syslog:

Name	Type	Description	Default	Required
`endpoint`	`string`	The endpoint to send syslog formatted logs to.		yes
`network`	`string`	The type of network connection to use to send logs.	`"tcp"`	no
`port`	`int`	The port where the syslog server accepts connections.	`514`	no
`protocol`	`string`	The syslog protocol that the syslog server supports.	`"rfc5424"`	no
`enable_octet_counting`	`bool`	Whether to enable rfc6587 octet counting.	`false`	no
`timeout`	`duration`	Time to wait before marking a request as failed.	`"5s"`	no

The network argument specifies if the syslog endpoint is using the TCP or UDP protocol. network must be one of tcp, udp.

The protocol argument specifies the syslog format supported by the endpoint. protocol must be one of rfc5424, rfc3164.

Blocks

You can use the following blocks with otelcol.exporter.syslog:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`retry_on_failure`

The retry_on_failure block configures how failed requests to the syslog server are retried.

The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`boolean`	Enables retrying failed requests.	`true`	no
`initial_interval`	`duration`	Initial time to wait before retrying a failed request.	`"5s"`	no
`max_elapsed_time`	`duration`	Maximum time to wait before discarding a failed batch.	`"5m"`	no
`max_interval`	`duration`	Maximum time to wait between retries.	`"30s"`	no
`multiplier`	`number`	Factor to grow wait time before retrying.	`1.5`	no
`randomization_factor`	`number`	Factor to randomize wait time before retrying.	`0.5`	no

`sending_queue`

The sending_queue block configures queueing and batching for the exporter.

The following arguments are supported:

Name	Type	Description	Default	Required
`block_on_overflow`	`boolean`	The behavior when the component’s `TotalSize` limit is reached.	`false`	no
`enabled`	`boolean`	Enables a buffer before sending data to the client.	`true`	no
`num_consumers`	`number`	Number of readers to send batches written to the queue in parallel.	`10`	no
`queue_size`	`number`	Maximum number of unwritten batches allowed in the queue at the same time.	`1000`	no
`sizer`	`string`	How the queue and batching is measured.	`"requests"`	no
`wait_for_result`	`boolean`	Determines if incoming requests are blocked until the request is processed or not.	`false`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use to enable a persistent queue mechanism.		no

The blocking argument is deprecated in favor of the block_on_overflow argument.

When block_on_overflow is true, the component will wait for space. Otherwise, operations will immediately return a retryable error.

The sizer argument could be set to:

requests: number of incoming batches of metrics, logs, traces (the most performant option).
items: number of the smallest parts of each signal (spans, metric data points, log records).
bytes: the size of serialized data in bytes (the least performant option).

`batch`

The batch block configures batching requests based on a timeout and a minimum number of items.

The following arguments are supported:

Name	Type	Description	Default	Required
`flush_timeout`	`duration`	Time after which a batch will be sent regardless of its size. Must be a non-zero value.	`"200ms"`	no
`min_size`	`number`	The minimum size of a batch.	`2000`	no
`max_size`	`number`	The maximum size of a batch, enables batch splitting.	`3000`	no
`sizer`	`string`	How the queue and batching is measured. Overrides the sizer set at the `sending_queue` level for batching.	`"items"`	no

If configured, max_size must be greater than or equal to min_size.

The sizer argument can be set to:

items: The number of the smallest parts of each span, metric data point, or log record.
bytes: the size of serialized data in bytes (the least performant option).

`tls`

The tls block configures TLS settings used for a connection to a TCP syslog server.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for logs. Other telemetry signals are ignored.

Component health

otelcol.exporter.syslog is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.exporter.syslog doesn’t expose any component-specific debug information.

Examples

TCP endpoint without TLS

This example creates an exporter to send data to a syslog server expecting RFC5424-compliant messages over TCP without TLS:

otelcol.exporter.syslog "default" {
  endpoint = "localhost"
  tls {
      insecure             = true
      insecure_skip_verify = true
  }
}

Use the `otelcol.processor.transform` component to format logs from `loki.source.syslog`

This example shows one of the methods for annotating your Loki messages into the format expected by the exporter using a otelcol.receiver.loki component in addition to the otelcol.processor.transform component. This example assumes that the log messages being parsed have come from a loki.source.syslog component. This is just an example of some of the techniques that can be applied, and not a fully functioning example for a specific incoming log.

otelcol.receiver.loki "default" {
  output {
    logs = [otelcol.processor.transform.syslog.input]
  }
}

otelcol.processor.transform "syslog" {
  error_mode = "ignore"

  log_statements {
    context = "log"

    statements = [
      `set(attributes["message"], attributes["__syslog_message"])`,
      `set(attributes["appname"], attributes["__syslog_appname"])`,
      `set(attributes["hostname"], attributes["__syslog_hostname"])`,

      // To set structured data you can chain index ([]) operations.
      `set(attributes["structured_data"]["auth@32473"]["user"], attributes["__syslog_message_sd_auth_32473_user"])`,
      `set(attributes["structured_data"]["auth@32473"]["user_host"], attributes["__syslog_message_sd_auth_32473_user_host"])`,
      `set(attributes["structured_data"]["auth@32473"]["valid"], attributes["__syslog_message_sd_auth_32473_authenticated"])`,
    ]
  }

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

Use the `otelcol.processor.transform` component to format OpenTelemetry logs

This example shows one of the methods for annotating your messages in the OpenTelemetry log format into the format expected by the exporter using an otelcol.processor.transform component. This example assumes that the log messages being parsed have come from another OpenTelemetry receiver in JSON format (or have been transformed to OpenTelemetry logs using an otelcol.receiver.loki component). This is just an example of some of the techniques that can be applied, and not a fully functioning example for a specific incoming log format.

otelcol.processor.transform "syslog" {
  error_mode = "ignore"

  log_statements {
    context = "log"

    statements = [
      // Parse body as JSON and merge the resulting map with the cache map, ignoring non-json bodies.
      // cache is a field exposed by OTTL that is a temporary storage place for complex operations.
      `merge_maps(cache, ParseJSON(body), "upsert") where IsMatch(body, "^\\{")`,

      // Set some example syslog attributes using the values from a JSON message body
      // If the attribute doesn't exist in cache then nothing happens.
      `set(attributes["message"], cache["log"])`,
      `set(attributes["appname"], cache["application"])`,
      `set(attributes["hostname"], cache["source"])`,

      // To set structured data you can chain index ([]) operations.
      `set(attributes["structured_data"]["auth@32473"]["user"], attributes["user"])`,
      `set(attributes["structured_data"]["auth@32473"]["user_host"], cache["source"])`,
      `set(attributes["structured_data"]["auth@32473"]["valid"], cache["authenticated"])`,

      // Example priority setting, using facility 1 (user messages) and default to Info
      `set(attributes["priority"], 14)`,
      `set(attributes["priority"], 12) where severity_number == SEVERITY_NUMBER_WARN`,
      `set(attributes["priority"], 11) where severity_number == SEVERITY_NUMBER_ERROR`,
      `set(attributes["priority"], 10) where severity_number == SEVERITY_NUMBER_FATAL`,
    ]
  }

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

Compatible components

otelcol.exporter.syslog has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.extension.jaeger_remote_sampling

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.extension.jaeger_remote_sampling`

otelcol.extension.jaeger_remote_sampling serves a specified Jaeger remote sampling document.

Note
otelcol.extension.jaeger_remote_sampling is a wrapper over the upstream OpenTelemetry Collector jaegerremotesampling extension. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.extension.jaeger_remote_sampling components by giving them different labels.

Usage

otelcol.extension.jaeger_remote_sampling "<LABEL>" {
  source {
  }
}

Arguments

The otelcol.extension.jaeger_remote_sampling component doesn’t support any arguments. You can configure this component with blocks.

Blocks

You can use the following blocks with otelcol.extension.jaeger_remote_sampling:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`source`

Required

The source block configures the method of retrieving the Jaeger remote sampling document that’s served by the servers specified in the grpc and http blocks.

The following arguments are supported:

Name	Type	Description	Default	Required
`content`	`string`	A string containing the Jaeger remote sampling contents directly.	`""`	no
`file`	`string`	A local file containing a Jaeger remote sampling document.	`""`	no
`reload_interval`	`duration`	The interval at which to reload the specified file. Leave at 0 to never reload.	`"0"`	no

Exactly one of the file argument, content argument or remote block must be specified.

`remote`

The remote block configures the gRPC client used by the component.

The following arguments are supported:

Name	Type	Description	Default	Required
`endpoint`	`string`	`host:port` to send telemetry data to.		yes
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`authority`	`string`	Overrides the default `:authority` header in gRPC requests from the gRPC client.		no
`compression`	`string`	Compression mechanism to use for requests.	`"gzip"`	no
`headers`	`map(string)`	Additional headers to send with the request.	`{}`	no
`read_buffer_size`	`string`	Size of the read buffer the gRPC client to use for reading server responses.		no
`wait_for_ready`	`bool`	Waits for gRPC connection to be in the `READY` state before sending data.	`false`	no
`write_buffer_size`	`string`	Size of the write buffer the gRPC client to use for writing requests.	`"512KiB"`	no

By default, requests are compressed with Gzip. The compression argument controls which compression mechanism to use. Supported strings are:

"gzip"
"zlib"
"deflate"
"snappy"
"zstd"

If you set compression to "none" or an empty string "", the requests aren’t compressed.

The supported values for balancer_name are listed in the gRPC documentation on Load balancing:

pick_first: Tries to connect to the first address. It uses the address for all RPCs if it connects, or if it fails, it tries the next address and keeps trying until one connection is successful. Because of this, all the RPCs are sent to the same backend.
round_robin: Connects to all the addresses it sees and sends an RPC to each backend one at a time in order. For example, the first RPC is sent to backend-1, the second RPC is sent to backend-2, and the third RPC is sent to backend-1.

An HTTP proxy can be configured through the following environment variables:

HTTPS_PROXY
NO_PROXY

The HTTPS_PROXY environment variable specifies a URL to use for proxying requests. Connections to the proxy are established via the HTTP CONNECT method.

Because otelcol.extension.jaeger_remote_sampling uses gRPC, the configured proxy server must be able to handle and proxy HTTP/2 traffic.

`keepalive` client

This keepalive block configures keepalive settings for gRPC client connections.

The following arguments are supported:

Name	Type	Description	Required
`ping_wait`	`duration`	How often to ping the server after no activity.	no
`ping_response_timeout`	`duration`	Time to wait before closing inactive connections if the server doesn’t respond to a ping.	no
`ping_without_stream`	`boolean`	Send pings even if there is no active stream request.	no

`tls` client

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

`http`

The http block configures an HTTP server which serves the Jaeger remote sampling document.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`compression_algorithms`	`list(string)`	A list of compression algorithms the server can accept.	`["", "gzip", "zstd", "zlib", "snappy", "deflate", "lz4"]`	no
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:5778"`	no
`include_metadata`	`boolean`	Propagate incoming connection metadata to downstream consumers.		no
`keep_alives_enabled`	`boolean`	Whether or not HTTP keep-alives are enabled	`true`	no
`max_request_body_size`	`string`	Maximum request body size the server will allow.	`"20MiB"`	no

`cors`

The cors block configures CORS settings for an HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`allowed_headers`	`list(string)`	Accepted headers from CORS requests.	`["X-Requested-With"]`	no
`allowed_origins`	`list(string)`	Allowed values for the `Origin` header.		no
`max_age`	`number`	Configures the `Access-Control-Max-Age` response header.		no

The allowed_headers specifies which headers are acceptable from a CORS request. The following headers are always implicitly allowed:

Accept
Accept-Language
Content-Type
Content-Language

If allowed_headers includes "*", all headers will be permitted.

`tls`

The tls block configures TLS settings used for a server. If the tls block isn’t provided, TLS won’t be used for connections to the server.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`client_ca_file`	`string`	Path to the TLS cert to use by the server to verify a client certificate.		no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no

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. Refer to the Go Cipher Suites documentation for a list of supported cipher suites.

client_ca_file sets the ClientCA and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Refer to the Go TLS documentation for more information.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

`grpc`

The grpc block configures a gRPC server which serves the Jaeger remote sampling document.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`endpoint`	`string`	`host:port` to listen for traffic on.	`"0.0.0.0:14250"`	no
`include_metadata`	`boolean`	Propagate incoming connection metadata to downstream consumers.		no
`max_concurrent_streams`	`number`	Limit the number of concurrent streaming RPC calls.		no
`max_recv_msg_size`	`string`	Maximum size of messages the server will accept.	`"4MiB"`	no
`read_buffer_size`	`string`	Size of the read buffer the gRPC server will use for reading from clients.	`"512KiB"`	no
`transport`	`string`	Transport to use for the gRPC server.	`"tcp"`	no
`write_buffer_size`	`string`	Size of the write buffer the gRPC server will use for writing to clients.		no

`keepalive`

The keepalive block configures keepalive settings for connections to a gRPC server.

keepalive doesn’t support any arguments and is configured fully through inner blocks.

`enforcement_policy`

The enforcement_policy block configures the keepalive enforcement policy for gRPC servers. The server will close connections from clients that violate the configured policy.

The following arguments are supported:

Name	Type	Description	Default	Required
`min_time`	`duration`	Minimum time clients should wait before sending a keepalive ping.	`"5m"`	no
`permit_without_stream`	`boolean`	Allow clients to send keepalive pings when there are no active streams.	`false`	no

`server_parameters`

The server_parameters block controls keepalive and maximum age settings for gRPC servers.

The following arguments are supported:

Name	Type	Description	Default	Required
`max_connection_age_grace`	`duration`	Time to wait before forcibly closing connections.	`"infinity"`	no
`max_connection_age`	`duration`	Maximum age for non-idle connections.	`"infinity"`	no
`max_connection_idle`	`duration`	Maximum age for idle connections.	`"infinity"`	no
`time`	`duration`	How often to ping inactive clients to check for liveness.	`"2h"`	no
`timeout`	`duration`	Time to wait before closing inactive clients that don’t respond to liveness checks.	`"20s"`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Component health

otelcol.extension.jaeger_remote_sampling is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.extension.jaeger_remote_sampling doesn’t expose any component-specific debug information.

Examples

Serve from a file

This example configures the Jaeger remote sampling extension to load a local JSON document and serve it over the default HTTP port of 5778. Currently this configuration style exists for consistency with upstream OpenTelemetry Collector components and may be removed.

otelcol.extension.jaeger_remote_sampling "example" {
  http {
  }
  source {
    file             = "/path/to/jaeger-sampling.json"
    reload_interval  = "10s"
  }
}

Serve from another component

This example uses the output of a component to determine what sampling rules to serve:

local.file "sampling" {
  filename  = "/path/to/jaeger-sampling.json"
}

otelcol.extension.jaeger_remote_sampling "example" {
  http {
  }
  source {
    content = local.file.sampling.content
  }
}

Enable authentication

You can use jaeger_remote_sampling to authenticate requests. This allows you to limit access to the sampling document.

Note
Not all OpenTelemetry Collector authentication plugins support receiver authentication. Refer to the documentation for each otelcol.auth.* component to determine its compatibility.

otelcol.extension.jaeger_remote_sampling "default" {
  http {
    auth = otelcol.auth.basic.creds.handler
  }
  grpc {
     auth = otelcol.auth.basic.creds.handler
  }
}

otelcol.auth.basic "creds" {
    username = sys.env("USERNAME")
    password = sys.env("PASSWORD")
}

otelcol.processor.attributes

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.attributes`

otelcol.processor.attributes accepts telemetry data from other otelcol components and modifies attributes of a span, log, or metric. It also supports the ability to filter and match input data to determine if it should be included or excluded for attribute modifications.

Note
otelcol.processor.attributes is a wrapper over the upstream OpenTelemetry Collector attributes processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.attributes "<LABEL>" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

The otelcol.processor.attributes component doesn’t support any arguments. You can configure this component with blocks.

Blocks

You can use the following blocks with otelcol.processor.attributes:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

If both an include block and an excludeblock are specified, the include properties are checked before the exclude properties.

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`action`

The action block configures how to modify the span, log, or metric.

The following attributes are supported:

Name	Type	Description	Default	Required
`key`	`string`	The attribute that the action relates to.		yes
`action`	`string`	The type of action performed.		yes
`value`	`any`	The value to populate for the key.		no
`pattern`	`string`	A regular expression pattern.	`""`	no
`from_attribute`	`string`	The attribute from the input data used to populate the attribute value.	`""`	no
`from_context`	`string`	The context value used to populate the attribute value.	`""`	no
`converted_type`	`string`	The type to convert the attribute value to.	`""`	no

The value data type must be either a number, string, or boolean.

The supported values for action are:

insert: Inserts an attribute in input data where the key doesn’t already exist.
- The key attribute is required. It specifies the attribute to act upon.
- One of the value, from_attribute or from_context attributes is required.
update: Updates an attribute in input data where the key does exist.
- The keyattribute is required. It specifies the attribute to act upon.
- One of the value, from_attribute or from_context attributes is required.
upsert: Either inserts an attribute in input data where the key doesn’t already exist or updates an attribute in input data where the key does exist.
- The keyattribute is required. It specifies the attribute to act upon.
- One of the value, from_attribute or from_contextattributes is required:
  - value specifies the value to populate for the key.
  - from_attribute specifies the attribute from the input data to use to populate the value. If the attribute doesn’t exist, no action is performed.
  - from_context specifies the context value used to populate the attribute value. If the key is prefixed with metadata., the values are searched in the receiver’s transport protocol for additional information like gRPC Metadata or HTTP Headers. If the key is prefixed with auth., the values are searched in the authentication information set by the server authenticator. Refer to the server authenticator documentation part of your pipeline for more information about which attributes are available. If the key is client.address, the value will be set to the client address. If the key doesn’t exist, no action is performed. If the key has multiple values the values will be joined with a ; separator.
hash: Hashes (SHA1) an attribute value.
- The key attribute or the pattern attributes is required.
extract: Extracts values using a regular expression rule from the input key to target keys specified in the rule. If a target key already exists, it will be overridden. Note: It behaves similarly to the Span Processor to_attributes setting with the attribute as the source.
- The key attribute is required. It specifies the attribute to extract values from. The value of key isn’t altered.
- The pattern attribute is required. It’s the regular expression pattern used to extract attributes from the value of key. The submatchers must be named. If attributes already exist, they will be overwritten.
convert: Converts an attribute to a specified type.
- The key attribute is required. It specifies the attribute to act upon.
- The converted_type attribute is required and must be one of int, double or string.
delete: Deletes an attribute from the input data.
- The key attribute or the pattern attribute is required. It specifies the attribute to act upon.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`exclude`

The exclude block provides an option to exclude data from being fed into the [action] blocks based on the properties of a span, log, or metric records.

Note
Signals excluded by the exclude block will still be propagated to downstream components as-is. If you would like to not propagate certain signals to downstream components, consider a processor such as otelcol.processor.tail_sampling.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_type`	`string`	Controls how items to match against are interpreted.		yes
`log_bodies`	`list(string)`	A list of strings that the LogRecord’s body field must match against.	`[]`	no
`log_severity_texts`	`list(string)`	A list of strings that the LogRecord’s severity text field must match against.	`[]`	no
`metric_names`	`list(string)`	A list of strings to match the metric name against.	`[]`	no
`services`	`list(string)`	A list of items to match the service name against.	`[]`	no
`span_kinds`	`list(string)`	A list of items to match the span kind against.	`[]`	no
`span_names`	`list(string)`	A list of items to match the span name against.	`[]`	no

match_type is required and you must set it to either "regexp" or "strict".

A match occurs if at least one item in the lists matches.

One of the following is also required:

For spans, one of services, span_names, span_kinds, [attribute][], [resource][], or [library][] must be specified with a non-empty value for a valid configuration. The log_bodies, log_severity_texts, log_severity, and metric_names attributes are invalid.
For logs, one of log_bodies, log_severity_texts, log_severity, [attribute][], [resource][], or [library][] must be specified with a non-empty value for a valid configuration. The span_names, span_kinds, metric_names, and services attributes are invalid.
For metrics, metric_names must be specified with a valid non-empty value for a valid configuration. The span_names, span_kinds, log_bodies, log_severity_texts, log_severity, services, [attribute][], [resource][], and [library][] attributes are invalid.

If the configuration includes filters which are specific to a particular signal type, it’s best to include only that signal type in the component’s output. For example, adding a span_names filter could cause the component to error if logs are configured in the component’s outputs.

`attribute`

This block specifies an attribute to match against:

You can define more than one attribute block.
Only match_type = "strict" is allowed if attribute is specified.
All attribute blocks must match exactly for a match to occur.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	The attribute key.		yes
`value`	`any`	The attribute value to match against.		no

If value isn’t set, any value matches. The type of value could be a number, a string, or a boolean.

`library`

This block specifies properties to match the implementation library against:

More than one library block can be defined.
A match occurs if the span’s implementation library matches at least one library block.

The following arguments are supported:

Name	Type	Description	Default	Required
`name`	`string`	The attribute key.		yes
`version`	`string`	The version to match against.	null	no

If version is unset, any version matches. If you set version to an empty string, it only matches a library version, which is also an empty string.

`log_severity`

This block defines how to match based on a log record’s SeverityNumber field.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_undefined`	`bool`	Whether logs with “undefined” severity match.		yes
`min`	`string`	The lowest severity that may be matched.		yes

If match_undefined is true, entries with undefined severity will match.

The following table lists the severities supported by OTel. The value for min should be one of the values in the “Log Severity” column.

Log Severity	Severity number
TRACE	1
TRACE2	2
TRACE3	3
TRACE4	4
DEBUG	5
DEBUG2	6
DEBUG3	7
DEBUG4	8
INFO	9
INFO2	10
INFO3	11
INFO4	12
WARN	13
WARN2	14
WARN3	15
WARN4	16
ERROR	17
ERROR2	18
ERROR3	19
ERROR4	20
FATAL	21
FATAL2	22
FATAL3	23
FATAL4	24

For example, if the min attribute in the log_severity block is “INFO”, then INFO, WARN, ERROR, and FATAL logs will match.

`regexp`

This block is an optional configuration for the match_type of "regexp". It configures a Least Recently Used (LRU) cache.

The following arguments are supported:

Name	Type	Description	Default	Required
`cache_enabled`	`bool`	Determines whether match results are LRU cached.	`false`	no
`cache_max_num_entries`	`int`	The max number of entries of the LRU cache that stores match results.	`0`	no

Enabling cache_enabled could make subsequent matches faster. Cache size is unlimited unless cache_max_num_entries is also specified.

cache_max_num_entries is ignored if cache_enabled is false.

`resource`

This block specifies items to match the resources against:

More than one resource block can be defined.
A match occurs if the input data resources match at least one resource block.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	The resource key.		yes
`value`	`any`	The resource value to match against.		no

If value isn’t set, any value matches. The type of value could be a number, a string, or a boolean.

`include`

The include block provides an option to include data being fed into the [action] blocks based on the properties of a span, log, or metric records.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_type`	`string`	Controls how items to match against are interpreted.		yes
`log_bodies`	`list(string)`	A list of strings that the LogRecord’s body field must match against.	`[]`	no
`log_severity_texts`	`list(string)`	A list of strings that the LogRecord’s severity text field must match against.	`[]`	no
`metric_names`	`list(string)`	A list of strings to match the metric name against.	`[]`	no
`services`	`list(string)`	A list of items to match the service name against.	`[]`	no
`span_kinds`	`list(string)`	A list of items to match the span kind against.	`[]`	no
`span_names`	`list(string)`	A list of items to match the span name against.	`[]`	no

match_type is required and you must set it to either "regexp" or "strict".

A match occurs if at least one item in the lists matches.

One of the following is also required:

For spans, one of services, span_names, span_kinds, [attribute][], [resource][], or [library][] must be specified with a non-empty value for a valid configuration. The log_bodies, log_severity_texts, log_severity, and metric_names attributes are invalid.
For logs, one of log_bodies, log_severity_texts, log_severity, [attribute][], [resource][], or [library][] must be specified with a non-empty value for a valid configuration. The span_names, span_kinds, metric_names, and services attributes are invalid.
For metrics, one of metric_names or resources must be specified with a valid non-empty value for a valid configuration. The span_names, span_kinds, log_bodies, log_severity_texts, log_severity, services, [attribute][], [resource][], and [library][] attributes are invalid.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

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

Examples

Various uses of the `action` block

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.attributes.default.input]
    logs    = [otelcol.processor.attributes.default.input]
    traces  = [otelcol.processor.attributes.default.input]
  }
}

otelcol.processor.attributes "default" {
    // Inserts a new attribute "attribute1" to spans where
    // the key "attribute1" doesn't exist.
    // The type of `attribute1` is inferred by the configuration.
    // `123` is an integer and is stored as an integer in the attributes.
    action {
        key = "attribute1"
        value = 123
        action = "insert"
    }

    // Inserts a new attribute with a key of "string key" and
    // a string value of "anotherkey".
    action {
        key = "string key"
        value = "anotherkey"
        action = "insert"
    }

    // Setting an attribute on all spans.
    // Any spans that already had `region` now have value `planet-earth`.
    // This can be done to set properties for all traces without
    // requiring an instrumentation change.
    action {
        key = "region"
        value = "planet-earth"
        action = "upsert"
    }

    // The following demonstrates copying a value to a new key.
    // If a span doesn't contain `user_key`, no new attribute `new_user_key` is created.
    action {
        key = "new_user_key"
        from_attribute = "user_key"
        action = "upsert"
    }

    // Hashing existing attribute values.
    action {
        key = "user.email"
        action = "hash"
    }

    // Uses the value from key `example_user_key` to upsert attributes
    // to the target keys specified in the `pattern`.
    // (Insert attributes for target keys that do not exist and update keys that exist.)
    // Given example_user_key = /api/v1/document/12345678/update/v1
    // then the following attributes will be inserted:
    // new_example_user_key: 12345678
    // version: v1
    //
    // Note: Similar to the Span Processor, if a target key already exists,
    // it will be updated.
    //
    // Note: The regex pattern is enclosed in backticks instead of quotation marks.
    // This constitutes a raw Alloy syntax string, and lets us avoid the need to escape backslash characters.
    action {
        key = "example_user_key"
        pattern = `\/api\/v1\/document\/(?P<new_user_key>.*)\/update\/(?P<version>.*)$`
        action = "extract"
    }

    // Converting the type of an existing attribute value.
    action {
        key = "http.status_code"
        converted_type = "int"
        action = "convert"
    }

    // Deleting keys from an attribute.
    action {
        key = "credit_card"
        action = "delete"
    }

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

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("OTLP_ENDPOINT")
  }
}

Exclude spans based on attributes

For example, the following spans match the properties and won’t be processed by the processor:

Span1 Name: "svcB", Attributes: {env: "dev", test_request: 123, credit_card: 1234}
Span2 Name: "svcA", Attributes: {env: "dev", test_request: false}

The following spans don’t match the properties and the processor actions are applied to it:

Span3 Name: "svcB", Attributes: {env: 1, test_request: "dev", credit_card: 1234}
Span4 Name: "svcC", Attributes: {env: "dev", test_request: false}

Due to the presence of the services attribute, this configuration works only for trace signals. This is why only traces are configured in the output block.

otelcol.processor.attributes "default" {
    exclude {
        match_type = "strict"
        services = ["svcA", "svcB"]
        attribute {
            key = "env"
            value = "dev"
        }
        attribute {
            key = "test_request"
        }
    }
    action {
        key = "credit_card"
        action = "delete"
    }
    action {
        key = "duplicate_key"
        action = "delete"
    }
    output {
        traces  = [otelcol.exporter.otlphttp.default.input]
    }
}

Exclude spans based on resources

A “strict” match_type means that you must strictly match the resource key/value pairs.

The resource attribute isn’t used for metrics, which is why metrics aren’t configured in the component output.

otelcol.processor.attributes "default" {
    exclude {
        match_type = "strict"
        resource {
            key = "host.type"
            value = "n1-standard-1"
        }
    }
    action {
        key = "credit_card"
        action = "delete"
    }
    action {
        key = "duplicate_key"
        action = "delete"
    }
    output {
        logs    = [otelcol.exporter.otlphttp.default.input]
        traces  = [otelcol.exporter.otlphttp.default.input]
    }
}

Exclude spans based on a specific library version

A “strict” match_type means that you must strictly match the library key/value pairs.

The library attribute isn’t used for metrics, which is why metrics aren’t configured in the component output.

otelcol.processor.attributes "default" {
    exclude {
        match_type = "strict"
        library {
            name = "mongo-java-driver"
            version = "3.8.0"
        }
    }
    action {
        key = "credit_card"
        action = "delete"
    }
    action {
        key = "duplicate_key"
        action = "delete"
    }
    output {
        logs    = [otelcol.exporter.otlphttp.default.input]
        traces  = [otelcol.exporter.otlphttp.default.input]
    }
}

Include and exclude spans based on regular expressions and services

This processor will remove the “token” attribute and will obfuscate the “password” attribute in spans where the service name matches "auth.*" and where the span name doesn’t match "login.*".

Due to the presence of the services and span_names attributes, this configuration works only for trace signals. This is why only traces are configured in the output block.

otelcol.processor.attributes "default" {
    // Specifies the span properties that must exist for the processor to be applied.
    include {
        // "match_type" defines that "services" is an array of regexp-es.
        match_type = "regexp"
        // The span service name must match "auth.*" pattern.
        services = ["auth.*"]
    }

    exclude {
        // "match_type" defines that "span_names" is an array of regexp-es.
        match_type = "regexp"
        // The span name must not match "login.*" pattern.
        span_names = ["login.*"]
    }

    action {
        key = "password"
        action = "update"
        value = "obfuscated"
    }

    action {
        key = "token"
        action = "delete"
    }

    output {
        traces  = [otelcol.exporter.otlphttp.default.input]
    }
}

Include spans based on regular expressions and attributes

The following demonstrates how to process spans with attributes that match a regular expression pattern. This processor will obfuscate the db.statement attribute in spans where the db.statement attribute matches a regular expression pattern.

otelcol.processor.attributes "default" {
    include {
        // "match_type" of "regexp" defines that the "value" attributes 
        // in the "attribute" blocks are regexp-es.
        match_type = "regexp"

        // This attribute ('db.statement') must exist in the span and match 
        // the regex ('SELECT \* FROM USERS.*') for a match.
        attribute {
            key = "db.statement"
            value = "SELECT \* FROM USERS.*"
        }
    }

    action {
        key = "db.statement"
        action = "update"
        value = "SELECT * FROM USERS [obfuscated]"
    }

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

Include spans based on a regular expression of log body

This processor removes the “token” attribute and obfuscates the “password” attribute in spans where the log body matches "AUTH.*".

Due to the presence of the log_bodies attribute, this configuration works only for log signals. This is why only logs are configured in the output block.

otelcol.processor.attributes "default" {
    include {
        match_type = "regexp"
        log_bodies = ["AUTH.*"]
    }
    action {
        key = "password"
        action = "update"
        value = "obfuscated"
    }
    action {
        key = "token"
        action = "delete"
    }

    output {
        logs    = [otelcol.exporter.otlphttp.default.input]
    }
}

Include spans based on a regular expression of log severity

The following example demonstrates how to process logs that have a severity level which is equal to or higher than the level specified in the log_severity block. This processor removes the “token” attribute and obfuscates the “password” attribute in logs where the severity is at least "INFO".

Due to the presence of the log_severity attribute, this configuration works only for log signals. This is why only logs are configured in the output block.

otelcol.processor.attributes "default" {
    include {
        match_type = "regexp"
        log_severity {
            min = "INFO"
            match_undefined = true
        }
    }
    action {
        key = "password"
        action = "update"
        value = "obfuscated"
    }
    action {
        key = "token"
        action = "delete"
    }

    output {
        logs    = [otelcol.exporter.otlphttp.default.input]
    }
}

Include spans based on a regular expression of log severity text

The following demonstrates how to process logs that have a severity text that match regular expression patterns. This processor removes the “token” attribute and obfuscates the “password” attribute in logs where severity matches “info”.

Due to the presence of the log_severity_texts attribute, this configuration works only for log signals. This is why only logs are configured in the output block.

otelcol.processor.attributes "default" {
    include {
        match_type = "regexp"
        log_severity_texts = ["info.*"]
    }
    action {
        key = "password"
        action = "update"
        value = "obfuscated"
    }
    action {
        key = "token"
        action = "delete"
    }

    output {
        logs    = [otelcol.exporter.otlphttp.default.input]
    }
}

Include metrics based on metric names

The following demonstrates how to process metrics that have a name starting with “counter”. This processor will add a label called "important_label" with a value of "label_val" to the metric. If the label already exists, its value will be updated.

Due to the presence of the metric_names attribute, this configuration works only for metric signals. This is why only metrics are configured in the output block.

otelcol.processor.attributes "default" {
    include {
        match_type = "regexp"
        metric_names = ["counter.*"]
    }
    action {
        key = "important_label"
        action = "upsert"
        value = "label_val"
    }

    output {
        metrics = [otelcol.exporter.otlphttp.default.input]
    }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.batch

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.batch`

otelcol.processor.batch accepts telemetry data from other otelcol components and places them into batches. Batching improves the compression of data and reduces the number of outgoing network requests required to transmit data. This processor supports both size and time based batching.

Grafana Labs strongly recommends that you configure the batch processor on every Alloy that uses OpenTelemetry (otelcol) Alloy components. Define the batch processor in the pipeline after the otelcol.processor.memory_limiter as well as any sampling processors. Batching should happen after any processing that drops data such as sampling.

Note
otelcol.processor.batch is a wrapper over the upstream OpenTelemetry Collector batch processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.batch "<LABEL>" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.batch:

Name	Type	Description	Default	Required
`metadata_cardinality_limit`	`number`	Limit of the unique metadata key/value combinations.	`1000`	no
`metadata_keys`	`list(string)`	Creates a different batch processor for each key/value combination of metadata.	`[]`	no
`send_batch_max_size`	`number`	Upper limit of a batch size.	`3000`	no
`send_batch_size`	`number`	Number of spans, log records, or metric data points that trigger a batch to be sent.	`2000`	no
`timeout`	`duration`	How long to wait before flushing the batch.	`"200ms"`	no

otelcol.processor.batch accumulates data into a batch until one of the following events happens:

The duration specified by timeout elapses since the time the last batch was sent.
The number of spans, log records, or metric data points processed reaches or exceeds the number specified by send_batch_size.

send_batch_size acts as a trigger threshold, not the exact batch size. When data arrives in large chunks, the actual batch size may exceed send_batch_size unless you configure send_batch_max_size to enforce an upper limit.

Logs, traces, and metrics are processed independently. For example, if send_batch_size is set to 1000:

The processor may, at the same time, buffer 1,000 spans, 1,000 log records, and 1,000 metric data points before flushing them.
If there are enough spans for a batch of spans, for example 1,000 or more, but not enough for a batch of metric data points, for example less than 1,000, then only the spans are flushed.

Use send_batch_max_size to limit the amount of data contained in a single batch:

When set to 0, batches can be any size.
When set to a non-zero value, send_batch_max_size must be greater than or equal to send_batch_size. Every batch contains up to the send_batch_max_size number of spans, log records, or metric data points. The excess spans, log records, or metric data points aren’t lost - instead, they’re added to the next batch.

For example, assume you set send_batch_size to 8192 and there are 8,000 batched spans. If the batch processor receives 8,000 more spans at once, its behavior depends on how you configure send_batch_max_size:

If you set send_batch_max_size to 0, the total batch size would be 16,000 spans which are then flushed as a single batch.
If you set send_batch_max_size to 10000, then the batch has a limit of 10,000 spans and the processor adds the remaining 6,000 spans to the next batch.

This demonstrates how send_batch_size acts as a trigger while send_batch_max_size enforces the actual maximum batch size.

metadata_cardinality_limit applies for the lifetime of the process.

Configure receivers with include_metadata = true so that metadata keys are available to the processor.

Each distinct combination of metadata triggers the allocation of a background task in the Alloy process that runs for the lifetime of the process, and each background task holds one pending batch of up to send_batch_size telemetry items such as spans, log records, or metric data points. Batching by metadata can therefore substantially increase the amount of memory dedicated to batching.

The maximum number of distinct combinations is limited to the configured metadata_cardinality_limit, which defaults to 1000 to limit memory impact.

Blocks

You can use the following blocks with otelcol.processor.batch:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal including metrics, logs, or traces.

Component health

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

Debug information

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

Debug metrics

otelcol_processor_batch_batch_send_size_bytes (histogram): Number of bytes in each sent batch.
otelcol_processor_batch_batch_send_size (histogram): Number of units in the batch.
otelcol_processor_batch_batch_size_trigger_send_total (counter): Number of times a batch was sent due to a size trigger.
otelcol_processor_batch_metadata_cardinality (gauge): Number of distinct metadata value combinations processed.
otelcol_processor_batch_timeout_trigger_send_total (counter): Number of times a batch was sent due to a timeout trigger.

Examples

Basic usage

This example batches telemetry data before sending it to otelcol.exporter.otlphttp for further processing:

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
    logs    = [otelcol.exporter.otlphttp.production.input]
    traces  = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Batching with a timeout

This example buffers up to 1000 spans, log records, or metric data points for up to 10 seconds. Because send_batch_max_size is set to 0, the actual batch size may exceed 1000 if large amounts of data arrive simultaneously.

otelcol.processor.batch "default" {
  timeout = "10s"
  send_batch_size = 1000
  send_batch_max_size = 0

  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
    logs    = [otelcol.exporter.otlphttp.production.input]
    traces  = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Metadata-based batching

Batching by metadata enables support for multi-tenant OpenTelemetry pipelines with batching over groups of data having the same authorization metadata.

otelcol.receiver.jaeger "default" {
  protocols {
    grpc {
      include_metadata = true
    }
    thrift_http {}
    thrift_binary {}
    thrift_compact {}
  }

  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  // batch data by tenant id
  metadata_keys = ["tenant_id"]
  // limit to 10 batch processor instances before raising errors
  metadata_cardinality_limit = 123

  output {
    traces  = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.cumulativetodelta

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.cumulativetodelta`

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. To enable and use a public preview component, you must set the stability.level flag to public-preview or below.

otelcol.processor.cumulativetodelta accepts metrics from other otelcol components and converts metrics with the cumulative temporality to delta.

Note
otelcol.processor.cumulativetodelta is a wrapper over the upstream OpenTelemetry Collector cumulativetodelta processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.cumulativetodelta "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.cumulativetodelta:

Name	Type	Description	Default	Required
`initial_value`	`string`	Handling of the first observed point for a given metric identity.	`"auto"`	no
`max_staleness`	`duration`	The total time a state entry will live past the time it was last seen.	`"0"`	no

otelcol.processor.cumulativetodelta tracks incoming metric streams. Sum and exponential histogram metrics with delta temporality are tracked and converted into cumulative temporality.

If a new sample hasn’t been received since the duration specified by max_staleness, tracked streams are considered stale and dropped. When set to "0", the state is retained indefinitely.

The initial_value sets the handling of the first observed point for a given metric identity. When the collector (re)starts, there’s no record of how much of a given cumulative counter has already been converted to delta values.

"auto" (default): Send the observed value if the start time is set AND the start time happens after the component started AND the start time is different from the timestamp. This is suitable for gateway deployments. This heuristic is like drop, but it keeps values for newly started counters which couldn’t have had previous observed values.
"keep": Send the observed value as the delta value. This is suitable for when the incoming metrics haven’t been observed before. For example, when you are running the collector as a sidecar, the collector lifecycle is tied to the metric source.
"drop": Keep the observed value but don’t send it. This is suitable for gateway deployments. It guarantees that all delta counts it produces haven’t been observed before, but drops the values between the first two observations.

Blocks

You can use the following blocks with otelcol.processor.cumulativetodelta:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

If metric matches both include and exclude, exclude takes preference. If neither include nor exclude are supplied, no filtering is applied.

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`include`

The include block configures which metrics to convert to delta.

The following attributes are supported:

Name	Type	Description	Required
`match_type`	`string`	Match type to use, `strict` or `regexp`.	no
`metric_types`	`list(string)`	Metric types to convert to delta.	no
`metrics`	`list(string)`	Names or patterns to convert to delta.	no

If one of metrics or match_type is supplied, the other must be supplied too.

Valid values for metric_types are sum and histogram.

`exclude`

The exclude block configures which metrics not to convert to delta. exclude takes precedence over include

The following attributes are supported:

Name	Type	Description	Required
`match_type`	`string`	Match type to use, `strict` or `regexp`.	no
`metric_types`	`list(string)`	Metric types to exclude when converting to delta.	no
`metrics`	`list(string)`	Names or patterns to exclude when converting to delta.	no

If one of metrics or match_type is supplied, the other must be supplied too.

Valid values for metric_types are sum and histogram.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for metrics.

Component health

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

Debug information

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

Example

This example converts cumulative temporality metrics to delta before sending it to otelcol.exporter.otlphttp for further processing.

otelcol.processor.cumulativetodelta "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.deltatocumulative

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.deltatocumulative`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.processor.deltatocumulative accepts metrics from other otelcol components and converts metrics with the delta temporality to cumulative.

Note
otelcol.processor.deltatocumulative is a wrapper over the upstream OpenTelemetry Collector deltatocumulative processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.deltatocumulative "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.deltatocumulative:

Name	Type	Description	Default	Required
`max_stale`	`duration`	How long to wait for a new sample before marking a stream as stale.	`"5m"`	no
`max_streams`	`number`	Upper limit of streams to track. Set to `0` to disable.	`9223372036854775807`	no

otelcol.processor.deltatocumulative tracks incoming metric streams. Sum and exponential histogram metrics with delta temporality are tracked and converted into cumulative temporality.

If a new sample hasn’t been received since the duration specified by max_stale, tracked streams are considered stale and dropped. max_stale must be set to a duration greater than "0s".

The max_streams attribute configures the upper limit of streams to track. If the limit of tracked streams is reached, new incoming streams are dropped.

Blocks

You can use the following blocks with otelcol.processor.deltatocumulative:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for metrics.

Component health

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

Debug information

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

Debug metrics

otelcol_deltatocumulative_datapoints (counter): Total number of datapoints processed (successfully or unsuccessfully).
otelcol_deltatocumulative_streams_limit (gauge): Upper limit of tracked streams.
otelcol_deltatocumulative_streams_max_stale_seconds (gauge): Duration without new samples after which streams are dropped.
otelcol_deltatocumulative_streams_tracked (gauge): Number of streams currently tracked by the aggregation state.

Examples

Basic usage

This example converts delta temporality metrics to cumulative before sending it to otelcol.exporter.otlphttp for further processing:

otelcol.processor.deltatocumulative "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("<OTLP_SERVER_ENDPOINT>")
  }
}

Export Prometheus data

This example converts delta temporality metrics to cumulative metrics before it’s converted to Prometheus data, which requires cumulative temporality:

otelcol.processor.deltatocumulative "default" {
  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  endpoint {
    url = sys.env("<PROMETHEUS_SERVER_URL>")
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.discovery

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.discovery`

otelcol.processor.discovery accepts traces telemetry data from other otelcol components. It can be paired with discovery.* components, which supply a list of labels for each discovered target. otelcol.processor.discovery adds resource attributes to spans which have a hostname matching the one in the __address__ label provided by the discovery.* component.

Note
otelcol.processor.discovery is a custom component unrelated to any processors from the OpenTelemetry Collector.

Multiple otelcol.processor.discovery components can be specified by giving them different labels.

Note
It can be difficult to follow OpenTelemetry semantic conventions when adding resource attributes via otelcol.processor.discovery:

discovery.relabel and most discovery.* processes such as discovery.kubernetes can only emit Prometheus-compatible labels.

Prometheus labels use underscores (_) in labels names, whereas OpenTelemetry semantic conventions use dots (.).

Although otelcol.processor.discovery is able to work with non-Prometheus labels such as ones containing dots, the fact that discovery.* components are generally only compatible with Prometheus naming conventions makes it hard to follow OpenTelemetry semantic conventions in otelcol.processor.discovery.

If your use case is to add resource attributes which contain Kubernetes metadata, consider using otelcol.processor.k8sattributes instead.

The main use case for otelcol.processor.discovery is for users who migrate to Alloy from Grafana Agent Static mode prom_sd_operation_type/prom_sd_pod_associations configuration options.

Usage

otelcol.processor.discovery "<LABEL>" {
  targets = [...]
  output {
    traces  = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.discovery:

Name	Type	Description	Default	Required
`targets`	`list(map(string))`	List of target labels to apply to the spans.		yes
`operation_type`	`string`	Configures whether to update a span’s attribute if it already exists.	`"upsert"`	no
`pod_associations`	`list(string)`	Configures how to decide the hostname of the span.	`["ip", "net.host.ip", "k8s.pod.ip", "hostname", "connection"]`	no

targets could come from discovery.* components:

The __address__ label will be matched against the IP address of incoming spans.
- If __address__ contains a port, it’s ignored.
If a match is found, then relabeling rules are applied.
- Labels starting with __ won’t be added to the spans.

The supported values for operation_type are:

insert: Inserts a new resource attribute if the key doesn’t already exist.
update: Updates a resource attribute if the key already exists.
upsert: Either inserts a new resource attribute if the key doesn’t already exist, or updates a resource attribute if the key does exist.

The supported values for pod_associations are:

ip: The hostname will be sourced from an ip resource attribute.
net.host.ip: The hostname will be sourced from a net.host.ip resource attribute.
k8s.pod.ip: The hostname will be sourced from a k8s.pod.ip resource attribute.
hostname: The hostname will be sourced from a host.name resource attribute.
connection: The hostname will be sourced from the context from the incoming requests (gRPC and HTTP).

If multiple pod_associations methods are enabled, the order of evaluation is honored. For example, when pod_associations is ["ip", "net.host.ip"], "net.host.ip" may be matched only if "ip" hasn’t already matched.

Blocks

You can use the following block with otelcol.processor.discovery:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`traces`	`list(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 traces argument accordingly to send telemetry data to other components.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

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

traces

Component health

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

Debug information

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

Examples

Basic usage

discovery.http "dynamic_targets" {
    url              = "https://example.com/scrape_targets"
    refresh_interval = "15s"
}

otelcol.processor.discovery "default" {
    targets = discovery.http.dynamic_targets.targets

    output {
        traces = [otelcol.exporter.otlphttp.default.input]
    }
}

Use more than one discovery process

Outputs from more than one discovery process can be combined via the array.concat function.

discovery.http "dynamic_targets" {
    url              = "https://example.com/scrape_targets"
    refresh_interval = "15s"
}

discovery.kubelet "k8s_pods" {
  bearer_token_file = "/var/run/secrets/kubernetes.io/serviceaccount/token"
  namespaces        = ["default", "kube-system"]
}

otelcol.processor.discovery "default" {
    targets = array.concat(discovery.http.dynamic_targets.targets, discovery.kubelet.k8s_pods.targets)

    output {
        traces = [otelcol.exporter.otlphttp.default.input]
    }
}

Use a preconfigured list of attributes

It’s not necessary to use a discovery component. In the following example, both a test_label and a test.label.with.dots resource attributes will be added to a span if its IP address is “1.2.2.2”. The __internal_label__ will be not be added to the span, because it begins with a double underscore (__).

otelcol.processor.discovery "default" {
    targets = [{
        "__address__"          = "1.2.2.2",
        "__internal_label__"   = "test_val",
        "test_label"           = "test_val2",
        "test.label.with.dots" = "test.val2.with.dots"}]

    output {
        traces = [otelcol.exporter.otlphttp.default.input]
    }
}

Compatible components

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

Components that export Targets
Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.filter

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.filter`

otelcol.processor.filter filters out accepted telemetry data from other otelcol components using the OpenTelemetry Transformation Language (OTTL). If any of the OTTL statements evaluates to true, the telemetry data is dropped.

OTTL statements consist of OTTL Converter functions, which act on paths. A path is a reference to a telemetry data such as:

Resource attributes.
Instrumentation scope name.
Span attributes.

In addition to the standard OTTL Converter functions, the following metrics-only functions are used exclusively by the processor:

OTTL statements used in otelcol.processor.filter mostly contain constructs such as:

Booleans:
- not true
- not IsMatch(name, "http_.*")
Math expressions:
- 1 + 1
- end_time_unix_nano - start_time_unix_nano
- sum([1, 2, 3, 4]) + (10 / 1) - 1

Note
Raw Alloy syntax strings can be used to write OTTL statements. For example, the OTTL statement attributes["grpc"] == true is written in Alloy syntax as `attributes[“grpc”] == true`

Note
otelcol.processor.filter is a wrapper over the upstream OpenTelemetry Collector filter processor. If necessary, bug reports or feature requests will be redirected to the upstream repository.

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

Warning
Exercise caution when using otelcol.processor.filter:

Make sure you understand schema/format of the incoming data and test the configuration thoroughly. In general, use a configuration that’s as specific as possible ensure you retain only the data you want to keep.

Orphaned Telemetry: The processor allows dropping spans. Dropping a span may lead to orphaned spans if the dropped span is a parent. Dropping a span may lead to orphaned logs if the log references the dropped span.

Usage

otelcol.processor.filter "<LABEL>" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following argument with otelcol.processor.filter:

Name	Type	Description	Default	Required
`error_mode`	`string`	How to react to errors if they occur while processing a statement.	`"propagate"`	no

The supported values for error_mode are:

ignore: Ignore errors returned by conditions, log them, and continue on to the next condition. This is the recommended mode.
silent: Ignore errors returned by conditions, don’t log them, and continue on to the next condition.
propagate: Return the error up the pipeline. This will result in the payload being dropped from Alloy.

Blocks

You can use the following blocks with otelcol.processor.filter:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`logs`

Note
The logs block is deprecated. Use [log_conditions][log_conditions] instead.

The logs block specifies statements that filter log telemetry signals. Only logs blocks can be specified.

Name	Type	Description	Default	Required
`log_record`	`list(string)`	List of OTTL statements filtering OTLP metric.		no

The syntax of OTTL statements depends on the OTTL context. Refer to the OpenTelemetry documentation for more information:

OTTL log context

Only one of the statements inside the list of statements has to be satisfied.

`metrics`

Note
The metrics block is deprecated. Use [metric_conditions][metric_conditions] instead.

The metrics block specifies statements that filter metric telemetry signals. Only one metrics blocks can be specified.

Name	Type	Description	Default	Required
`datapoint`	`list(string)`	List of OTTL statements filtering OTLP metric datapoints.		no
`metric`	`list(string)`	List of OTTL statements filtering OTLP metric.		no

The syntax of OTTL statements depends on the OTTL context. Refer to the OpenTelemetry documentation for more information:

Statements are checked in order from “high level” to “low level” telemetry, in this order:

metric
datapoint

If at least one metric condition is satisfied, the datapoint conditions won’t be checked. Only one of the statements inside the list of statements has to be satisfied.

If all datapoints for a metric are dropped, the metric will also be dropped.

`traces`

Note
The traces block is deprecated. Use [trace_conditions][trace_conditions] instead.

The traces block specifies statements that filter trace telemetry signals. Only one traces block can be specified.

Name	Type	Description	Default	Required
`span`	`list(string)`	List of OTTL statements filtering OTLP spans.		no
`spanevent`	`list(string)`	List of OTTL statements filtering OTLP span events.		no

The syntax of OTTL statements depends on the OTTL context. See the OpenTelemetry documentation for more information:

Statements are checked in order from “high level” to “low level” telemetry, in this order:

span
spanevent

If at least one span condition is satisfied, the spanevent conditions won’t be checked. Only one of the statements inside the list of statements has to be satisfied.

If all span events for a span are dropped, the span will be left intact.

`trace_conditions`

The trace_conditions block specifies inferred-context OTTL conditions for traces.

Name	Type	Description	Default	Required
`conditions`	`list(string)`	List of OTTL conditions.		yes
`context`	`string`	OTTL context for evaluating conditions.		no

Supported context values are:

resource
span
spanevent

For more details on available contexts, refer to filterprocessor context documentation.

`metric_conditions`

The metric_conditions block specifies inferred-context OTTL conditions for metrics.

Name	Type	Description	Default	Required
`conditions`	`list(string)`	List of OTTL conditions.		yes
`context`	`string`	OTTL context for evaluating conditions.		no

Supported context values are:

resource
metric
datapoint

For more details on available contexts, refer to filterprocessor context documentation.

`log_conditions`

The log_conditions block specifies inferred-context OTTL conditions for logs.

Name	Type	Description	Default	Required
`conditions`	`list(string)`	List of OTTL conditions.		yes
`context`	`string`	OTTL context for evaluating conditions.		no

Supported context values are:

resource
log

For more details on available contexts, refer to filterprocessor context documentation.

trace_conditions, metric_conditions, and log_conditions can’t be used together with traces, metrics, and logs blocks in the same component.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

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

Debug metrics

otelcol.processor.filter doesn’t expose any component-specific debug metrics.

Examples

Drop spans which contain a certain span attribute

This example drops the signals that have the attribute container.name set to the value app_container_1.

otelcol.processor.filter "default" {
  error_mode = "ignore"

  traces {
    span = [
      `attributes["container.name"] == "app_container_1"`,
    ]
  }

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

Drop metrics based on either of two criteria

This example drops metrics which satisfy at least one of two OTTL statements:

The metric name is my.metric and there is a my_label resource attribute with a value of abc123.
The metric is a histogram.

otelcol.processor.filter "default" {
  error_mode = "ignore"

  metrics {
    metric = [
       `name == "my.metric" and resource.attributes["my_label"] == "abc123"`,
       `type == METRIC_DATA_TYPE_HISTOGRAM`,
    ]
  }

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

Drop non-HTTP spans and sensitive logs

otelcol.processor.filter "default" {
  error_mode = "ignore"

  traces {
    span = [
      `attributes["http.request.method"] == nil`,
    ]
  }

  logs {
    log_record = [
      `IsMatch(body, ".*password.*")`,
      `severity_number < SEVERITY_NUMBER_WARN`,
    ]
  }

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

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.groupbyattrs

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.groupbyattrs`

otelcol.processor.groupbyattrs accepts spans, metrics, and traces from other otelcol components and groups them under the same resource.

Note
otelcol.processor.groupbyattrs is a wrapper over the upstream OpenTelemetry Collector groupbyattrs processor. If necessary, bug reports or feature requests will be redirected to the upstream repository.

We recommend you use the groupbyattrs processor together with otelcol.processor.batch, as a consecutive step. This will reduce the fragmentation of data by grouping records together under the matching Resource/Instrumentation Library.

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

Usage

otelcol.processor.groupbyattrs "<LABEL>" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following argument with otelcol.processor.groupbyattrs:

Name	Type	Description	Default	Required
`keys`	`list(string)`	Keys that will be used to group the spans, log records, or metric data points together.	`[]`	no

keys is a string array that’s used for grouping the data. If it’s empty, the processor performs compaction and reassociates all spans with matching Resource and InstrumentationLibrary.

Blocks

You can use the following blocks with otelcol.processor.groupbyattrs:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	Accepts `otelcol.Consumer` data for metrics, logs, or traces.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

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

Debug metrics

otelcol.processor.groupbyattrs doesn’t expose any component-specific debug metrics.

Examples

Group metrics

Consider the following metrics, all originally associated to the same Resource:

Resource {host.name="localhost",source="prom"}
  Metric "gauge-1" (GAUGE)
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-B",id="eth0"}
  Metric "gauge-1" (GAUGE) // Identical to previous Metric
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-B",id="eth0"}
  Metric "mixed-type" (GAUGE)
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-B",id="eth0"}
  Metric "mixed-type" (SUM)
    DataPoint {host.name="host-A",id="eth0"}
    DataPoint {host.name="host-A",id="eth0"}
  Metric "dont-move" (Gauge)
    DataPoint {id="eth0"}

With the following configuration, the groupbyattrs will re-associate the metrics with either host-A or host-B, based on the value of the host.name attribute.

otelcol.processor.groupbyattrs "default" {
  keys = [ "host.name" ]
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

The output of the processor is:

Resource {host.name="localhost",source="prom"}
  Metric "dont-move" (Gauge)
    DataPoint {id="eth0"}
Resource {host.name="host-A",source="prom"}
  Metric "gauge-1"
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
  Metric "mixed-type" (GAUGE)
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
  Metric "mixed-type" (SUM)
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
Resource {host.name="host-B",source="prom"}
  Metric "gauge-1"
    DataPoint {id="eth0"}
    DataPoint {id="eth0"}
  Metric "mixed-type" (GAUGE)
    DataPoint {id="eth0"}

This output demonstrates how otelcol.processor.groupbyattrs works in various situations:

The DataPoints for the gauge-1 (GAUGE) metric were originally split under 2 Metric instances and have been merged in the output.
The DataPoints of the mixed-type (GAUGE) and mixed-type (SUM) metrics haven’t been merged under the same Metric, because their DataType is different.
The dont-move metric DataPoints don’t have a host.name attribute and therefore remained under the original Resource.
The new Resources inherited the attributes from the original Resource (source="prom"), plus the specified attributes from the processed metrics (host.name="host-A" or host.name="host-B").
The specified “grouping” attributes that are set on the new Resources are also removed from the metric DataPoints.
While not shown in the above example, the processor also merges collections of records under matching InstrumentationLibrary.

Compaction

Sometimes telemetry data can become fragmented due to multiple duplicated ResourceSpans/ResourceLogs/ResourceMetrics objects. This leads to additional memory consumption, increased processing costs, inefficient serialization and increase of the export requests. In such situations, otelcol.processor.groupbyattrs can be used to compact the data with matching Resource and InstrumentationLibrary properties.

For example, consider this input data:

Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=1, ...}
  InstrumentationLibrary {name="OtherLibrary"}
  Spans
    Span {span_id=2, ...}
    
Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=3, ...}
    
Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=4, ...}
    
Resource {host.name="otherhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=5, ...}

You can use otelcol.processor.groupbyattrs with its default configuration to compact the data:

otelcol.processor.groupbyattrs "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

The output is:

Resource {host.name="localhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=1, ...}
    Span {span_id=3, ...}
    Span {span_id=4, ...}
  InstrumentationLibrary {name="OtherLibrary"}
  Spans
    Span {span_id=2, ...}

Resource {host.name="otherhost"}
  InstrumentationLibrary {name="MyLibrary"}
  Spans
    Span {span_id=5, ...}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.interval

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.interval`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.processor.interval aggregates metrics and periodically forwards the latest values to the next component in the pipeline. The processor supports aggregating the following metric types:

Monotonically increasing, cumulative sums
Monotonically increasing, cumulative histograms
Monotonically increasing, cumulative exponential histograms
Gauges
Summaries

The following metric types won’t be aggregated and will instead be passed, unchanged, to the next component in the pipeline:

All delta metrics
Non-monotonically increasing sums

Note
Aggregating data over an interval is an inherently lossy process. You lose precision for monotonically increasing cumulative sums, histograms, and exponential histograms, but you don’t lose overall data. You can lose data when you aggregate non-monotonically increasing sums, gauges, and summaries. For example, a value can increase and decrease to the original value, and you can lose this change in the aggregation. In most cases, this type of data loss is acceptable. However, you can change the configuration so that these changed values pass through and aren’t aggregated.

Warning
After exporting, any internal state is cleared. If no new metrics come in, the next interval will export nothing.

Note
otelcol.processor.interval is a wrapper over the upstream OpenTelemetry Collector interval processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Usage

otelcol.processor.interval "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

You can use the following argument with otelcol.processor.interval:

Name	Type	Description	Default	Required
`interval`	`duration`	The interval in which the processor should export aggregated metrics.	`"60s"`	no

Blocks

You can use the following blocks with otelcol.processor.interval:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`passthrough`

The passthrough block configures which metric types should be passed through instead of being aggregated.

The following attributes are supported:

Name	Type	Description	Default	Required
`gauge`	`bool`	Determines whether gauge metrics should be passed through as they’re or aggregated.	`false`	no
`summary`	`bool`	Determines whether summary metrics should be passed through as they’re or aggregated.	`false`	no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for metrics.

Component health

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

Debug information

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

Example

This example receives OTLP metrics and aggregates them for 30s before sending to the next exporter.

otelcol.receiver.otlp "default" {
  grpc { ... }
  http { ... }

  output {
    metrics = [otelcol.processor.interval.default.input]
  }
}

otelcol.processor.interval "default" {
  interval = "30s"
  output {
    metrics = [otelcol.exporter.otlphttp.grafana_cloud.input]
  }
}

otelcol.exporter.otlphttp "grafana_cloud" {
  client {
    endpoint = "https://otlp-gateway-prod-gb-south-0.grafana.net/otlp"
    auth     = otelcol.auth.basic.grafana_cloud.handler
  }
}

otelcol.auth.basic "grafana_cloud" {
  username = env("<GRAFANA_CLOUD_USERNAME>")
  password = env("<GRAFANA_CLOUD_API_KEY>")
}

Timestamp	Metric Name	Aggregation Temporality	Attributes	Value
0	`test_metric`	Cumulative	`labelA: example1`	4.0
2	`test_metric`	Cumulative	`labelA: example2`	3.1
4	`other_metric`	Delta	`fruitType: orange`	77.4
6	`test_metric`	Cumulative	`labelA: example1`	8.2
8	`test_metric`	Cumulative	`labelA: example1`	12.8
10	`test_metric`	Cumulative	`labelA: example2`	6.4

The processor immediately passes the following metric to the next processor in the chain because it’s a Delta metric.

Timestamp	Metric Name	Aggregation Temporality	Attributes	Value
4	`other_metric`	Delta	`fruitType: orange`	77.4

At the next interval (15s by default), the processor passed the following metrics to the next processor in the chain.

Timestamp	Metric Name	Aggregation Temporality	Attributes	Value
8	`test_metric`	Cumulative	`labelA: example1`	12.8
10	`test_metric`	Cumulative	`labelA: example1`	6.4

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.k8sattributes

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.k8sattributes`

otelcol.processor.k8sattributes accepts telemetry data from other otelcol components and adds Kubernetes metadata to the resource attributes of spans, logs, or metrics.

Note
otelcol.processor.k8sattributes is a wrapper over the upstream OpenTelemetry Collector k8sattributes processor. If necessary, bug reports or feature requests will be redirected to the upstream repository.

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

Usage

otelcol.processor.k8sattributes "<LABEL>" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.k8sattributes:

Name	Type	Description	Default	Required
`auth_type`	`string`	Authentication method when connecting to the Kubernetes API.	`"serviceAccount"`	no
`passthrough`	`bool`	Pass through signals as-is, only adding a `k8s.pod.ip` resource attribute.	`false`	no
`wait_for_metadata_timeout`	`duration`	How long to wait for Kubernetes metadata to arrive.	`"10s"`	no
`wait_for_metadata`	`bool`	Whether to wait for Kubernetes metadata to arrive before processing telemetry.	`false`	no

The supported values for auth_type are:

none: No authentication is required.
serviceAccount: Use the built-in service account that Kubernetes automatically provisions for each Pod.
kubeConfig: Use local credentials like those used by kubectl.
tls: Use client TLS authentication.

Setting passthrough to true enables the “passthrough mode” of otelcol.processor.k8sattributes:

Only a k8s.pod.ip resource attribute will be added.
No other metadata will be added.
The Kubernetes API won’t be accessed.
To correctly detect the Pod IPs, Alloy must receive spans directly from services.
The passthrough setting is useful when configuring Alloy as a Kubernetes Deployment.

A Alloy running as a Deployment can’t detect the IP addresses of pods generating telemetry data without any of the well-known IP attributes. If the Deployment Alloy receives telemetry from Alloys deployed as DaemonSet, then some of those attributes might be missing. As a workaround, you can configure the DaemonSet Alloys with passthrough set to true.

By default, otelcol.processor.k8sattributes is ready as soon as it starts, even if no metadata has been fetched yet. If telemetry is sent to this processor before the metadata is synced, there will be no metadata to enrich the telemetry with.

To wait for the metadata to be synced before otelcol.processor.k8sattributes is ready, set the wait_for_metadata option to true. Then, the processor won’t be ready until the metadata is fully synced. As a result, the start-up of Alloy will be blocked. If the metadata can’t be synced by the time the wait_for_metadata_timeout duration is reached, otelcol.processor.k8sattributes will become unhealthy and fail to start.

If otelcol.processor.k8sattributes is unhealthy, other Alloy components will still be able to start. However, they may be unable to send telemetry to otelcol.processor.k8sattributes.

Blocks

You can use the following blocks with otelcol.processor.k8sattributes:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`exclude`

The exclude block configures which pods to exclude from the processor.

Note
Pods with the name jaeger-agent or jaeger-collector are excluded by default.

`pod`

The pod block configures a Pod to be excluded from the processor.

The following attributes are supported:

Name	Type	Description	Default	Required
`name`	`string`	The name of the Pod		yes

`extract`

The extract block configures which metadata, annotations, and labels to extract from the Pod.

The following attributes are supported:

Name	Type	Description	Default	Required
`deployment_name_from_replicaset`	`bool`	Whether to set the deployment name by trimming the hash from the end of the replica set.	`false`	no
`metadata`	`list(string)`	Pre-configured metadata keys to add.	See below	no
`otel_annotations`	`bool`	Whether to set the recommended resource attributes.	`false`	no

The supported metadata keys are:

container.id
container.image.name
container.image.tag
k8s.container.name
k8s.cronjob.name
k8s.cronjob.uid
k8s.daemonset.name
k8s.daemonset.uid
k8s.deployment.name
k8s.deployment.uid
k8s.job.name
k8s.job.uid
k8s.namespace.name
k8s.node.name
k8s.pod.name
k8s.pod.start_time
k8s.pod.uid
k8s.replicaset.name
k8s.replicaset.uid
k8s.statefulset.name
k8s.statefulset.uid
service.instance.id
service.name
service.namespace
service.version

The service.* metadata are calculated following the OpenTelemetry semantic conventions.

By default, if metadata isn’t specified, the following fields are extracted and added to spans, metrics, and logs as resource attributes:

container.image.name (requires one of the following additional attributes to be set: container.id or k8s.container.name)
container.image.tag (requires one of the following additional attributes to be set: container.id or k8s.container.name)
k8s.container.name (requires an additional attribute to be set: container.id)
k8s.deployment.name (if the Pod is controlled by a deployment)
k8s.namespace.name
k8s.node.name
k8s.pod.name
k8s.pod.start_time
k8s.pod.uid

When otel_annotations is set to true, annotations such as resource.opentelemetry.io/exampleResource will be translated to the exampleResource resource attribute, etc.

When deployment_name_from_replicaset is set to true, the processor will extract deployment name from replicaset name by trimming pod template hash. This will disable watching for replicaset resources, which can be useful in environments with limited RBAC permissions as the processor will not need get, watch, and list permissions for replicasets.

`annotation`

The annotation block configures how to extract Kubernetes annotations.

The following attributes are supported:

Name	Type	Description	Default	Required
`from`	`string`	The source of the labels or annotations.	`pod`	no
`key_regex`	`string`	A regular expression used to extract a key that matches the regular expression.	`""`	no
`key`	`string`	The annotation or label name. This key must exactly match an annotation or label name.	`""`	no
`tag_name`	`string`	The name of the resource attribute added to logs, metrics, or spans.	`""`	no

The from attribute must be one of pod, namespace, deployment, statefulset, daemonset, job, or node.

When you don’t specify the tag_name, a default tag name is used with the format:

k8s.pod.annotations.<annotation key>
k8s.pod.labels.<label key>

For example, if tag_name isn’t specified and the key is git_sha, the attribute name will be k8s.pod.annotations.git_sha.

You can set either the key attribute or the key_regex attribute, but not both. When key_regex is present, tag_name supports back reference to both named capturing and positioned capturing.

For example, assume your Pod spec contains the following labels:

app.kubernetes.io/component: mysql
app.kubernetes.io/version: 5.7.21

If you’d like to add tags for all labels with the prefix app.kubernetes.io/ and trim the prefix, then you can specify the following extraction rules:

extract {
  label {
    from = "pod"
    key_regex = "kubernetes.io/(.*)"
    tag_name  = "$1"
  }
}

These rules add the component and version tags to the spans or metrics.

You can set the from attribute to "pod", "namespace", "node", or "deployment".

Caution
The regex argument has been removed. Use the ExtractPatterns function from otelcol.processor.transform instead.

`label` extract

The label block configures how to extract Kubernetes labels.

The following attributes are supported:

Name	Type	Description	Default	Required
`from`	`string`	The source of the labels or annotations.	`pod`	no
`key_regex`	`string`	A regular expression used to extract a key that matches the regular expression.	`""`	no
`key`	`string`	The annotation or label name. This key must exactly match an annotation or label name.	`""`	no
`tag_name`	`string`	The name of the resource attribute added to logs, metrics, or spans.	`""`	no

The from attribute must be one of pod, namespace, deployment, statefulset, daemonset, job, or node.

When you don’t specify the tag_name, a default tag name is used with the format:

k8s.pod.annotations.<annotation key>
k8s.pod.labels.<label key>

For example, if tag_name isn’t specified and the key is git_sha, the attribute name will be k8s.pod.annotations.git_sha.

You can set either the key attribute or the key_regex attribute, but not both. When key_regex is present, tag_name supports back reference to both named capturing and positioned capturing.

For example, assume your Pod spec contains the following labels:

app.kubernetes.io/component: mysql
app.kubernetes.io/version: 5.7.21

If you’d like to add tags for all labels with the prefix app.kubernetes.io/ and trim the prefix, then you can specify the following extraction rules:

extract {
  label {
    from = "pod"
    key_regex = "kubernetes.io/(.*)"
    tag_name  = "$1"
  }
}

These rules add the component and version tags to the spans or metrics.

You can set the from attribute to "pod", "namespace", "node", or "deployment".

Caution
The regex argument has been removed. Use the ExtractPatterns function from otelcol.processor.transform instead.

`filter`

The filter block configures which nodes to get data from and which fields and labels to fetch.

The following attributes are supported:

Name	Type	Description	Default	Required
`node`	`string`	Configures a Kubernetes node name or host name.	`""`	no
`namespace`	`string`	Filters all pods by the provided namespace. All other pods are ignored.	`""`	no

If node is specified, then any pods not running on the specified node will be ignored by otelcol.processor.k8sattributes.

`field`

The field block allows you to filter pods by generic Kubernetes fields.

The following attributes are supported:

Name	Type	Description	Default	Required
`key`	`string`	The key or name of the field or labels that a filter can use.		yes
`value`	`string`	The value associated with the key that a filter can use.		yes
`op`	`string`	The filter operation to apply on the given key: value pair.	`equals`	no

You can use the following values for op:

equals: The field value must equal the provided value.
not-equals: The field value must not be equal to the provided value.
exists: The field value must exist. Only applicable to annotation fields.
does-not-exist: The field value must not exist. Only applicable to annotation fields.

`label` filter

The label block allows you to filter pods by generic Kubernetes labels.

The following attributes are supported:

Name	Type	Description	Default	Required
`key`	`string`	The key or name of the field or labels that a filter can use.		yes
`value`	`string`	The value associated with the key that a filter can use.		yes
`op`	`string`	The filter operation to apply on the given key: value pair.	`equals`	no

You can use the following values for op:

equals: The field value must equal the provided value.
not-equals: The field value must not be equal to the provided value.
exists: The field value must exist. Only applicable to annotation fields.
does-not-exist: The field value must not exist. Only applicable to annotation fields.

`pod_association`

The pod_association block configures rules on how to associate logs/traces/metrics to pods.

The pod_association block doesn’t support any arguments and is configured fully through child blocks.

The pod_association block can be repeated multiple times, to configure additional rules.

Example

pod_association {
    source {
        from = "resource_attribute"
        name = "k8s.pod.ip"
    }
}

pod_association {
    source {
        from = "resource_attribute"
        name = "k8s.pod.uid"
    }
    source {
        from = "connection"
    }
}

`source`

The source block configures a Pod association rule. This is used by the k8sattributes processor to determine the Pod associated with a telemetry signal.

When multiple source blocks are specified inside a pod_association block, both source blocks has to match for the Pod to be associated with the telemetry signal.

The following attributes are supported:

Name	Type	Description	Default	Required
`from`	`string`	The association method. Currently supports `resource_attribute` and `connection`		yes
`name`	`string`	Name represents extracted key name. For example, `ip`, `pod_uid`, `k8s.pod.ip`		no

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

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

Examples

Basic usage

In most cases, this is enough to get started. It’ll add these resource attributes to all logs, metrics, and traces:

k8s.deployment.name
k8s.namespace.name
k8s.node.name
k8s.pod.name
k8s.pod.start_time
k8s.pod.uid

Example:

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.k8sattributes.default.input]
    logs    = [otelcol.processor.k8sattributes.default.input]
    traces  = [otelcol.processor.k8sattributes.default.input]
  }
}

otelcol.processor.k8sattributes "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
    logs    = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("<OTLP_ENDPOINT>")
  }
}

Add additional metadata and labels

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.k8sattributes.default.input]
    logs    = [otelcol.processor.k8sattributes.default.input]
    traces  = [otelcol.processor.k8sattributes.default.input]
  }
}

otelcol.processor.k8sattributes "default" {
  extract {
    label {
      from      = "pod"
      key_regex = "(.*)/(.*)"
      tag_name  = "$1.$2"
    }

    metadata = [
      "k8s.namespace.name",
      "k8s.deployment.name",
      "k8s.statefulset.name",
      "k8s.daemonset.name",
      "k8s.cronjob.name",
      "k8s.job.name",
      "k8s.node.name",
      "k8s.pod.name",
      "k8s.pod.uid",
      "k8s.pod.start_time",
    ]

    otel_annotations = true
  }

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

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("<OTLP_ENDPOINT>")
  }
}

Add Kubernetes metadata to Prometheus metrics

otelcol.processor.k8sattributes adds metadata to metrics signals in the form of resource attributes. To display the metadata as labels of Prometheus metrics, the OTLP attributes must be converted from resource attributes to datapoint attributes. One way to do this is by using an otelcol.processor.transform component.

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.k8sattributes.default.input]
  }
}

otelcol.processor.k8sattributes "default" {
  extract {
    label {
      from = "pod"
    }

    metadata = [
      "k8s.namespace.name",
      "k8s.pod.name",
    ]
  }

  output {
    metrics = [otelcol.processor.transform.add_kube_attrs.input]
  }
}

otelcol.processor.transform "add_kube_attrs" {
  error_mode = "ignore"

  metric_statements {
    context = "datapoint"
    statements = [
      "set(attributes[\"k8s.pod.name\"], resource.attributes[\"k8s.pod.name\"])",
      "set(attributes[\"k8s.namespace.name\"], resource.attributes[\"k8s.namespace.name\"])",
    ]
  }

  output {
    metrics = [otelcol.exporter.prometheus.default.input]
  }
}

otelcol.exporter.prometheus "default" {
  forward_to = [prometheus.remote_write.mimir.receiver]
}

prometheus.remote_write "mimir" {
  endpoint {
    url = "http://mimir:9009/api/v1/push"
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.memory_limiter

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.memory_limiter`

otelcol.processor.memory_limiter is used to prevent out of memory situations on a telemetry pipeline by performing periodic checks of memory usage. If usage exceeds the defined limits, data is dropped and garbage collections are triggered to reduce it.

The memory_limiter component uses both soft and hard limits, where the hard limit is always equal or larger than the soft limit. When memory usage goes above the soft limit, the processor component drops data and returns errors to the preceding components in the pipeline. When usage exceeds the hard limit, the processor forces a garbage collection to try and free memory. When usage is below the soft limit, no data is dropped and no forced garbage collection is performed.

Note
otelcol.processor.memory_limiter is a wrapper over the upstream OpenTelemetry Collector memorylimiter processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.memory_limiter "<LABEL>" {
  check_interval = "1s"

  limit = "50MiB" // alternatively, set `limit_percentage` and `spike_limit_percentage`

  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.memory_limiter:

Name	Type	Description	Default	Required
`check_interval`	`duration`	How often to check memory usage.		yes
`limit_percentage`	`int`	Maximum amount of total available memory targeted to be allocated by the process heap.	`0`	no
`limit`	`string`	Maximum amount of memory targeted to be allocated by the process heap.	`"0MiB"`	no
`spike_limit_percentage`	`int`	Maximum spike expected between the measurements of memory usage.	`0`	no
`spike_limit`	`string`	Maximum spike expected between the measurements of memory usage.	20% of `limit`	no

The arguments must define either limit or the limit_percentage, spike_limit_percentage pair, but not both.

The configuration options limit and limit_percentage define the hard limits. The soft limits are then calculated as the hard limit minus the spike_limit or spike_limit_percentage values respectively. The recommended value for spike limits is about 20% of the corresponding hard limit.

The recommended check_interval value is 1 second. If the traffic through the component is spiky in nature, it’s recommended to either decrease the interval or increase the spike limit to avoid going over the hard limit.

The limit and spike_limit values must be larger than 1 MiB.

Blocks

You can use the following blocks with otelcol.processor.memory_limiter:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

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

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.metric_start_time

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.metric_start_time`

otelcol.processor.metric_start_time accepts metrics from other otelcol components and sets the start time for cumulative metric datapoints which do not already have a start time. This processor is commonly used with otelcol.receiver.prometheus, which produces metric points without a start time.

Grafana Mimir ingests OTLP metric start times only when it is configured with the -distributor.otel-created-timestamp-zero-ingestion-enabled flag. Without this configuration, setting start times in Alloy has no effect on ingestion behavior.

Note
otelcol.processor.metric_start_time is a wrapper over the upstream OpenTelemetry Collector metricstarttime processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.metric_start_time "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.metric_start_time:

Name	Type	Description	Default	Required
`strategy`	`string`	Strategy to use for setting start time.	`"true_reset_point"`	no
`gc_interval`	`duration`	How long to wait before removing a metric from the cache.	`"10m"`	no
`start_time_metric_regex`	`string`	Regex for a metric name containing the start time. Only applies when strategy is `start_time_metric`.	`""`	no

Strategies

The strategy argument determines how the processor handles missing start times for cumulative metrics. Valid values are:

`true_reset_point` (default)

Produces a stream of points that starts with a True Reset Point. The true reset point has its start time set to its end timestamp, indicating the absolute value of the cumulative point when the collector first observed it. Subsequent points reuse the start timestamp of the initial true reset point.

Pros:

The absolute value of the cumulative metric is preserved.
It is possible to calculate the correct rate between any two points since the timestamps and values are not modified.

Cons:

This strategy is stateful because the initial True Reset point is necessary to properly calculate rates on subsequent points.
The True Reset point doesn’t make sense semantically. It has a zero duration, but non-zero values.
Many backends reject points with equal start and end timestamps.
- If the True Reset point is rejected, the next point will appear to have a very large rate.

Example transformation:

Input Timestamp	Input Value	Output Start Time	Output End Time	Output Value
T1	10	T1	T1	10
T2	15	T1	T2	15
T3	25	T1	T3	25

`subtract_initial_point`

Drops the first point in a cumulative series, subtracting that point’s value from subsequent points and using the initial point’s timestamp as the start timestamp for subsequent points.

Pros:

Cumulative semantics are preserved. This means that for a point with a given [start, end] interval, the cumulative value occurred in that interval.
Rates over resulting timeseries are correct, even if points are lost. This strategy is not stateful.

Cons:

The absolute value of counters is modified. This is generally not an issue, since counters are usually used to compute rates.
The initial point is dropped, which loses information.

Example transformation:

Input Timestamp	Input Value	Output Start Time	Output End Time	Output Value
T1	10	(dropped)	(dropped)	(dropped)
T2	15	T1	T2	5
T3	25	T1	T3	15

`start_time_metric`

Looks for the process_start_time metric (or a metric matching start_time_metric_regex) and uses its value as the start time for all other cumulative points in the batch of metrics. If the start time metric is not found, it falls back to the time at which the collector started.

This strategy should only be used in limited circumstances:

When your application has a metric with the start time in Unix seconds, such as process_start_time_seconds.
The processor is used before any batching, so that the batch of metrics all originate from a single application.
This strategy can be used when the collector is run as a sidecar to the application, where the collector’s start time is a good approximation of the application’s start time.

Cons:

If the collector’s start time is used as a fallback and the collector restarts, it can produce rates that are incorrect and higher than expected.
The process’ start time isn’t the time at which individual instruments or timeseries are initialized. It may result in lower rates if the first observation is significantly later than the process’ start time.

Example transformation:

Given a process_start_time_seconds metric with value T0:

Input Timestamp	Input Value	Output Start Time	Output End Time	Output Value
T1	10	T0	T1	10
T2	15	T0	T2	15
T3	25	T0	T3	25

Garbage collection

The gc_interval argument defines how often to check if any resources have not emitted data since the last check. If a resource hasn’t emitted any data, it’s removed from the cache to free up memory. Any additional data from resources removed from the cache will be given a new start time.

Blocks

You can use the following blocks with otelcol.processor.metric_start_time:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for metrics.

Component health

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

Debug information

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

Examples

Basic usage with default strategy

This example uses the default true_reset_point strategy to set start times for Prometheus metrics:

otelcol.receiver.prometheus "default" {
  output {
    metrics = [otelcol.processor.metric_start_time.default.input]
  }
}

otelcol.processor.metric_start_time "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Using `subtract_initial_point` strategy

This example uses the subtract_initial_point strategy, which preserves cumulative semantics and produces correct rates:

otelcol.receiver.prometheus "default" {
  output {
    metrics = [otelcol.processor.metric_start_time.default.input]
  }
}

otelcol.processor.metric_start_time "default" {
  strategy = "subtract_initial_point"

  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Use a `start_time_metric` strategy with a custom regular expression

This example uses the start_time_metric strategy with a custom regular expression to find the start time metric:

otelcol.receiver.prometheus "default" {
  output {
    metrics = [otelcol.processor.metric_start_time.default.input]
  }
}

otelcol.processor.metric_start_time "default" {
  strategy                 = "start_time_metric"
  gc_interval              = "1h"
  start_time_metric_regex  = "^.+_start_time$"

  output {
    metrics = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("OTLP_SERVER_ENDPOINT")
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.probabilistic_sampler

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.probabilistic_sampler`

otelcol.processor.probabilistic_sampler accepts logs and traces data from other otelcol components and applies probabilistic sampling based on configuration options.

The probabilistic sampler processor supports several modes of sampling for spans and log records.
Sampling is performed on a per-request basis, considering individual items statelessly. For whole trace sampling, see otelcol.processor.tail_sampling.

For trace spans, this sampler supports probabilistic sampling based on a configured sampling percentage applied to the TraceID. In addition, the sampler recognizes a sampling.priority annotation, which can force the sampler to apply 0% or 100% sampling.

For log records, this sampler can be configured to use the embedded TraceID and follow the same logic as applied to spans.
When the TraceID isn’t defined, the sampler can be configured to apply hashing to a selected log record attribute.
This sampler also supports sampling priority.

Note
otelcol.processor.probabilistic_sampler is a wrapper over the upstream OpenTelemetry Collector Contrib probabilistic_sampler processor. If necessary, bug reports or feature requests will be redirected to the upstream repository.

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

Usage

otelcol.processor.probabilistic_sampler "<LABEL>" {
  output {
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.probabilistic_sampler:

Name	Type	Description	Default	Required
`attribute_source`	`string`	Defines where to look for the attribute in `from_attribute`.	`"traceID"`	no
`fail_closed`	`bool`	Whether to reject items with sampling-related errors.	`true`	no
`from_attribute`	`string`	The name of a log record attribute used for sampling purposes.	`""`	no
`hash_seed`	`uint32`	An integer used to compute the hash algorithm.	`0`	no
`mode`	`string`	Sampling mode.	`"proportional"`	no
`sampling_percentage`	`float32`	Percentage of traces or logs sampled.	`0`	no
`sampling_precision`	`int`	The number of hexadecimal digits used to encode the sampling threshold.	`4`	no
`sampling_priority`	`string`	The name of a log record attribute used to set a different sampling priority from the `sampling_percentage` setting.	`""`	no

You can set mode to "proportional", "equalizing", or "hash_seed". The default is "proportional" unless either hash_seed is configured or attribute_source is set to record. For more information on modes, refer to the upstream Collector’s Mode Selection documentation section.

hash_seed determines an integer to compute the hash algorithm. This argument could be used for both traces and logs. When used for logs, it computes the hash of a log record. For hashing to work, all collectors for a given tier, for example, behind the same load balancer, must have the same hash_seed. It’s also possible to leverage a different hash_seed at different collector tiers to support additional sampling requirements.

sampling_percentage determines the percentage at which traces or logs are sampled. All traces or logs are sampled if you set this argument to a value greater than or equal to 100.

attribute_source (logs only) determines where to look for the attribute in from_attribute. The allowed values are traceID or record.

from_attribute (logs only) determines the name of a log record attribute used for sampling purposes, such as a unique log record ID. The value of the attribute is only used if the trace ID is absent or if attribute_source is set to record.

sampling_priority (logs only) determines the name of a log record attribute used to set a different sampling priority from the sampling_percentage setting. 0 means to never sample the log record, and greater than or equal to 100 means to always sample the log record.

The probabilistic_sampler supports two types of sampling for traces:

sampling.priority semantic convention as defined by OpenTracing.
Trace ID hashing.

The sampling.priority semantic convention takes priority over trace ID hashing. Trace ID hashing samples based on hash values determined by trace IDs.

The probabilistic_sampler supports sampling logs according to their trace ID, or by a specific log record attribute.

sampling_precision must be a value between 1 and 14 (inclusive).

Blocks

You can use the following block with otelcol.processor.probabilistic_sampler:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A 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
traces

Component health

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

Debug information

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

Examples

Basic usage

otelcol.processor.probabilistic_sampler "default" {
  hash_seed           = 123
  sampling_percentage = 15.3

  output {
    logs = [otelcol.exporter.otlphttp.default.input]
  }
}

Sample 15% of the logs

otelcol.processor.probabilistic_sampler "default" {
  sampling_percentage = 15

  output {
    logs = [otelcol.exporter.otlphttp.default.input]
  }
}

Sample logs according to their “logID” attribute

otelcol.processor.probabilistic_sampler "default" {
  sampling_percentage = 15
  attribute_source    = "record"
  from_attribute      = "logID"

  output {
    logs = [otelcol.exporter.otlphttp.default.input]
  }
}

Sample logs according to a “priority” attribute

otelcol.processor.probabilistic_sampler "default" {
  sampling_percentage = 15
  sampling_priority   = "priority"

  output {
    logs = [otelcol.exporter.otlphttp.default.input]
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.resourcedetection

Mon, 13 Apr 2026 07:37:47 +0000

`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

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

Arguments

You can use the following arguments with otelcol.processor.resourcedetection:

Name	Type	Description	Default	Required
`detectors`	`list(string)`	An ordered list of named detectors used to detect resource information.	`["env"]`	no
`override`	`bool`	Configures whether existing resource attributes should be overridden or preserved.	`true`	no
`timeout`	`duration`	Timeout by which all specified detectors must complete.	`"5s"`	no

detectors could contain the following values:

akamai
alibaba_ecs
aks
azure
consul
digitalocean
docker
dynatrace
ec2
ecs
eks
elasticbeanstalk
env
gcp
heroku
hetzner
kubeadm
kubernetes_node
lambda
openshift
nova
oraclecloud
scaleway
tencent_cvm
upcloud
vultr
system

You can customize most detectors 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:

[lambda][lambda]
[elasticbeanstalk][elasticbeanstalk]
[eks][eks]
[ecs][ecs]
[ec2][ec2]

There are several delectors which are not configured through blocks:

`env` detector

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.

`dynatrace` detector

The dynatrace block loads resource information from the dt_host_metadata.properties file which is located in the /var/lib/dynatrace/enrichment (on Unix systems) or %ProgramData%\dynatrace\enrichment (on Windows) directories.

The dynatrace detector reads the following resource attributes from the metadata file: host.name, dt.entity.host, and dt.smartscape.host. These attributes are not configurable.

Blocks

You can use the following blocks with otelcol.processor.resourcedetection:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`akamai`

The akamai block queries the Akamai connected cloud instance metadata service to retrieve various resource attributes from the Akamai cloud environment.

The akamai block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`akamai` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.provider: "akamai"

`aks`

The aks block adds resource attributes related to Azure AKS.

The aks block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`aks` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`k8s.cluster.name`][res-attr-cfg]	Toggles the `k8s.cluster.name` resource attribute. Sets `enabled` to `false` by default.	no

Example values:

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

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 doesn’t contain underscores and if a custom infrastructure resource group name wasn’t used.

If accurate parsing can’t be performed, the infrastructure resource group value is returned. This value can be used to uniquely identify the cluster, because Azure won’t allow users to create multiple clusters with the same infrastructure resource group name.

`azure`

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

The azure block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

The azure block supports the following attributes:

Attribute	Type	Description	Default	Required
`tags`	`list(string)`	A list of regular expressions to match tag keys to add as resource attributes can be specified.	`[]`	no

`azure` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`azure.resourcegroup.name`][res-attr-cfg]	Toggles the `azure.resourcegroup.name` resource attribute. Sets `enabled` to `true` by default.	no
[`azure.vm.name`][res-attr-cfg]	Toggles the `azure.vm.name` resource attribute. Sets `enabled` to `true` by default.	no
[`azure.vm.scaleset.name`][res-attr-cfg]	Toggles the `azure.vm.scaleset.name` resource attribute. Sets `enabled` to `true` by default.	no
[`azure.vm.size`][res-attr-cfg]	Toggles the `azure.vm.size` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `false` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

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

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

Attribute	Type	Description	Default	Required
`address`	`string`	The address of the Consul server	`""`	no
`datacenter`	`string`	Data center to use. If not provided, the default agent data center is used.	`""`	no
`meta`	`list(string)`	Allowlist of Consul Metadata keys to use as resource attributes.	`[]`	no
`namespace`	`string`	The name of the namespace to send along for the request.	`""`	no
`token`	`secret`	A per-request ACL token which overrides the Consul agent’s default (empty) token.	`""`	no

token is only required if the Consul ACL System is enabled.

The consul block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`consul` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`digitalocean`

The digitalocean block queries the DigitalOcean instance metadata API to retrieve various resource attributes from the DigitalOcean cloud environment.

The digitalocean block supports the following attributes:

Attribute	Type	Description	Default	Required
`resource_attributes`	[`resource_attributes`][res-attr-cfg]	Configures which resource attributes to add.		no

`digitalocean` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.provider: "digitalocean"

`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 doesn’t work on MacOS.

The docker block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`docker` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`os.type`][res-attr-cfg]	Toggles the `os.type` resource attribute. Sets `enabled` to `true` by default.	no

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

Attribute	Type	Description	Default	Required
`max_attempts`	`int`	The maximum number of attempts to retrieve metadata.	`3`	no
`max_backoff`	`duration`	The maximum backoff time between retries.	`"20s"`	no
`tags_from_imds`	`bool`	Fetch instance tags through IMDS instead of the EC2 `DescribeTags` API.	`false`	no
`tags`	`list(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:

Block	Description	Required
``	Configures which resource attributes to add.	no

`ec2` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.image.id`][res-attr-cfg]	Toggles the `host.image.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.type`][res-attr-cfg]	Toggles 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:

Block	Description	Required
resource_attr`ibutes	Configures which resource attributes to add.	no

`ecs` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`aws.ecs.cluster.arn`][res-attr-cfg]	Toggles the `aws.ecs.cluster.arn` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.ecs.launchtype`][res-attr-cfg]	Toggles the `aws.ecs.launchtype` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.ecs.task.arn`][res-attr-cfg]	Toggles the `aws.ecs.task.arn` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.ecs.task.family`][res-attr-cfg]	Toggles the `aws.ecs.task.family` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.ecs.task.id`][res-attr-cfg]	Toggles the `aws.ecs.task.id` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.ecs.task.revision`][res-attr-cfg]	Toggles the `aws.ecs.task.revision` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.log.group.arns`][res-attr-cfg]	Toggles the `aws.log.group.arns` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.log.group.names`][res-attr-cfg]	Toggles the `aws.log.group.names` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.log.stream.arns`][res-attr-cfg]	Toggles the `aws.log.stream.arns` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.log.stream.names`][res-attr-cfg]	Toggles the `aws.log.stream.names` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles 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 attributes:

Attribute	Type	Description	Default	Required
`node_from_env_var`	`string`	The environment variable that contains the node name.	`"K8S_NODE_NAME"`	no

The eks block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`eks` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `false` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`k8s.cluster.name`][res-attr-cfg]	Toggles 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:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`elasticbeanstalk` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`deployment.envir`][res-attr-cfg]	Toggles the `deployment.envir` resource attribute. Sets `enabled` to `true` by default.	no
[`service.instance`][res-attr-cfg]	Toggles the `service.instance` resource attribute. Sets `enabled` to `true` by default.	no
[`service.version`][res-attr-cfg]	Toggles the `service.version` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

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

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

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`gcp` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`faas.instance`][res-attr-cfg]	Toggles the `faas.instance` resource attribute. Sets `enabled` to `true` by default.	no
[`faas.id`][res-attr-cfg]	Deprecated. Removed upstream and has no effect.	no
[`faas.name`][res-attr-cfg]	Toggles the `faas.name` resource attribute. Sets `enabled` to `true` by default.	no
[`faas.version`][res-attr-cfg]	Toggles the `faas.version` resource attribute. Sets `enabled` to `true` by default.	no
[`gcp.cloud_run.job.execution`][res-attr-cfg]	Toggles the `gcp.cloud_run.job.execution` resource attribute. Sets `enabled` to `true` by default.	no
[`gcp.cloud_run.job.task_index`][res-attr-cfg]	Toggles the `gcp.cloud_run.job.task_index` resource attribute. Sets `enabled` to `true` by default.	no
[`gcp.gce.instance.group_manager.name`][res-attr-cfg]	Toggles the `gcp.gce.instance.group_manager.name` resource attribute. Sets `enabled` to `true` by default.	no
[`gcp.gce.instance.group_manager.region`][res-attr-cfg]	Toggles the `gcp.gce.instance.group_manager.region` resource attribute. Sets `enabled` to `true` by default.	no
[`gcp.gce.instance.group_manager.zone`][res-attr-cfg]	Toggles the `gcp.gce.instance.group_manager.zone` resource attribute. Sets `enabled` to `true` by default.	no
[`gcp.gce.instance.hostname`][res-attr-cfg]	Toggles the `gcp.gce.instance.hostname` resource attribute. Sets `enabled` to `false` by default.	no
[`gcp.gce.instance.name`][res-attr-cfg]	Toggles the `gcp.gce.instance.name` resource attribute. Sets `enabled` to `false` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.type`][res-attr-cfg]	Toggles the `host.type` resource attribute. Sets `enabled` to `true` by default.	no
[`k8s.cluster.name`][res-attr-cfg]	Toggles 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: For example, "us-central1"
cloud.availability_zone: For example, "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
gcp.gce.instance.group_manager.name: Managed instance group name
gcp.gce.instance.group_manager.region: Managed instance group region
gcp.gce.instance.group_manager.zone: Managed instance group zone

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, for example "us-central1"
cloud.availability_zone: only for zonal GKE clusters, for example, "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: For example, "us-central1"
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: For example, "us-central1"
faas.name: Service name
gcp.cloud_run.job.execution: For example, "my-service-ajg89"
gcp.cloud_run.job.task_index: For example, "0"

Google Cloud Functions metadata

cloud.provider: "gcp"
cloud.platform: "gcp_cloud_functions"
cloud.account.id: Project ID
cloud.region: For example, "us-central1"
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: For example, "us-central1"
cloud.availability_zone: For example, "us-central1-c"
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:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`heroku` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`heroku.app.id`][res-attr-cfg]	Toggles the `heroku.app.id` resource attribute. Sets `enabled` to `true` by default.	no
[`heroku.dyno.id`][res-attr-cfg]	Toggles the `heroku.dyno.id` resource attribute. Sets `enabled` to `true` by default.	no
[`heroku.release.commit`][res-attr-cfg]	Toggles the `heroku.release.commit` resource attribute. Sets `enabled` to `true` by default.	no
[`heroku.release.creation_timestamp`][res-attr-cfg]	Toggles the `heroku.release.creation_timestamp` resource attribute. Sets `enabled` to `true` by default.	no
[`service.instance.id`][res-attr-cfg]	Toggles the `service.instance.id` resource attribute. Sets `enabled` to `true` by default.	no
[`service.name`][res-attr-cfg]	Toggles the `service.name` resource attribute. Sets `enabled` to `true` by default.	no
[`service.version`][res-attr-cfg]	Toggles 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. These environment variables map 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, refer to the Heroku cloud provider documentation under the OpenTelemetry specification semantic conventions.

`hetzner`

The hetzner block queries the Hetzner cloud instance metadata API to retrieve various resource attributes from the Hetzner cloud environment.

The hetzner block supports the following attributes:

Attribute	Type	Description	Default	Required
`resource_attributes`	[`resource_attributes`][res-attr-cfg]	Configures which resource attributes to add.		no

`hetzner` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.provider: "hetzner"

`kubeadm`

The kubeadm block queries the Kubernetes API server to retrieve kubeadm resource attributes.

The kubeadm block supports the following attributes:

Attribute	Type	Description	Default	Required
`auth_type`	`string`	Configures how to authenticate to the Kubernetes API server.	`"none"`	no
`context`	`string`	Override the current context when `auth_type` is set to `"kubeConfig"`.	`""`	no

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"]
---
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

You can set auth_type 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 kubeadm block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`kubeadm` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`k8s.cluster.name`][res-attr-cfg]	Toggles the `k8s.cluster.name` resource attribute. Sets `enabled` to `true` by default.	no
[`k8s.cluster.uid`][res-attr-cfg]	Toggles the `k8s.cluster.uid` 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:

Attribute	Type	Description	Default	Required
`auth_type`	`string`	Configures how to authenticate to the K8s API server.	`"none"`	no
`context`	`string`	Override the current context when `auth_type` is set to `"kubeConfig"`.	`""`	no
`node_from_env_var`	`string`	The environment variable that contains the node name.	`"K8S_NODE_NAME"`	no

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

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:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`kubernetes_node` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`k8s.node.name`][res-attr-cfg]	Toggles the `k8s.node.name` resource attribute. Sets `enabled` to `true` by default.	no
[`k8s.node.uid`][res-attr-cfg]	Toggles the `k8s.node.uid` resource attribute. Sets `enabled` to `true` by default.	no

`lambda`

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

The lambda block supports the following blocks:

Block	Description	Required
resource_attri`butes	Configures which resource attributes to add.	no

`lambda` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`aws.log.group.names`][res-attr-cfg]	Toggles the `aws.log.group.names` resource attribute. Sets `enabled` to `true` by default.	no
[`aws.log.stream.names`][res-attr-cfg]	Toggles the `aws.log.stream.names` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`faas.instance`][res-attr-cfg]	Toggles the `faas.instance` resource attribute. Sets `enabled` to `true` by default.	no
[`faas.max_memory`][res-attr-cfg]	Toggles the `faas.max_memory` resource attribute. Sets `enabled` to `true` by default.	no
[`faas.name`][res-attr-cfg]	Toggles the `faas.name` resource attribute. Sets `enabled` to `true` by default.	no
[`faas.version`][res-attr-cfg]	Toggles 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

`nova`

The nova block queries the OpenStack Nova instance metadata API to retrieve various resource attributes from the OpenStack environment.

The nova block supports the following attributes:

Attribute	Type	Description	Default	Required
`fail_on_missing_metadata`	`bool`	Whether to fail if metadata is missing.	`false`	no
`labels`	`list(string)`	A list of regular expressions to match against OpenStack Nova instance metadata keys (from the “meta” map) to add as resource attributes.	`[]`	no

The nova block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`nova` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.type`][res-attr-cfg]	Toggles the `host.type` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.platform: "openstack"
cloud.provider: "openstack_nova"

`oraclecloud`

The oraclecloud block queries the Oracle Cloud Infrastructure (OCI) instance metadata service to retrieve various resource attributes from the Oracle Cloud environment.

The oraclecloud block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`oraclecloud` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.type`][res-attr-cfg]	Toggles the `host.type` resource attribute. Sets `enabled` to `true` by default.	no
[`k8s.cluster.name`][res-attr-cfg]	Toggles the `k8s.cluster.name` resource attribute. Sets `enabled` to `true` by default.	no
[`oracle_cloud.realm`][res-attr-cfg]	Toggles the `oracle_cloud.realm` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.platform: "oracle_cloud_infrastructure"
cloud.provider: "oraclecloud"
oracle_cloud.realm: For example, "oc1"

`tencent_cvm`

The tencent_cvm block queries the Tencent Cloud CVM metadata service to retrieve resource attributes.

The tencent_cvm block supports the following attributes:

Attribute	Type	Description	Default	Required
`fail_on_missing_metadata`	`bool`	Whether to fail if the metadata endpoint is unavailable or required fields are missing.	`false`	no

The tencent_cvm block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`tencent_cvm` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.image.id`][res-attr-cfg]	Toggles the `host.image.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.type`][res-attr-cfg]	Toggles the `host.type` resource attribute. Sets `enabled` to `true` by default.	no

`alibaba_ecs`

The alibaba_ecs block queries the Alibaba Cloud ECS metadata service to retrieve resource attributes.

The alibaba_ecs block supports the following attributes:

Attribute	Type	Description	Default	Required
`fail_on_missing_metadata`	`bool`	Whether to fail if the metadata endpoint is unavailable or required fields are missing.	`false`	no

The alibaba_ecs block supports the following blocks:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`alibaba_ecs` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.image.id`][res-attr-cfg]	Toggles the `host.image.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.type`][res-attr-cfg]	Toggles the `host.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:

Attribute	Type	Description	Default	Required
`address`	`string`	Address of the OpenShift API server.	See below	no
`token`	`string`	Token used to identify against the OpenShift API server.	""	no

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

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 isn’t 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:

Block	Description	Required
`tls`	TLS settings for the connection with the OpenShift API.	yes
`resource_attributes`	Configures which resource attributes to add.	no

`openshift` > `tls`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`insecure_skip_verify`	`boolean`	Ignores insecure server TLS certificates.		no
`insecure`	`boolean`	Disables TLS when connecting to the configured server.		no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no
`server_name`	`string`	Verifies 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 you set reload_interval 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. Refer to the Go TLS documentation for a list of supported cipher suites.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

`openshift` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`k8s.cluster.name`][res-attr-cfg]	Toggles the `k8s.cluster.name` resource attribute. Sets `enabled` to `true` by default.	no

`scaleway`

The scaleway block queries the Scaleway instance metadata API to retrieve various resource attributes from the Scaleway cloud environment.

The scaleway block supports the following attributes:

Attribute	Type	Description	Default	Required
`resource_attributes`	[`resource_attributes`][res-attr-cfg]	Configures which resource attributes to add.		no

`scaleway` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.account.id`][res-attr-cfg]	Toggles the `cloud.account.id` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.availability_zone`][res-attr-cfg]	Toggles the `cloud.availability_zone` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.platform`][res-attr-cfg]	Toggles the `cloud.platform` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.image.id`][res-attr-cfg]	Toggles the `host.image.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.image.name`][res-attr-cfg]	Toggles the `host.image.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`host.type`][res-attr-cfg]	Toggles the `host.type` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.platform: "scaleway_cloud_compute"
cloud.provider: "scaleway_cloud"

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

Attribute	Type	Description	Default	Required
`hostname_sources`	`list(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. First, it looks up the host name in the local machine’s hosts file. If that fails, it looks up the CNAME. If the CNAME lookup fails, it does a reverse DNS query. This hostname source may produce unreliable results on Windows. To produce a FQDN, Windows hosts might have better results using the “lookup” hostname source.
"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. This hostname source may produce unreliable results on Windows.
"lookup": Does a reverse DNS lookup of the current host’s IP address.

If there is an error 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:

Block	Description	Required
`resource_attributes`	Configures which resource attributes to add.	no

`system` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`host.arch`][res-attr-cfg]	Toggles the `host.arch` resource attribute. Sets `enabled` to `false` by default.	no
[`host.cpu.cache.l2.size`][res-attr-cfg]	Toggles the `host.cpu.cache.l2.size` resource attribute. Sets `enabled` to `false` by default.	no
[`host.cpu.family`][res-attr-cfg]	Toggles the `host.cpu.family` resource attribute. Sets `enabled` to `false` by default.	no
[`host.cpu.model.id`][res-attr-cfg]	Toggles the `host.cpu.model.id` resource attribute. Sets `enabled` to `false` by default.	no
[`host.cpu.model.name`][res-attr-cfg]	Toggles the `host.cpu.model.name` resource attribute. Sets `enabled` to `false` by default.	no
[`host.cpu.stepping`][res-attr-cfg]	Toggles the `host.cpu.stepping` resource attribute. Sets `enabled` to `false` by default.	no
[`host.cpu.vendor.id`][res-attr-cfg]	Toggles the `host.cpu.vendor.id` resource attribute. Sets `enabled` to `false` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `false` by default.	no
[`host.interface`][res-attr-cfg]	Toggles the `host.interface` resource attribute. Sets `enabled` to `false` by default.	no
[`host.ip`][res-attr-cfg]	Toggles the `host.ip` resource attribute. Sets `enabled` to `false` by default.	no
[`host.mac`][res-attr-cfg]	Toggles the `host.mac` resource attribute. Sets `enabled` to `false` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no
[`os.build.id`][res-attr-cfg]	Toggles the `os.build.id` resource attribute. Sets `enabled` to `false` by default.	no
[`os.description`][res-attr-cfg]	Toggles the `os.description` resource attribute. Sets `enabled` to `false` by default.	no
[`os.name`][res-attr-cfg]	Toggles the `os.name` resource attribute. Sets `enabled` to `false` by default.	no
[`os.type`][res-attr-cfg]	Toggles the `os.type` resource attribute. Sets `enabled` to `true` by default.	no
[`os.version`][res-attr-cfg]	Toggles the `os.version` resource attribute. Sets `enabled` to `false` by default.	no

`upcloud`

The upcloud block queries the UpCloud instance metadata API to retrieve various resource attributes from the UpCloud environment.

The upcloud block supports the following attributes:

Attribute	Type	Description	Default	Required
`fail_on_missing_metadata`	`bool`	Whether to fail if metadata cannot be retrieved from the UpCloud metadata API.	`false`	no
`resource_attributes`	[`resource_attributes`][res-attr-cfg]	Configures which resource attributes to add.		no

`upcloud` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.provider: "upcloud"

`vultr`

The vultr block queries the Vultr instance metadata API to retrieve various resource attributes from the Vultr cloud environment.

The vultr block supports the following attributes:

Attribute	Type	Description	Default	Required
`fail_on_missing_metadata`	`bool`	Whether to fail if metadata cannot be retrieved from the Vultr metadata API.	`false`	no
`resource_attributes`	[`resource_attributes`][res-attr-cfg]	Configures which resource attributes to add.		no

`vultr` > `resource_attributes`

The resource_attributes block supports the following blocks:

Block	Description	Required
[`cloud.provider`][res-attr-cfg]	Toggles the `cloud.provider` resource attribute. Sets `enabled` to `true` by default.	no
[`cloud.region`][res-attr-cfg]	Toggles the `cloud.region` resource attribute. Sets `enabled` to `true` by default.	no
[`host.id`][res-attr-cfg]	Toggles the `host.id` resource attribute. Sets `enabled` to `true` by default.	no
[`host.name`][res-attr-cfg]	Toggles the `host.name` resource attribute. Sets `enabled` to `true` by default.	no

Example values:

cloud.provider: "vultr"

Common configuration

Resource attribute configuration

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:

Attribute	Type	Description	Default	Required
`enabled`	`bool`	Toggles whether to add the resource attribute to the span, log, or metric resource.	See below	no

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:

Name	Type	Description
`input`	`otelcol.Consumer`	A 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.

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

  output {
    logs    = [otelcol.exporter.otlphttp.default.input]
    metrics = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.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][ec2].

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

  output {
    logs    = [otelcol.exporter.otlphttp.default.input]
    metrics = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.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][ec2].

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

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

`ec2` with explicit resource attributes

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.otlphttp.default.input]
    metrics = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}

`kubernetes_node` with a default 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][kubernetes_node].

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

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

You need to add this to your workload:

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.

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

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

You need to add this to your workload:

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

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.span

Mon, 13 Apr 2026 07:37:47 +0000

otelcol.processor.span

otelcol.processor.span accepts traces telemetry data from other otelcol components and modifies the names and attributes of the spans. It also supports the ability to filter input data to determine if it should be included or excluded from this processor.

Note
otelcol.processor.span is a wrapper over the upstream OpenTelemetry Collector span processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.span "<LABEL>" {
  output {
    traces  = [...]
  }
}

Arguments

The otelcol.processor.span component doesn’t support any arguments. You can configure this component with blocks.

Blocks

You can use the following blocks with otelcol.processor.span:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

If both an include block and an excludeblock are specified, the include properties are checked before the exclude properties.

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`traces`	`list(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 traces argument accordingly to send telemetry data to other components.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`exclude`

The exclude block provides an option to exclude data from being fed into the [name][name] and [status][status] blocks based on the properties of a span.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_type`	`string`	Controls how items to match against are interpreted.		yes
`services`	`list(string)`	A list of items to match the service name against.	`[]`	no
`span_kinds`	`list(string)`	A list of items to match the span kind against.	`[]`	no
`span_names`	`list(string)`	A list of items to match the span name against.	`[]`	no

match_type is required and must be set to either "regexp" or "strict".

A match occurs if at least one item in the lists matches.

One of services, span_names, span_kinds, [attribute][attribute], [resource][resource], or [library][library] must be specified with a non-empty value for a valid configuration.

`attribute`

This block specifies an attribute to match against:

You can define more than one attribute block.
Only match_type = "strict" is allowed if attribute is specified.
All attribute blocks must match exactly for a match to occur.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	The attribute key.		yes
`value`	`any`	The attribute value to match against.		no

If value isn’t set, any value matches. The type of value could be a number, a string, or a boolean.

`library`

This block specifies properties to match the implementation library against:

More than one library block can be defined.
A match occurs if the span’s implementation library matches at least one library block.

The following arguments are supported:

Name	Type	Description	Default	Required
`name`	`string`	The attribute key.		yes
`version`	`string`	The version to match against.	null	no

If version is unset, any version matches. If you set version to an empty string, it only matches a library version, which is also an empty string.

`regexp`

This block is an optional configuration for the match_type of "regexp". It configures a Least Recently Used (LRU) cache.

The following arguments are supported:

Name	Type	Description	Default	Required
`cache_enabled`	`bool`	Determines whether match results are LRU cached.	`false`	no
`cache_max_num_entries`	`int`	The max number of entries of the LRU cache that stores match results.	`0`	no

Enabling cache_enabled could make subsequent matches faster. Cache size is unlimited unless cache_max_num_entries is also specified.

cache_max_num_entries is ignored if cache_enabled is false.

`resource`

This block specifies items to match the resources against:

More than one resource block can be defined.
A match occurs if the input data resources match at least one resource block.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	The resource key.		yes
`value`	`any`	The resource value to match against.		no

If value isn’t set, any value matches. The type of value could be a number, a string, or a boolean.

`include`

The include block provides an option to include data being fed into the [name][name] and [status][status] blocks based on the properties of a span.

The following arguments are supported:

Name	Type	Description	Default	Required
`match_type`	`string`	Controls how items to match against are interpreted.		yes
`services`	`list(string)`	A list of items to match the service name against.	`[]`	no
`span_kinds`	`list(string)`	A list of items to match the span kind against.	`[]`	no
`span_names`	`list(string)`	A list of items to match the span name against.	`[]`	no

match_type is required and must be set to either "regexp" or "strict".

A match occurs if at least one item in the lists matches.

One of services, span_names, span_kinds, [attribute][attribute], [resource][resource], or [library][library] must be specified with a non-empty value for a valid configuration.

`name`

The name block configures how to rename a span and add attributes.

The following attributes are supported:

Name	Type	Description	Default	Required
`from_attributes`	`list(string)`	Attribute keys to pull values from, to generate a new span name.	`[]`	no
`separator`	`string`	Separates attributes values in the new span name.	`""`	no

Firstly from_attributes rules are applied, then [to-attributes][to-attributes] are applied. At least one of these 2 fields must be set.

from_attributes represents the attribute keys to pull the values from to generate the new span name:

All attribute keys are required in the span to rename a span. If any attribute is missing from the span, no rename will occur.
The new span name is constructed in order of the from_attributes specified in the configuration.

separator is the string used to separate attributes values in the new span name. If no value is set, no separator is used between attribute values. separator is used with from_attributes only. It’s not used with [to-attributes][to-attributes].

`to_attributes`

The to_attributes block configures how to create attributes from a span name.

The following attributes are supported:

Name	Type	Description	Default	Required
`rules`	`list(string)`	A list of regular expression rules to extract attribute values from span name.		yes
`break_after_match`	`bool`	Configures if processing of rules should stop after the first match.	`false`	no
`keep_original_name`	`bool`	Configures if the original span name should be kept after processing the rules.	`false`	no

Each rule in the rules list is a regular expression pattern string.

The span name is checked against each regular expression in the list.
If it matches, then all named subexpressions of the regular expression are extracted as attributes and are added to the span.
Each subexpression name becomes an attribute name and the subexpression matched portion becomes the attribute value.
The matched portion in the span name is replaced by extracted attribute name.
If the attributes already exist in the span then they will be overwritten.
The process is repeated for all rules in the order they’re specified.
Each subsequent rule works on the span name that’s the output after processing the previous rule.

break_after_match specifies if processing of rules should stop after the first match. If it’s false, rule processing will continue to be performed over the modified span name.

If keep_original_name is true, the original span name is kept. If it’s false, the span name is replaced with the placeholders of the captured attributes.

`status`

The status block specifies a status which should be set for this span.

The following attributes are supported:

Name	Type	Description	Default	Required
`code`	`string`	A status code.		yes
`description`	`string`	An optional field documenting Error status codes.	`""`	no

The supported values for code are:

Ok
Error
Unset

description should only be specified if code is set to Error.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer OTLP-formatted data for traces telemetry signals. Logs and metrics aren’t supported.

Component health

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

Debug information

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

Examples

Create a new span name from attribute values

This example creates a new span name from the values of attributes db.svc, operation, and id, in that order, separated by the value ::. All attribute keys need to be specified in the span for the processor to rename it.

otelcol.processor.span "default" {
  name {
    separator        = "::"
    from_attributes  = ["db.svc", "operation", "id"]
  }

  output {
      traces = [otelcol.exporter.otlphttp.default.input]
  }
}

For a span with the following attributes key/value pairs, the above configuration changes the span name to "location::get::1234":

{
  "db.svc": "location",
  "operation": "get",
  "id": "1234"
}

For a span with the following attributes key/value pairs, the above configuration won’t change the span name. This is because the attribute key operation isn’t set:

{
  "db.svc": "location",
  "id": "1234"
}

Create a new span name from attribute values (no separator)

otelcol.processor.span "default" {
  name {
    from_attributes = ["db.svc", "operation", "id"]
  }

  output {
      traces = [otelcol.exporter.otlphttp.default.input]
  }
}

For a span with the following attributes key/value pairs, the above configuration changes the span name to "locationget1234":

{
  "db.svc": "location",
  "operation": "get",
  "id": "1234"
}

Rename a span name and adding attributes

Example input and output using the configuration below:

Assume the input span name is /api/v1/document/12345678/update
The span name will be changed to /api/v1/document/{documentId}/update
A new attribute "documentId"="12345678" will be added to the span.

otelcol.processor.span "default" {
  name {
    to_attributes {
      rules = ["^\\/api\\/v1\\/document\\/(?P<documentId>.*)\\/update$"]
    }
  }

  output {
      traces = [otelcol.exporter.otlphttp.default.input]
  }
}

Keep the original span name

This example adds the same new "documentId"="12345678" attribute as the previous example. However, the span name is unchanged (/api/v1/document/12345678/update).

otelcol.processor.span "keep_original_name" {
  name {
    to_attributes {
      keep_original_name = true
      rules = [`^\/api\/v1\/document\/(?P<documentId>.*)\/update$`]
    }
  }

  output {
      traces = [otelcol.exporter.otlphttp.default.input]
  }
}

Filtering, renaming a span name and adding attributes

This example renames the span name to {operation_website} and adds the attribute {Key: operation_website, Value: <old span name> } if the span has the following properties:

Service name contains the word banks.
The span name contains / anywhere in the string.
The span name isn’t donot/change.

otelcol.processor.span "default" {
  include {
    match_type = "regexp"
    services   = ["banks"]
    span_names = ["^(.*?)/(.*?)$"]
  }
  exclude {
    match_type = "strict"
    span_names = ["donot/change"]
  }
  name {
    to_attributes {
      rules = ["(?P<operation_website>.*?)$"]
    }
  }

  output {
      traces = [otelcol.exporter.otlphttp.default.input]
  }
}

Set a status

This example changes the status of a span to “Error” and sets an error description.

otelcol.processor.span "default" {
  status {
    code        = "Error"
    description = "some additional error description"
  }

  output {
      traces = [otelcol.exporter.otlphttp.default.input]
  }
}

Set a status depending on an attribute value

This example sets the status to success only when attribute http.status_code is equal to 400.

otelcol.processor.span "default" {
  include {
    match_type = "strict"
    attribute {
      key   = "http.status_code"
      value = 400
    }
  }
  status {
    code = "Ok"
  }

  output {
      traces = [otelcol.exporter.otlphttp.default.input]
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.tail_sampling

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.tail_sampling`

otelcol.processor.tail_sampling samples traces based on a set of defined policies. All spans for a given trace must be received by the same collector instance for effective sampling decisions.

Note
otelcol.processor.tail_sampling is a wrapper over the upstream OpenTelemetry Collector Contrib tail_sampling processor. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

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

Usage

otelcol.processor.tail_sampling "<LABEL>" {
  policy {
    ...
  }
  ...

  output {
    traces  = [...]
  }
}

Arguments

You can use the following arguments with otelcol.processor.tail_sampling:

Name	Type	Description	Default	Required
`decision_wait`	`duration`	Wait time since the first span of a trace before making a sampling decision.	`"30s"`	no
`decision_wait_after_root_received`	`duration`	Wait time since receiving the root span before making a sampling decision.	`"0s"`	no
`num_traces`	`int`	Number of traces kept in memory.	`50000`	no
`block_on_overflow`	`boolean`	If `true`, wait for space when the `num_traces` limit is reached. If `false`, old traces will be evicted to make space.	`false`	no
`expected_new_traces_per_sec`	`int`	Expected number of new traces (helps in allocating data structures).	`0`	no
`sample_on_first_match`	`boolean`	Make a sampling decision as soon as any policy matches.	`false`	no
`drop_pending_traces_on_shutdown`	`boolean`	Drop pending traces on shutdown instead of deciding with partial data.	`false`	no
`maximum_trace_size_bytes`	`int`	Drop traces early when they exceed this size in bytes. `0` disables early dropping.	`0`	no
`decision_cache`	`object`	Configures caches for sampling decisions.	`{}`	no

decision_wait determines the number of batches to maintain on a channel. Its value must convert to a number of seconds greater than zero.

num_traces determines the buffer size of the trace delete channel which is composed of trace IDs. Increasing the number will increase the memory usage of the component while decreasing the number will lower the maximum amount of traces kept in memory.

expected_new_traces_per_sec determines the initial slice sizing of the current batch. A larger number will use more memory but be more efficient when adding traces to the batch.

If sample_on_first_match is true, the component makes a decision as soon as one policy matches.

If drop_pending_traces_on_shutdown is true, the component drops traces that are still waiting for decision_wait when shutdown starts.

If decision_wait_after_root_received is greater than 0, the component can decide relative to root-span arrival time.

If maximum_trace_size_bytes is greater than 0, traces over this size are dropped before decision wait to limit memory usage.

decision_cache can contain two keys:

sampled_cache_size: Configures the number of trace IDs to be kept in an LRU cache, persisting the “keep” decisions for traces that may have already been released from memory. By default, the size is 0 and the cache is inactive.
non_sampled_cache_size: Configures the number of trace IDs to be kept in an LRU cache, persisting the “drop” decisions for traces that may have already been released from memory. By default, the size is 0 and the cache is inactive.

You may want to vary the size of the decision_cache depending on how many “keep” vs “drop” decisions you expect from your policies. For example, you can allocate a larger non_sampled_cache_size if you expect most traces to be dropped. Additionally, when you use decision_cache, configure it with a much higher value than num_traces so decisions for trace IDs are kept longer than the span data for the trace.

Blocks

You can use the following blocks with otelcol.processor.tail_sampling:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`policy`

Required

The policy block configures a sampling policy used by the component. At least one policy block is required.

The following arguments are supported:

Name	Type	Description	Default	Required
`name`	`string`	The custom name given to the policy.		yes
`type`	`string`	The valid policy type for this policy.		yes

Supported type values include: always_sample, latency, numeric_attribute, probabilistic, status_code, string_attribute, rate_limiting, bytes_limiting, span_count, trace_state, boolean_attribute, ottl_condition, trace_flags, and, not, drop, and composite.

Each policy results in a decision, and the processor evaluates them to make a final decision:

When there’s a “drop” decision, the trace isn’t sampled.
When there’s an “inverted not sample” decision, the trace isn’t sampled. Deprecated
When there’s a “sample” decision, the trace is sampled.
When there’s an “inverted sample” decision and no “not sample” decisions, the trace is sampled. Deprecated
In all other cases, the trace isn’t sampled.

An “inverted” decision is the one made based on the invert_match attribute, such as the one from the string, numeric or boolean tag policy. There is an exception to this if the policy is within an and or composite policy, the resulting decision will be either sampled or not sampled. The “inverted” decisions have been deprecated, please make use of drop policy to explicitly not sample select traces.

`boolean_attribute`

The boolean_attribute block configures a policy of type boolean_attribute. The policy samples based on a boolean attribute (resource and record).

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	Attribute key to match against.		yes
`value`	`bool`	The boolean value, `true` or `false`, to use when matching against attribute values.		yes
`invert_match`	`bool`	Indicates that values must not match against attribute values.	`false`	no

`latency`

The latency block configures a policy of type latency. The policy samples based on the duration of the trace. The duration is determined by looking at the earliest start time and latest end time, without taking into consideration what happened in between.

The following arguments are supported:

Name	Type	Description	Default	Required
`threshold_ms`	`number`	Lower latency threshold for sampling, in milliseconds.		yes
`upper_threshold_ms`	`number`	Upper latency threshold for sampling, in milliseconds.	`0`	no

For a trace to be sampled, its latency should be greater than threshold_ms and lower than or equal to upper_threshold_ms.

An upper_threshold_ms of 0 results in a policy which samples anything greater than threshold_ms.

`numeric_attribute`

The numeric_attribute block configures a policy of type numeric_attribute. The policy samples based on number attributes (resource and record).

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	Tag that the filter is matched against.		yes
`min_value`	`number`	The minimum value of the attribute to be considered a match.		yes
`max_value`	`number`	The maximum value of the attribute to be considered a match.		yes
`invert_match`	`bool`	Indicates that values must not match against attribute values.	`false`	no

`ottl_condition`

The ottl_condition block configures a policy of type ottl_condition. The policy samples based on a given boolean OTTL condition (span and span event).

The following arguments are supported:

Name	Type	Description	Default	Required
`error_mode`	`string`	Error handling if OTTL conditions fail to evaluate.		yes
`span`	`list(string)`	OTTL conditions for spans.	`[]`	no
`spanevent`	`list(string)`	OTTL conditions for span events.	`[]`	no

The supported values for error_mode are:

ignore: Ignore errors returned by conditions, log them, and continue on to the next condition. This is the recommended mode.
silent: Ignore errors returned by conditions, don’t log them, and continue on to the next condition.
propagate: Return the error up the pipeline. This results in the payload being dropped from Alloy.

At least one of span or spanevent should be specified. Both span and spanevent can also be specified.

`probabilistic`

The probabilistic block configures a policy of type probabilistic. The policy samples a percentage of traces.

The following arguments are supported:

Name	Type	Description	Default	Required
`sampling_percentage`	`number`	The percentage rate at which traces are sampled.		yes
`hash_salt`	`string`	See below.		no

Use hash_salt to configure the hashing salts. This is important in scenarios where multiple layers of collectors have different sampling rates. If multiple collectors use the same salt with different sampling rates, passing one layer may pass the other even if the collectors have different sampling rates. Configuring different salts avoids that.

`rate_limiting`

The rate_limiting block configures a policy of type rate_limiting. The policy samples based on rate.

The following arguments are supported:

Name	Type	Description	Default	Required
`spans_per_second`	`number`	Sets the maximum number of spans that can be processed each second.		yes

`bytes_limiting`

The bytes_limiting block configures a policy of type bytes_limiting. The policy samples based on the rate of bytes per second using a token bucket algorithm.

The following arguments are supported:

Name	Type	Description	Default	Required
`bytes_per_second`	`number`	Sets the sustained byte throughput limit.		yes
`burst_capacity`	`number`	Sets the maximum burst size in bytes. If omitted, it defaults to `2 * bytes_per_second` in the upstream policy.	`0`	no

`span_count`

The span_count block configures a policy of type span_count. The policy samples based on the minimum number of spans within a batch. If all traces within the batch have fewer spans than the threshold, the batch isn’t sampled.

The following arguments are supported:

Name	Type	Description	Default	Required
`min_spans`	`number`	Minimum number of spans in a trace.		yes
`max_spans`	`number`	Maximum number of spans in a trace.	`0`	no

Set max_spans to 0, if you don’t want to limit the policy samples based on the maximum number of spans in a trace.

`status_code`

The status_code block configures a policy of type status_code. The policy samples based upon the status code.

The following arguments are supported:

Name	Type	Description	Default	Required
`status_codes`	`list(string)`	Holds the configurable settings to create a status code filter sampling policy evaluator.		yes

status_codes values must be "OK", "ERROR", or "UNSET".

`string_attribute`

The string_attribute block configures a policy of type string_attribute. The policy samples based on string attributes (resource and record) value matches. Both exact and regular expression value matches are supported.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	Tag that the filter is matched against.		yes
`values`	`list(string)`	Set of values or regular expressions to use when matching against attribute values.		yes
`enabled_regex_matching`	`bool`	Determines whether to match attribute values by regular expression string.	`false`	no
`cache_max_size`	`string`	The maximum number of attribute entries of Least Recently Used (LRU) Cache that stores the matched result from the regular expressions defined in `values.`		no
`invert_match`	`bool`	Indicates that values or regular expressions must not match against attribute values.	`false`	no

`trace_state`

The trace_state block configures a policy of type trace_state. The policy samples based on TraceState value matches.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`string`	Tag that the filter is matched against.		yes
`values`	`list(string)`	Set of values to use when matching against `trace_state` values.		yes

`not`

The not block configures a policy of type not. This policy inverts the decision of a nested not_sub_policy.

`not_sub_policy`

The not_sub_policy block configures a sampling policy used by the not block. Exactly one not_sub_policy block is required inside a not block.

The following arguments are supported:

Name	Type	Description	Default	Required
`name`	`string`	The custom name given to the policy.		yes
`type`	`string`	The valid policy type for this policy.		yes

`and`

The and block configures a policy of type and. The policy samples based on multiple policies by creating an and policy.

`and_sub_policy`

The and_sub_policy block configures a sampling policy used by the and block. At least one and_sub_policy block is required inside an and block.

The following arguments are supported:

Name	Type	Description	Default	Required
`name`	`string`	The custom name given to the policy.		yes
`type`	`string`	The valid policy type for this policy.		yes

`drop`

The drop block configures a policy of type drop. This policy drops traces when all drop_sub_policy blocks match.

`drop_sub_policy`

The drop_sub_policy block configures a sampling policy used by the drop block. At least one drop_sub_policy block is required inside a drop block.

The following arguments are supported:

Name	Type	Description	Default	Required
`name`	`string`	The custom name given to the policy.		yes
`type`	`string`	The valid policy type for this policy.		yes

`composite`

The composite block configures a policy of type composite. This policy samples based on a combination of the above samplers, with ordering and rate allocation per sampler. Rate allocation allocates certain percentages of spans per policy order. For example, if max_total_spans_per_second is set to 100, then rate_allocation is set as follows:

test-composite-policy-1 = 50% of max_total_spans_per_second = 50 spans_per_second
test-composite-policy-2 = 25% of max_total_spans_per_second = 25 spans_per_second
To ensure remaining capacity is filled, use always_sample as one of the policies.

`composite_sub_policy`

The composite_sub_policy block configures a sampling policy used by the composite block. At least onecomposite_sub_policy block is required inside a composite block.

The following arguments are supported:

Name	Type	Description	Default	Required
`name`	`string`	The custom name given to the policy.		yes
`type`	`string`	The valid policy type for this policy.		yes

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

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

Example

This example batches trace data from Alloy before sending it to [otelcol.exporter.otlphttp][] for further processing. This example shows an impractical number of policies for the purpose of demonstrating how to set up each type.

tracing {
  sampling_fraction = 1
  write_to          = [otelcol.processor.tail_sampling.default.input]
}

otelcol.processor.tail_sampling "default" {
  decision_cache = {
    sampled_cache_size     = 100000,
    non_sampled_cache_size = 100000,
    }
  decision_wait               = "10s"
  num_traces                  = 100
  expected_new_traces_per_sec = 10
  sample_on_first_match       = true
  drop_pending_traces_on_shutdown = true

  policy {
    name = "test-policy-1"
    type = "always_sample"
  }

  policy {
    name = "test-policy-2"
    type = "latency"

    latency {
      threshold_ms = 5000
    }
  }

  policy {
    name = "test-policy-3"
    type = "numeric_attribute"

    numeric_attribute {
      key       = "key1"
      min_value = 50
      max_value = 100
    }
  }

  policy {
    name = "test-policy-4"
    type = "probabilistic"

    probabilistic {
      sampling_percentage = 10
    }
  }

  policy {
    name = "test-policy-5"
    type = "status_code"

    status_code {
      status_codes = ["ERROR", "UNSET"]
    }
  }

  policy {
    name = "test-policy-6"
    type = "string_attribute"

    string_attribute {
      key    = "key2"
      values = ["value1", "value2"]
    }
  }

  policy {
    name = "test-policy-7"
    type = "string_attribute"

    string_attribute {
      key                    = "key2"
      values                 = ["value1", "val*"]
      enabled_regex_matching = true
      cache_max_size         = 10
    }
  }

  policy {
    name = "test-policy-8"
    type = "rate_limiting"

    rate_limiting {
      spans_per_second = 35
    }
  }

  policy {
    name = "test-policy-9"
    type = "bytes_limiting"

    bytes_limiting {
      bytes_per_second = 2048
      burst_capacity   = 4096
    }
  }

  policy {
    name = "test-policy-10"
    type = "string_attribute"

    string_attribute {
      key                    = "http.url"
      values                 = ["/health", "/metrics"]
      enabled_regex_matching = true
      invert_match           = true
    }
  }

  policy {
    name = "test-policy-11"
    type = "span_count"

    span_count {
      min_spans = 2
    }
  }

  policy {
    name = "test-policy-12"
    type = "trace_state"

    trace_state {
      key    = "key3"
      values = ["value1", "value2"]
    }
  }

  policy {
    name = "test-policy-13"
    type = "ottl_condition"
    ottl_condition {
      error_mode = "ignore"
      span = [
        "attributes[\"test_attr_key_1\"] == \"test_attr_val_1\"",
        "attributes[\"test_attr_key_2\"] != \"test_attr_val_1\"",
      ]
      spanevent = [
        "name != \"test_span_event_name\"",
        "attributes[\"test_event_attr_key_2\"] != \"test_event_attr_val_1\"",
      ]
    }
  }

  policy {
    name = "drop-policy-1"
    type = "drop"

    drop {
      drop_sub_policy {
        name = "test-drop-policy-1"
        type = "string_attribute"

        string_attribute {
          key                    = "url.path"
          values                 = ["/health", "/metrics"]
          enabled_regex_matching = true
        }
      }
    }
  }

  policy {
    name = "and-policy-1"
    type = "and"

    and {
      and_sub_policy {
        name = "test-and-policy-1"
        type = "numeric_attribute"

        numeric_attribute {
          key       = "key1"
          min_value = 50
          max_value = 100
        }
      }

      and_sub_policy {
        name = "test-and-policy-2"
        type = "string_attribute"

        string_attribute {
          key    = "key1"
          values = ["value1", "value2"]
        }
      }
    }
  }

  policy {
    name = "composite-policy-1"
    type = "composite"

    composite {
      max_total_spans_per_second = 1000
      policy_order               = ["test-composite-policy-1", "test-composite-policy-2", "test-composite-policy-3"]

      composite_sub_policy {
        name = "test-composite-policy-1"
        type = "numeric_attribute"

        numeric_attribute {
          key       = "key1"
          min_value = 50
          max_value = 100
        }
      }

      composite_sub_policy {
        name = "test-composite-policy-2"
        type = "string_attribute"

        string_attribute {
          key    = "key1"
          values = ["value1", "value2"]
        }
      }

      composite_sub_policy {
        name = "test-composite-policy-3"
        type = "always_sample"
      }

      rate_allocation {
        policy  = "test-composite-policy-1"
        percent = 50
      }

      rate_allocation {
        policy  = "test-composite-policy-2"
        percent = 50
      }
    }
  }

  output {
    traces = [otelcol.exporter.otlphttp.production.input]
  }
}

otelcol.exporter.otlphttp "production" {
  client {
    endpoint = sys.env("<OTLP_SERVER_ENDPOINT>")
  }
}

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.processor.transform

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.processor.transform`

otelcol.processor.transform accepts telemetry data from other otelcol components and modifies it using the OpenTelemetry Transformation Language (OTTL). OTTL statements consist of OTTL functions, which act on paths. A path is a reference to a telemetry data such as:

Resource attributes.
Instrumentation scope name.
Span attributes.

In addition to the standard OTTL functions, the processor defines its own functions to help with transformations specific to this processor.

Metrics-only functions:

Traces-only functions:

set_semconv_span_name

OTTL statements can also contain constructs such as:

Booleans:
- not true
- not IsMatch(name, "http_.*")
Boolean Expressions consisting of a where followed by one or more boolean values:
- set(attributes["whose_fault"], "ours") where attributes["http.status"] == 500
- set(attributes["whose_fault"], "theirs") where attributes["http.status"] == 400 or attributes["http.status"] == 404
Math expressions:
- 1 + 1
- end_time_unix_nano - start_time_unix_nano
- sum([1, 2, 3, 4]) + (10 / 1) - 1

Note
There are two ways of inputting strings in Alloy configuration files:

Using quotation marks (normal Alloy syntax strings). Characters such as \ and " must be escaped by preceding them with a \ character.

Using backticks (raw Alloy syntax strings). No characters must be escaped. However, it’s not possible to have backticks inside the string.

For example, the OTTL statement set(description, "Sum") where type == "Sum" can be written as:

A normal Alloy syntax string: "set(description, \"Sum\") where type == \"Sum\"".

A raw Alloy syntax string: `set(description, "Sum") where type == "Sum"`.

Raw strings are generally more convenient for writing OTTL statements.

Note
otelcol.processor.transform is a wrapper over the upstream OpenTelemetry Collector transform processor. If necessary, bug reports or feature requests will be redirected to the upstream repository.

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

Warning
otelcol.processor.transform allows you to modify all aspects of your telemetry. Some specific risks are given below, but this isn’t an exhaustive list. It’s important to understand your data before using this processor.

Unsound Transformations: Transformations between metric data types aren’t defined in the metrics data model. To use these functions, you must understand the incoming data and know that it can be meaningfully converted to a new metric data type or can be used to create new metrics.

Although OTTL allows you to use the set function with metric.data_type, its implementation in the transform processor is a no-op. To modify a data type, you must use a specific function such as convert_gauge_to_sum.

Identity Conflict: Transformation of metrics can potentially affect a metric’s identity, leading to an Identity Crisis. Be especially cautious when transforming a metric name and when reducing or changing existing attributes. Adding new attributes is safe.

Orphaned Telemetry: The processor allows you to modify span_id, trace_id, and parent_span_id for traces and span_id, and trace_id logs. Modifying these fields could lead to orphaned spans or logs.

Usage

otelcol.processor.transform "<LABEL>" {
  output {
    metrics = [...]
    logs    = [...]
    traces  = [...]
  }
}

Arguments

You can use the following argument with otelcol.processor.transform:

Name	Type	Description	Default	Required
`error_mode`	`string`	How to react to errors if they occur while processing a statement.	`"propagate"`	no

The supported values for error_mode are:

ignore: Ignore errors returned by conditions, log them, and continue on to the next condition. This is the recommended mode.
silent: Ignore errors returned by conditions, don’t log them, and continue on to the next condition.
propagate: Return the error up the pipeline. This will result in the payload being dropped from Alloy.

Blocks

You can use the following blocks with otelcol.processor.transform:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`log_statements`

The log_statements block specifies statements which transform log telemetry signals. Multiple log_statements blocks can be specified.

Name	Type	Description	Required
`context`	`string`	OTTL Context to use when interpreting the associated statements.	yes
`statements`	`list(string)`	A list of OTTL statements.	yes
`conditions`	`list(string)`	Conditions for the statements to be executed.	no
`error_mode`	`string`	How to react to errors if they occur while processing a statement.	no

The supported values for context are:

resource: Use when interacting only with OTLP resources (for example, resource attributes).
scope: Use when interacting only with OTLP instrumentation scope (for example, the name of the instrumentation scope).
log: Use when interacting only with OTLP logs.

Refer to [OTTL Context][] for more information about how to use contexts.

conditions is a list of multiple where clauses which will be processed as global conditions for the accompanying set of statements. The conditions are ORed together, which means only one condition needs to evaluate to true in order for the statements (including their individual where clauses) to be executed.

The allowed values for error_mode are the same as the ones documented in the Arguments section. If error_mode is not specified in log_statements, the top-level error_mode is applied.

`metric_statements`

The metric_statements block specifies statements which transform metric telemetry signals. Multiple metric_statements blocks can be specified.

Name	Type	Description	Required
`context`	`string`	OTTL Context to use when interpreting the associated statements.	yes
`statements`	`list(string)`	A list of OTTL statements.	yes
`conditions`	`list(string)`	Conditions for the statements to be executed.	no
`error_mode`	`string`	How to react to errors if they occur while processing a statement.	no

The supported values for context are:

resource: Use when interacting only with OTLP resources (for example, resource attributes).
scope: Use when interacting only with OTLP instrumentation scope (for example, the name of the instrumentation scope).
metric: Use when interacting only with individual OTLP metrics.
datapoint: Use when interacting only with individual OTLP metric data points.

Refer to [OTTL Context][] for more information about how to use contexts.

The allowed values for error_mode are the same as the ones documented in the Arguments section. If error_mode is not specified in metric_statements, the top-level error_mode is applied.

`statements`

The statements block specifies statements which transform logs, metrics, or traces telemetry signals. There is no context configuration argument - the context will be inferred from the statement. This inference is based on the path names, functions, and enums present in the statements. At least one context must be capable of parsing all statements.

The statements block can replace the log_statements, metric_statements, and trace_statements blocks. It can also be used alongside them.

Name	Type	Description	Default	Required
`log`	`list(string)`	A list of OTTL statements which transform logs.	`[]`	no
`metric`	`list(string)`	A list of OTTL statements which transform metrics.	`[]`	no
`trace`	`list(string)`	A list of OTTL statements which transform traces.	`[]`	no

The inference happens automatically because path names are prefixed with the context name. In the following example, the inferred context value is datapoint, as it’s the only context that supports parsing both datapoint and metric paths:

statements {
    metric = [`set(metric.description, "test passed") where datapoint.attributes["test"] == "pass"`]
}

In the following example, the inferred context is metric, as metric is the context capable of parsing both metric and resource data:

statements {
    metric = [
        `resource.attributes["test"], "passed"`,
        `set(metric.description, "test passed")`,
    ]
}

The primary benefit of context inference is that it enhances the efficiency of statement processing by linking them to the most suitable context. This optimization ensures that data transformations are both accurate and performant, leveraging the hierarchical structure of contexts to avoid unnecessary iterations and improve overall processing efficiency. All of this happens automatically, leaving you to write OTTL statements without worrying about contexts.

`trace_statements`

The trace_statements block specifies statements which transform trace telemetry signals. Multiple trace_statements blocks can be specified.

Name	Type	Description	Required
`context`	`string`	OTTL Context to use when interpreting the associated statements.	yes
`statements`	`list(string)`	A list of OTTL statements.	yes
`conditions`	`list(string)`	Conditions for the statements to be executed.	no
`error_mode`	`string`	How to react to errors if they occur while processing a statement.	no

The supported values for context are:

resource: Use when interacting only with OTLP resources (for example, resource attributes).
scope: Use when interacting only with OTLP instrumentation scope (for example, the name of the instrumentation scope).
span: Use when interacting only with OTLP spans.
spanevent: Use when interacting only with OTLP span events.

Refer to [OTTL Context][] for more information about how to use contexts.

The allowed values for error_mode are the same as the ones documented in the Arguments section. If error_mode is not specified in trace_statements, the top-level error_mode is applied.

OTTL Context

Each context allows the transformation of its type of telemetry. For example, statements associated with a resource context will be able to transform the resource’s attributes and dropped_attributes_count.

Each type of context defines its own paths and enums specific to that context. Refer to the OpenTelemetry documentation for a list of paths and enums for each context:

Contexts NEVER supply access to individual items “lower” in the protobuf definition.

This means statements associated to a resource WILL NOT be able to access the underlying instrumentation scopes.
This means statements associated to a scope WILL NOT be able to access the underlying telemetry slices (spans, metrics, or logs).
Similarly, statements associated to a metric WILL NOT be able to access individual datapoints, but can access the entire datapoints slice.
Similarly, statements associated to a span WILL NOT be able to access individual SpanEvents, but can access the entire SpanEvents slice.

For practical purposes, this means that a context can’t make decisions on its telemetry based on telemetry “lower” in the structure. For example, the following context statement isn’t possible because it attempts to use individual datapoint attributes in the condition of a statement associated to a metric:

metric_statements {
  context = "metric"
  statements = [
    "set(description, \"test passed\") where datapoints.attributes[\"test\"] == \"pass\"",
  ]
}

Context ALWAYS supply access to the items “higher” in the protobuf definition that are associated to the telemetry being transformed.

This means that statements associated to a datapoint have access to a datapoint’s metric, instrumentation scope, and resource.
This means that statements associated to a spanevent have access to a spanevent’s span, instrumentation scope, and resource.
This means that statements associated to a span/metric/log have access to the telemetry’s instrumentation scope, and resource.
This means that statements associated to a scope have access to the scope’s resource.

For example, the following context statement is possible because datapoint statements can access the datapoint’s metric.

metric_statements {
  context = "datapoint"
  statements = [
    "set(metric.description, \"test passed\") where attributes[\"test\"] == \"pass\"",
  ]
}

The protobuf definitions for OTLP signals are maintained on GitHub:

Whenever possible, associate your statements to the context which the statement intens to transform. The contexts are nested, and the higher-level contexts don’t have to iterate through any of the contexts at a lower level. For example, although you can modify resource attributes associated to a span using the span context, it’s more efficient to use the resource context.

Exported fields

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

Name	Type	Description
`input`	`otelcol.Consumer`	A value that other components can use to send telemetry data to.

input accepts otelcol.Consumer data for any telemetry signal (metrics, logs, or traces).

Component health

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

Debug information

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

Debug metrics

otelcol.processor.transform doesn’t expose any component-specific debug metrics.

Examples

Perform a transformation if an attribute doesn’t exist

This example sets the attribute test to pass if the attribute test doesn’t exist.

otelcol.processor.transform "default" {
  error_mode = "ignore"

  trace_statements {
    context = "span"
    statements = [
      // Accessing a map with a key that doesn't exist will return nil.
      `set(attributes["test"], "pass") where attributes["test"] == nil`,
    ]
  }

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

Rename a resource attribute

The are two ways to rename an attribute key. One way is to set a new attribute and delete the old one:

otelcol.processor.transform "default" {
  error_mode = "ignore"

  trace_statements {
    context = "resource"
    statements = [
      `set(attributes["namespace"], attributes["k8s.namespace.name"])`,
      `delete_key(attributes, "k8s.namespace.name")`,
    ]
  }

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

Another way is to update the key using regular expressions:

otelcol.processor.transform "default" {
  error_mode = "ignore"

  trace_statements {
    context = "resource"
    statements = [
     `replace_all_patterns(attributes, "key", "k8s\\.namespace\\.name", "namespace")`,
    ]
  }

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

Create an attribute from the contents of a log body

This example sets the attribute body to the value of the log body:

otelcol.processor.transform "default" {
  error_mode = "ignore"

  log_statements {
    context = "log"
    statements = [
      `set(attributes["body"], body)`,
    ]
  }

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

Combine two attributes

This example sets the attribute test to the value of attributes service.name and service.version combined.

otelcol.processor.transform "default" {
  error_mode = "ignore"

  trace_statements {
    context = "resource"
    statements = [
      // The Concat function combines any number of strings, separated by a delimiter.
      `set(attributes["test"], Concat([attributes["service.name"], attributes["service.version"]], " "))`,
    ]
  }

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

Parsing JSON logs

Given the following JSON body:

{
  "name": "log",
  "attr1": "example value 1",
  "attr2": "example value 2",
  "nested": {
    "attr3": "example value 3"
  }
}

You can add specific fields as attributes on the log:

otelcol.processor.transform "default" {
  error_mode = "ignore"

  log_statements {
    context = "log"

    statements = [
      // Parse body as JSON and merge the resulting map with the cache map, ignoring non-json bodies.
      // cache is a field exposed by OTTL that is a temporary storage place for complex operations.
      `merge_maps(cache, ParseJSON(body), "upsert") where IsMatch(body, "^\\{")`,

      // Set attributes using the values merged into cache.
      // If the attribute doesn't exist in cache then nothing happens.
      `set(attributes["attr1"], cache["attr1"])`,
      `set(attributes["attr2"], cache["attr2"])`,

      // To access nested maps you can chain index ([]) operations.
      // If nested or attr3 do no exist in cache then nothing happens.
      `set(attributes["nested.attr3"], cache["nested"]["attr3"])`,
    ]
  }

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

Various transformations of attributes and status codes

The example takes advantage of context efficiency by grouping transformations with the context which it intends to transform.

otelcol.receiver.otlp "default" {
  http {}
  grpc {}

  output {
    metrics = [otelcol.processor.transform.default.input]
    logs    = [otelcol.processor.transform.default.input]
    traces  = [otelcol.processor.transform.default.input]
  }
}

otelcol.processor.transform "default" {
  error_mode = "ignore"

  trace_statements {
    context = "resource"
    statements = [
      `keep_keys(attributes, ["service.name", "service.namespace", "cloud.region", "process.command_line"])`,
      `replace_pattern(attributes["process.command_line"], "password\\=[^\\s]*(\\s?)", "password=***")`,
      `limit(attributes, 100, [])`,
      `truncate_all(attributes, 4096)`,
    ]
  }

  trace_statements {
    context = "span"
    statements = [
      `set(status.code, 1) where attributes["http.path"] == "/health"`,
      `set(name, attributes["http.route"])`,
      `replace_match(attributes["http.target"], "/user/*/list/*", "/user/{userId}/list/{listId}")`,
      `limit(attributes, 100, [])`,
      `truncate_all(attributes, 4096)`,
    ]
  }

  metric_statements {
    context = "resource"
    statements = [
      `keep_keys(attributes, ["host.name"])`,
      `truncate_all(attributes, 4096)`,
    ]
  }

  metric_statements {
    context = "metric"
    statements = [
      `set(description, "Sum") where type == "Sum"`,
      `convert_sum_to_gauge() where name == "system.processes.count"`,
      `convert_gauge_to_sum("cumulative", false) where name == "prometheus_metric"`,
      `aggregate_on_attributes("sum") where name == "system.memory.usage"`,
    ]
  }

  metric_statements {
    context = "datapoint"
    statements = [
      `limit(attributes, 100, ["host.name"])`,
      `truncate_all(attributes, 4096)`,
    ]
  }

  log_statements {
    context = "resource"
    statements = [
      `keep_keys(attributes, ["service.name", "service.namespace", "cloud.region"])`,
    ]
  }

  log_statements {
    context = "log"
    statements = [
      `set(severity_text, "FAIL") where body == "request failed"`,
      `replace_all_matches(attributes, "/user/*/list/*", "/user/{userId}/list/{listId}")`,
      `replace_all_patterns(attributes, "value", "/account/\\d{4}", "/account/{accountId}")`,
      `set(body, attributes["http.route"])`,
    ]
  }

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

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("OTLP_ENDPOINT")
  }
}

Using conditions

This example only runs the statements if the conditions are met:

otelcol.processor.transform "default" {
  error_mode = "ignore"

  metric_statements {
    context = "metric"
    statements = [
      `set(metric.description, "Sum")`,
    ]
    conditions = [
      `metric.type == METRIC_DATA_TYPE_SUM`,
    ]
  }

  log_statements {
    context = "log"
    statements = [
      `set(log.body, log.attributes["http.route"])`,
    ]
    conditions = [
      `IsMap(log.body) and log.body["object"] != nil`,
    ]
  }

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

Compatible components

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

Components that export OpenTelemetry otelcol.Consumer

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

Components that consume OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.awscloudwatch

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.awscloudwatch`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.receiver.awscloudwatch receives logs from Amazon CloudWatch and forwards them to other otelcol.* components.

Note
otelcol.receiver.awscloudwatch is a wrapper over the upstream OpenTelemetry Collector awscloudwatch receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.receiver.awscloudwatch components by giving them different labels.

Usage

otelcol.receiver.awscloudwatch "<LABEL>" {
  region = "us-west-2"

  output {
    logs = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.awscloudwatch:

Name	Type	Description	Required
`region`	`string`	AWS region to collect logs from.	yes
`imds_endpoint`	`string`	Custom EC2 IMDS endpoint to use.	no
`profile`	`string`	AWS credentials profile to use.	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use for persisting state.	no

If imds_endpoint isn’t specified, and the environment variable AWS_EC2_METADATA_SERVICE_ENDPOINT has a value, it will be used as the IMDS endpoint.

Blocks

You can use the following blocks with otelcol.receiver.awscloudwatch:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`logs`

The logs block configures how logs are collected from CloudWatch.

The following arguments are supported:

Name	Type	Description	Default	Required
`max_events_per_request`	`int`	Maximum number of events to process per request to CloudWatch.	`1000`	no
`poll_interval`	`duration`	How frequently to poll for new log entries.	`"1m"`	no
`start_from`	`string`	Timestamp in RFC3339 format where to start reading logs.	`""`	no

The logs block supports the following blocks:

Block	Description	Required
groups	Configures which log groups to collect from.	no

`logs` > `groups`

The groups block supports the following blocks:

Block	Description	Required
autodiscover	Configures automatic discovery of log groups.	no
named	Configures specific log groups to collect from.	no

The blocks autodiscover or named are mutually exclusive.

`logs` > `groups` > `autodiscover`

The autodiscover block configures automatic discovery of log groups.

The following arguments are supported:

Name	Type	Description	Default	Required
`limit`	`int`	Maximum number of log groups to discover.	`50`	no
`prefix`	`string`	Prefix to filter log groups by.		no

The autodiscover block supports the following blocks:

Block	Description	Required
streams	Configures log streams filtering.	no

`logs` > `groups` > `autodiscover` > `streams`

The streams block configures filtering of log streams for the autodiscovered log groups.

The following arguments are supported:

Name	Type	Description	Default	Required
`names`	`[]string`	List of exact stream names to collect.		no
`prefixes`	`[]string`	List of prefixes to filter streams by.		no

`logs` > `groups` > `named`

The named block explicitly configures specific log groups to collect from. Multiple named blocks can be specified.

The following arguments are supported:

Name	Type	Description	Required
`group_name`	`string`	Name of the CloudWatch log group.	yes
`names`	`[]string`	List of exact stream names to collect.	no
`prefixes`	`[]string`	List of prefixes to filter streams by.	no

Exported fields

otelcol.receiver.awscloudwatch doesn’t export any fields.

Component health

otelcol.receiver.awscloudwatch is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.awscloudwatch doesn’t expose any component-specific debug information.

Example

The following example collects logs from specific EKS cluster log groups and forwards them through a batch processor:

otelcol.receiver.awscloudwatch "default" {
  region = "us-west-2"

  logs {
    poll_interval = "3m"
    max_events_per_request = 5000

    groups {
      named {
        group_name = "/aws/eks/dev-cluster/cluster"
        names = ["api-gateway"]
      }
      named {
        group_name = "/aws/eks/prod-cluster/cluster"
        prefixes = ["app-", "service-"]
      }
    }
  }

  output {
    logs = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    logs = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = env("<OTLP_ENDPOINT>")
  }
}

Compatible components

otelcol.receiver.awscloudwatch can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.awsecscontainermetrics

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.awsecscontainermetrics`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.receiver.awsecscontainermetrics reads AWS ECS task- and container-level metadata, and resource usage metrics such as CPU, memory, network, and disk, and forwards them to other otelcol.* components.

Note
otelcol.receiver.awsecscontainermetrics is a wrapper over the upstream OpenTelemetry Collector awsecscontainermetrics receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

This receiver supports ECS Fargate and ECS on EC2. It uses ECS Task Metadata Endpoint V4 which is automatically available within the task’s containers. Therefore, you should run the Alloy collector using this receiver as a sidecar within the task you want to monitor. Refer to the upstream awsecscontainermetrics receiver documentation for more details.

You can specify multiple otelcol.receiver.awsecscontainermetrics components by giving them different labels.

Usage

otelcol.receiver.awsecscontainermetrics "<LABEL>" {
  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.awsecscontainermetrics:

Name	Type	Description	Default	Required
`collection_interval`	`duration`	How frequently to collect and emit metrics.	“20s”	no

Blocks

You can use the following blocks with otelcol.receiver.awsecscontainermetrics:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

otelcol.receiver.awsecscontainermetrics doesn’t export any fields.

Component health

otelcol.receiver.awsecscontainermetrics is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.awsecscontainermetrics doesn’t expose any component-specific debug information.

Example

The following example collects eight task-level metrics from the 52 metrics available in an ECS task and forwards them to a filter processor.

otelcol.receiver.awsecscontainermetrics "default" {
  collection_interval = "60s"

  output {
    metrics = [otelcol.processor.filter.default.input]
  }
}

otelcol.processor.filter "default" {
  error_mode = "ignore"

  metrics {
    metric = [
      string.join([
        `metric.name != "ecs.task.memory.reserved"`,
        `metric.name != "ecs.task.memory.utilized"`,
        `metric.name != "ecs.task.cpu.reserved"`,
        `metric.name != "ecs.task.cpu.utilized"`,
        `metric.name != "ecs.task.network.rate.rx"`,
        `metric.name != "ecs.task.network.rate.tx"`,
        `metric.name != "ecs.task.storage.read_bytes"`,
        `metric.name != "ecs.task.storage.write_bytes"`,
      ], " and "),
    ]
  }

  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = env("<OTLP_ENDPOINT>")
  }
}

Compatible components

otelcol.receiver.awsecscontainermetrics can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.awss3

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.awss3`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.receiver.awss3 receives telemetry stored in S3 by the AWS S3 Exporter.

Warning
otelcol.receiver.awss3 is a wrapper over the upstream OpenTelemetry Collector awss3 receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

The receiver has two modes of operation:

Time Range Mode - Specify start and end to fetch data from a specific time range.
SQS Message Mode - Subscribe to SQS messages to process objects as they arrive.

The receiver supports the following encodings:

otlp_json (OpenTelemetry Protocol format represented as JSON) with a suffix of .json
otlp_proto (OpenTelemetry Protocol format represented as Protocol Buffers) with a suffix of .binpb

Note
Currently, otelcol.receiver.awss3 receiver doesn’t support encoding extensions.

You can specify multiple otelcol.receiver.awss3 components by giving them different labels.

Usage

otelcol.receiver.awss3 "<LABEL>" {
  start_time = "..."
  end_time = "..."

  s3downloader {
    s3_bucket = "..."
    s3_prefix = "..."
  }

  output {
    logs = [...]
    metrics = [...]
    trace = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.awss3:

Name	Type	Description	Default	Required
`start_time`	`string`	The time at which to start retrieving data.		Required if fetching by time.
`end_time`	`string`	The time at which to stop retrieving data.		Required if fetching by time.

The start_time and end_time fields use one of the following time formats: RFC3339, YYYY-MM-DD HH:MM, or YYYY-MM-DD. When using YYYY-MM-DD, the time defaults to 00:00.

Note
Time-based configuration (start_time and end_time arguments) can’t be combined together with sqs block.

Refer to the upstream receiver documentation for more details.

Blocks

You can use the following blocks with otelcol.receiver.awss3:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`s3downloader`

Required

The s3downloader block contains AWS S3 downloader related configuration to control things like bucket, prefix, batching, connections, retries, etc.

The following arguments are supported:

Name	Type	Description	Default	Required
`s3_bucket`	`string`	S3 bucket.		yes
`s3_prefix`	`string`	Prefix for the S3 key (root directory inside bucket).		yes
`endpoint_partition_id`	`string`	Partition id to use if `endpoint` is specified.	`"aws"`	no
`endpoint`	`string`	Overrides the endpoint used by the exporter instead of constructing it from `region` and `s3_bucket`.		no
`file_prefix`	`string`	Prefix used to filter files for download.		no
`region`	`string`	AWS region.	`"us-east-1"`	no
`s3_force_path_style`	`bool`	When enabled, forces the request to use path-style addressing.	`false`	no
`s3_partition_format`	`string`	Format for the partition key. See strftime for format specification.	`"year=%Y/month=%m/day=%d/hour=%H/minute=%M"`	no
`s3_partition_timezone`	`string`	IANA timezone name applied when formatting the partition key.	Local time	no

`sqs`

The sqs block holds SQS queue configuration for receiving object change notifications.

The following arguments are supported:

Name	Type	Description	Default	Required
`queue_url`	`string`	The URL of the SQS queue that receives S3 bucket notifications.		yes
`region`	`string`	AWS region of the SQS queue.		yes
`endpoint`	`string`	Custom endpoint for the SQS service.		no
`max_number_of_messages`	`int`	Maximum number of messages to retrieve in a single SQS request.	`10`	no
`wait_time_seconds`	`int`	Wait time in seconds for long polling SQS requests.	`20`	no

Note
You must configure your S3 bucket to send event notifications to the SQS queue. Time-based configuration (start_time/end_time) and SQS configuration can’t be used together.

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

Exported fields

otelcol.receiver.awss3 doesn’t export any fields.

Component health

otelcol.receiver.awss3 is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.awss3 doesn’t expose any component-specific debug information.

Example

This example forwards received traces through a batch processor before finally sending it to an OTLP-capable endpoint:

// Time range mode:
otelcol.receiver.awss3 "default" {
  start_time = "2024-01-01 01:00"
  end_time = "2024-01-02"

  s3downloader {
    region = "us-west-1"
    s3_bucket = "mybucket"
    s3_prefix = "trace"
    s3_partition = "minute"
  }

  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

// SQS message mode:
otelcol.receiver.awss3 "sqs_traces" {
  s3downloader {
    region = "us-east-1"
    s3_bucket = "mybucket"
    s3_prefix = "mytrace"
  }

  sqs {
    queue_url = "https://sqs.us-east-1.amazonaws.com/123456789012/test-queue"
    region = "us-east-1"
  }

  output {
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
    logs    = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("<OTLP_ENDPOINT>")
  }
}

Compatible components

otelcol.receiver.awss3 can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.cloudflare

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.cloudflare`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.receiver.cloudflare receives logs sent by Cloudflare LogPush jobs.

Note
otelcol.receiver.cloudflare is a wrapper over the upstream OpenTelemetry Collector cloudflare receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.receiver.cloudflare components by giving them different labels.

Usage

otelcol.receiver.cloudflare "<LABEL>" {
  endpoint = "<HOST>:<PORT>"

  output {
    logs = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.cloudflare:

Name	Type	Description	Default	Required
`endpoint`	`string`	The `<HOST:PORT>` endpoint address on which the receiver awaits requests from Cloudflare.		yes
`secret`	`string`	If this value is set, the receiver expects to see it in any valid requests under the `X-CF-Secret` header.		no
`attributes`	`map[string]string`	Sets log attributes from message fields. Only string, boolean, integer, or float fields can be mapped.		no
`delimiter`	`string`	The separator to join nested fields in the log message when setting attributes.	`"."`	no
`timestamp_field`	`string`	Log field name that contains timestamp.	`"EdgeStartTimestamp"`	no
`timestamp_format`	`string`	One of `unix`, `unixnano`, or `rfc3339`, matching how your LogPush job encodes the timestamp field.	`"rfc3339"`	no

When the attributes configuration is empty, the receiver will automatically ingest all fields from the log messages as attributes, using the original field names as attribute names.

Refer to the upstream receiver documentation for more details.

Blocks

You can use the following blocks with otelcol.receiver.cloudflare:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`tls`

The tls block configures TLS settings used for a server. If the tls block isn’t provided, TLS won’t be used for connections to the server.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`client_ca_file`	`string`	Path to the TLS cert to use by the server to verify a client certificate.		no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no

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. Refer to the Go Cipher Suites documentation for a list of supported cipher suites.

client_ca_file sets the ClientCA and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Refer to the Go TLS documentation for more information.

Exported fields

otelcol.receiver.cloudflare doesn’t export any fields.

Component health

otelcol.receiver.cloudflare is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.cloudflare doesn’t expose any component-specific debug information.

Example

The following example receives logs from Cloudflare and forwards them through a batch processor:

otelcol.receiver.cloudflare "default" {
  endpoint = "<HOST>:<PORT>"
  secret = "1234567890abcdef1234567890abcdef"
  timestamp_field = "EdgeStartTimestamp"
  timestamp_format = "rfc3339"
  attributes = {
    ClientIP = "http_request.client_ip",
    ClientRequestURI = "http_request.uri",
  }

  tls {
    cert_file = "/path/to/cert.pem"
    key_file = "/path/to/key.pem"
  }

  output {
    logs = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    logs = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = env("<OTLP_ENDPOINT>")
  }
}

Replace the following:

<HOST>: The hostname or IP address where the receiver listens for Cloudflare LogPush requests.
<PORT>: The port number where the receiver listens for Cloudflare LogPush requests.
<OTLP_ENDPOINT>: The OTLP endpoint URL for your observability backend.

Compatible components

otelcol.receiver.cloudflare can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.datadog

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.datadog`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.receiver.datadog accepts Datadog metrics and traces over the network and forwards it to other otelcol.* components.

You can specify multiple otelcol.receiver.datadog components by giving them different labels.

Note
otelcol.receiver.datadog is a wrapper over the upstream OpenTelemetry Collector datadog receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Usage

otelcol.receiver.datadog "<LABEL>" {
  output {
    metrics = [...]
    traces  = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.datadog:

Name	Type	Description	Default	Required
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`compression_algorithms`	`list(string)`	A list of compression algorithms the server can accept.	`["", "gzip", "zstd", "zlib", "snappy", "deflate", "lz4"]`	no
`endpoint`	`string`	`host:port` to listen for traffic on.	`"localhost:8126"`	no
`include_metadata`	`bool`	Propagate incoming connection metadata to downstream consumers.	`false`	no
`keep_alives_enabled`	`boolean`	Whether or not HTTP keep-alives are enabled	`true`	no
`max_request_body_size`	`string`	Maximum request body size the server will allow.	`"20MiB"`	no
`read_timeout`	`duration`	Read timeout for requests of the HTTP server.	`"60s"`	no
`trace_id_cache_size`	`int`	Cache size for mapping 64-bit to 128-bit trace IDs.	`0`	no

By default, otelcol.receiver.datadog listens for HTTP connections on localhost. To expose the HTTP server to other machines on your network, configure endpoint with the IP address to listen on, or 0.0.0.0:8126 to listen on all network interfaces.

Blocks

You can use the following blocks with otelcol.receiver.datadog:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`cors`

The cors block configures CORS settings for an HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`allowed_origins`	`list(string)`	Allowed values for the `Origin` header.	`[]`	no
`allowed_headers`	`list(string)`	Accepted headers from CORS requests.	`["X-Requested-With"]`	no
`max_age`	`number`	Configures the `Access-Control-Max-Age` response header.	`0`	no

The allowed_headers argument specifies which headers are acceptable from a CORS request. The following headers are always implicitly allowed:

Accept
Accept-Language
Content-Type
Content-Language

If allowed_headers includes "*", all headers are permitted.

`intake`

The intake block configures how the /intake endpoint behaves. The Datadog Agent uses this endpoint to submit host tags and other metadata.

The following arguments are supported:

Name	Type	Description	Default	Required
`behavior`	`string`	How the `/intake` endpoint behaves: `"disable"` or `"proxy"`.		yes

Set behavior to "proxy" to forward /intake requests to Datadog’s API. Proxying requires a nested proxy { api { ... } } block with a Datadog API key. When set to "disable", the endpoint returns an error for any incoming request.

`proxy`

The proxy block configures how the /intake proxy operates. It’s only used when behavior is set to "proxy". If behavior isn’t "proxy", this block is ignored.

This block has no arguments and is configured with the nested [api][api] block.

`api`

The api block configures the Datadog API connection used by the intake proxy.

The following arguments are supported:

Name	Type	Description	Default	Required
`key`	`secret`	Datadog API key.		yes
`site`	`string`	Datadog site to send data to.	`"datadoghq.com"`	no
`fail_on_invalid_key`	`bool`	Exit on startup if the API key is invalid.	`false`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`tls`

The tls block configures TLS settings used for a server. If the tls block isn’t provided, TLS won’t be used for connections to the server.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`client_ca_file`	`string`	Path to the TLS cert to use by the server to verify a client certificate.		no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no

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. Refer to the Go Cipher Suites documentation for a list of supported cipher suites.

client_ca_file sets the ClientCA and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Refer to the Go TLS documentation for more information.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

Exported fields

otelcol.receiver.datadog doesn’t export any fields.

Component health

otelcol.receiver.datadog is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.datadog doesn’t expose any component-specific debug information.

Example

This example forwards received telemetry through a batch processor before finally sending it to an OTLP-capable endpoint:

otelcol.receiver.datadog "default" {
  output {
    metrics = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
    traces  = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("OTLP_ENDPOINT")
  }
}

Proxy `/intake` requests to Datadog

You can configure the receiver to forward /intake requests (host tags and metadata) to Datadog’s API while processing metrics and traces locally:

otelcol.receiver.datadog "default" {
  intake {
    behavior = "proxy"
    proxy {
      api {
        key  = sys.env("DD_API_KEY")
        site = "datadoghq.eu"
      }
    }
  }

  output {
    metrics = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
}

Enable authentication

You can create a otelcol.receiver.datadog component that requires authentication for requests. This is useful for limiting who can push data to the server.

Note
Not all OpenTelemetry Collector authentication plugins support receiver authentication. Refer to the documentation for each otelcol.auth.* component to determine its compatibility.

otelcol.receiver.datadog "default" {
  output {
    metrics = [otelcol.processor.batch.default.input]
    traces  = [otelcol.processor.batch.default.input]
  }
  auth = otelcol.auth.basic.creds.handler
}

otelcol.auth.basic "creds" {
    username = sys.env("<USERNAME>")
    password = sys.env("<PASSWORD>")
}

Compatible components

otelcol.receiver.datadog can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.faro

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.faro`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.receiver.faro accepts telemetry data from the Grafana Faro Web SDK and forwards it to other otelcol.* components.

You can specify multiple otelcol.receiver.faro components by giving them different labels.

Note
This component is necessary for Grafana Cloud Frontend Observability to work. For more information, refer to the Choose a component guide.

Note
otelcol.receiver.faro is a wrapper over the upstream OpenTelemetry Collector faro receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Usage

otelcol.receiver.faro "<LABEL>" {
  output {
    logs   = [...]
    traces = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.faro:

Name	Type	Description	Default	Required
`auth`	`capsule(otelcol.Handler)`	Handler from an `otelcol.auth` component to use for authenticating requests.		no
`compression_algorithms`	`list(string)`	A list of compression algorithms the server can accept.	`["", "gzip", "zstd", "zlib", "snappy", "deflate", "lz4"]`	no
`endpoint`	`string`	`host:port` to listen for traffic on.	`"localhost:8080"`	no
`include_metadata`	`bool`	Propagate incoming connection metadata to downstream consumers.	`false`	no
`keep_alives_enabled`	`boolean`	Whether or not HTTP keep-alives are enabled	`true`	no
`max_request_body_size`	`string`	Maximum request body size the server will allow.	`"20MiB"`	no

By default, otelcol.receiver.faro listens for HTTP connections on localhost. To expose the HTTP server to other machines on your network, configure endpoint with the IP address to listen on, or 0.0.0.0:8080 to listen on all network interfaces.

Blocks

You can use the following blocks with otelcol.receiver.faro:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`cors`

The cors block configures CORS settings for an HTTP server.

The following arguments are supported:

Name	Type	Description	Default	Required
`allowed_origins`	`list(string)`	Allowed values for the `Origin` header.	`[]`	no
`allowed_headers`	`list(string)`	Accepted headers from CORS requests.	`["X-Requested-With"]`	no
`max_age`	`number`	Configures the `Access-Control-Max-Age` response header.	`0`	no

The allowed_headers argument specifies which headers are acceptable from a CORS request. The following headers are always implicitly allowed:

Accept
Accept-Language
Content-Type
Content-Language

If allowed_headers includes "*", all headers are permitted.

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`tls`

The tls block configures TLS settings used for a server. If the tls block isn’t provided, TLS won’t be used for connections to the server.

The following arguments are supported:

Name	Type	Description	Default	Required
`ca_file`	`string`	Path to the CA file.		no
`ca_pem`	`string`	CA PEM-encoded text to validate the server with.		no
`cert_file`	`string`	Path to the TLS certificate.		no
`cert_pem`	`string`	Certificate PEM-encoded text for client authentication.		no
`cipher_suites`	`list(string)`	A list of TLS cipher suites that the TLS transport can use.	`[]`	no
`client_ca_file`	`string`	Path to the TLS cert to use by the server to verify a client certificate.		no
`curve_preferences`	`list(string)`	Set of elliptic curves to use in a handshake.	`[]`	no
`include_system_ca_certs_pool`	`boolean`	Whether to load the system certificate authorities pool alongside the certificate authority.	`false`	no
`key_file`	`string`	Path to the TLS certificate key.		no
`key_pem`	`secret`	Key PEM-encoded text for client authentication.		no
`max_version`	`string`	Maximum acceptable TLS version for connections.	`"TLS 1.3"`	no
`min_version`	`string`	Minimum acceptable TLS version for connections.	`"TLS 1.2"`	no
`reload_interval`	`duration`	The duration after which the certificate is reloaded.	`"0s"`	no

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. Refer to the Go Cipher Suites documentation for a list of supported cipher suites.

client_ca_file sets the ClientCA and ClientAuth to RequireAndVerifyClientCert in the TLSConfig. Refer to the Go TLS documentation for more information.

`tpm`

The tpm block configures retrieving the TLS key_file from a trusted device.

The following arguments are supported:

Name	Type	Description	Default	Required
`auth`	`string`	The authorization value used to authenticate the TPM device.	`""`	no
`enabled`	`bool`	Load the `tls.key_file` from TPM.	`false`	no
`owner_auth`	`string`	The owner authorization value used to authenticate the TPM device.	`""`	no
`path`	`string`	Path to the TPM device or Unix domain socket.	`""`	no

The trusted platform module (TPM) configuration can be used for loading TLS key from TPM. Currently only TSS2 format is supported.

The path attribute is not supported on Windows.

In the following example, the private key my-tss2-key.key in TSS2 format is loaded from the TPM device /dev/tmprm0:

otelcol.example.component "<LABEL>" {
    ...
    tls {
        ...
        key_file = "my-tss2-key.key"
        tpm {
            enabled = true
            path = "/dev/tpmrm0"
        }
    }
}

Exported fields

otelcol.receiver.faro doesn’t export any fields.

Component health

otelcol.receiver.faro is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.faro doesn’t expose any component-specific debug information.

Examples

This example forwards received telemetry through a batch processor before finally sending it to an OTLP-capable endpoint:

otelcol.receiver.faro "default" {
  output {
    logs   = [otelcol.processor.batch.default.input]
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    logs   = [otelcol.exporter.faro.default.input]
    traces = [otelcol.exporter.faro.default.input]
  }
}

otelcol.exporter.faro "default" {
  client {
    endpoint = "<FARO_COLLECTOR_ADDRESS>"
  }
}

Replace the following:

<FARO_COLLECTOR_ADDRESS>: The address of the Faro-compatible server to send data to.

Enable TLS

You can configure otelcol.receiver.faro to use TLS for added security:

otelcol.receiver.faro "default" {
  endpoint = "localhost:8443"
  
  tls {
    cert_file = "/path/to/cert.pem"
    key_file  = "/path/to/key.pem"
  }
  
  output {
    logs   = [otelcol.processor.batch.default.input]
    traces = [otelcol.processor.batch.default.input]
  }
}

Enable authentication

You can create a otelcol.receiver.faro component that requires authentication for requests. This is useful for limiting who can push data to the server.

Note
Not all OpenTelemetry Collector authentication plugins support receiver authentication. Refer to the documentation for each otelcol.auth.* component to determine its compatibility.

otelcol.receiver.faro "default" {
  auth     = otelcol.auth.basic.creds.handler
  
  output {
    logs   = [otelcol.processor.batch.default.input]
    traces = [otelcol.processor.batch.default.input]
  }
}

otelcol.auth.basic "creds" {
  username = sys.env("FARO_USERNAME")
  password = sys.env("FARO_PASSWORD")
}

Configure CORS

You can configure CORS settings to allow web applications to send telemetry data from browsers:

otelcol.receiver.faro "default" {
  cors {
    allowed_origins = ["https://my-webapp.example.com", "https://staging.example.com"]
    allowed_headers = ["Content-Type", "X-Custom-Header"]
    max_age         = 3600
  }
  
  output {
    logs   = [otelcol.processor.batch.default.input]
    traces = [otelcol.processor.batch.default.input]
  }
}

Compatible components

otelcol.receiver.faro can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.file_stats

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.file_stats`

otelcol.receiver.file_stats collects metrics from files and folders specified with a glob pattern.

Note
otelcol.receiver.file_stats is a wrapper over the upstream OpenTelemetry Collector filestats receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

Multiple otelcol.receiver.file_stats components can be specified by giving them different labels.

Warning
otelcol.receiver.file_stats only works on macOS, Linux, and Windows.

Usage

otelcol.receiver.file_stats "<LABEL>" {
  include = "GLOB_PATTERN"

  output {
    metrics = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.file_stats:

Name	Type	Description	Default	Required
`include`	`string`	Glob path for paths to collect stats from.		yes
`collection_interval`	`duration`	How often to collect statistics.	`"1m"`	no
`initial_delay`	`duration`	Initial time to wait before collecting statistics.	`"1s"`	no
`timeout`	`duration`	Timeout for a collection; `0s` means no timeout.	`"0s"`	no

include is a glob pattern that specifies which paths (files and folders) to collect stats from. A * character matches entries in a directory, while ** includes subdirectories. For example, /var/log/**/*.log matches all files and directories ending in .log recursively inside /var/log.

The timeout argument controls the timeout for each collection specified by the collection_interval. The timeout applies to the entire collection process across all paths matched by the include argument.

Blocks

You can use the following blocks with otelcol.receiver.file_stats:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`metrics`

The metrics block configures the set of metrics that will be sent to downstream components. It accepts no arguments, but contains other blocks for individual metrics:

The [file.atime][file.atime] block
The [file.count][file.count] block
The [file.ctime][file.ctime] block
The [file.mtime][file.mtime] block
The [file.size][file.size] block

Refer to the documentation of individual metric blocks for whether that metric is enabled by default.

`file.atime`

The file.atime block configures the file.atime metric. file.atime tracks the elapsed time since the last access of the file or folder in Unix seconds since the epoch.

Name	Type	Description	Default	Required
`enabled`	`boolean`	Whether to collect the `file.atime` metric.	`false`	no

`file.count`

The file.count block configures the file.count metric. file.count tracks the number of files and folders in the specified glob pattern.

Name	Type	Description	Default	Required
`enabled`	`boolean`	Whether to collect the `file.count` metric.	`false`	no

`file.ctime`

The file.ctime block configures the file.ctime metric. file.ctime tracks the elapsed time since the last change of the file or folder in Unix seconds since the epoch. Changes include permissions, ownership, and timestamps.

Name	Type	Description	Default	Required
`enabled`	`boolean`	Whether to collect the `file.ctime` metric.	`false`	no

`file.mtime`

The file.mtime block configures the file.mtime metric. file.mtime tracks the elapsed time since the last modification of the file or folder in Unix seconds since the epoch.

Name	Type	Description	Default	Required
`enabled`	`boolean`	Whether to collect the `file.mtime` metric.	`true`	no

`file.size`

The file.size block configures the file.size metric. file.size tracks the size of the file or folder in bytes.

Name	Type	Description	Default	Required
`enabled`	`boolean`	Whether to collect the `file.size` metric.	`true`	no

`resource_attributes`

The resource_attributes block configures resource attributes for metrics sent to downstream components. It accepts no arguments, but contains other blocks for configuring individual resource attributes:

The [file.name][file.name] block
The [file.path][file.path] block

Refer to the documentation of individual resource attribute blocks for whether that resource attribute is enabled by default.

`file.name`

The file.name block configures the file.name resource attribute.

Name	Type	Description	Default	Required
`enabled`	`boolean`	Whether to include the `file.name` resource attribute.	`true`	no

When enabled is true, the file.name attribute is included in all metrics.

The children blocks metrics_include and metrics_exclude can be used to further filter which metrics are given the file.name attribute. If a given metric matches all the metrics_include blocks and none of the metrics_exclude blocks, the file.name attribute is added.

`metrics_exclude`

The metrics_exclude block configures a filter for excluding metrics. The metrics_exclude block may be specified multiple times.

Name	Type	Description	Default	Required
`strict`	`string`	The exact name of the metric to exclude.		yes*
`regexp`	`string`	A regular expression for the metrics to exclude.		yes*

Exactly one of strict or regexp must be specified.

`metrics_include`

The metrics_include block configures a filter for matching metrics. The metrics_include block may be specified multiple times.

Name	Type	Description	Default	Required
`strict`	`string`	The exact name of the metric to include.		yes*
`regexp`	`string`	A regular expression for the metrics to include.		yes*

Exactly one of strict or regexp must be specified.

`file.path`

The file.path block configures the file.path resource attribute.

Name	Type	Description	Default	Required
`enabled`	`boolean`	Whether to include the `file.path` resource attribute.	`false`	no

When enabled is true, the file.path attribute is included in all metrics. The children blocks metrics_include and metrics_exclude can be used to further filter which metrics are given the file.path attribute. If a given metric matches all the metrics_include blocks and none of the metrics_exclude blocks, the file.path attribute is added.

Exported fields

otelcol.receiver.file_stats doesn’t export any fields.

Component health

otelcol.receiver.file_stats is reported as unhealthy when:

It’s given an invalid configuration.
It runs on an unsupported operating system.

Debug information

otelcol.receiver.file_stats doesn’t expose any component-specific debug information.

Example

This example forwards file stats of files and folders with the .log extension in /var/log through a batch processor before finally sending it to an OTLP-capable endpoint:

otelcol.receiver.file_stats "default" {
  include = "/var/log/**/*.log"

  output {
    metrics = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    metrics = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = sys.env("OTLP_ENDPOINT")
  }
}

Compatible components

otelcol.receiver.file_stats can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.filelog

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.filelog`

Public preview: This is a public preview component. Public preview components are subject to breaking changes, and may be replaced with equivalent functionality that cover the same use case. To enable and use a public preview component, you must set the stability.level flag to public-preview or below.

otelcol.receiver.filelog reads log entries from files and forwards them to other otelcol.* components.

Note
otelcol.receiver.filelog is a wrapper over the upstream OpenTelemetry Collector filelog receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.receiver.filelog components by giving them different labels.

Usage

otelcol.receiver.filelog "<LABEL>" {
  include = [...]
  output {
    logs    = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.filelog:

Name	Type	Description	Default	Required
`include`	`list(string)`	A list of glob patterns to include files.		yes
`acquire_fs_lock`	`bool`	Whether to acquire a file system lock while reading the file (Unix only).	`false`	no
`attributes`	`map(string)`	A map of attributes to add to each log entry.	`{}`	no
`compression`	`string`	The compression type used for the log file.	``	no
`delete_after_read`	`bool`	Whether to delete the file after reading.	`false`	no
`encoding`	`string`	The encoding of the log file.	`"utf-8"`	no
`exclude_older_than`	`duration`	Exclude files with a modification time older than the specified duration.	`"0s"`	no
`exclude`	`list(string)`	A list of glob patterns to exclude files that would be included by the `include` patterns.	`[]`	no
`fingerprint_size`	`units.Base2Bytes`	The size of the fingerprint used to detect file changes.	`1KiB`	no
`force_flush_period`	`duration`	The period after which logs are flushed even if the buffer isn’t full.	`"500ms"`	no
`include_file_name_resolved`	`bool`	Whether to include the resolved filename in the log entry.	`false`	no
`include_file_name`	`bool`	Whether to include the filename in the log entry.	`true`	no
`include_file_owner_group_name`	`bool`	Whether to include the file owner’s group name in the log entry.	`false`	no
`include_file_owner_name`	`bool`	Whether to include the file owner’s name in the log entry.	`false`	no
`include_file_path_resolved`	`bool`	Whether to include the resolved file path in the log entry.	`false`	no
`include_file_path`	`bool`	Whether to include the file path in the log entry.	`false`	no
`include_file_record_number`	`bool`	Whether to include the file record number in the log entry.	`false`	no
`max_batches`	`int`	The maximum number of batches to process concurrently.	`10`	no
`max_concurrent_files`	`int`	The maximum number of files to read concurrently.	`10`	no
`max_log_size`	`units.Base2Bytes`	The maximum size of a log entry.	`1MiB`	no
`operators`	`list(map(string))`	A list of operators used to parse the log entries.	`[]`	no
`poll_interval`	`duration`	The interval at which the file is polled for new entries.	`"200ms"`	no
`preserve_leading_whitespaces`	`bool`	Preserves leading whitespace in messages when set to `true`.	`false`	no
`preserve_trailing_whitespaces`	`bool`	Preserves trailing whitespace in messages when set to `true`.	`false`	no
`resource`	`map(string)`	A map of resource attributes to associate with each log entry.	`{}`	no
`start_at`	`string`	The position to start reading the file from.	`"end"`	no
`storage`	`capsule(otelcol.Handler)`	Handler from an `otelcol.storage` component to use for persisting state.		no

encoding must be one of utf-8, utf8-raw, utf-16le, utf-16be, ascii, big5, or nop. Refer to the upstream receiver documentation for more details.

start_at must be one of beginning or end. The header block may only be used if start_at is beginning.

compression must be either "", gzip, or auto. auto automatically detects file compression type and ingests data. Currently, only gzip compressed files are auto detected. This allows for mix of compressed and uncompressed files to be ingested with the same filelogreceiver.

To persist state between restarts of the Alloy process, set the storage attribute to the handler exported from an otelcol.storage.* component.

`operators`

The operators list is a list of stanza operators that transform the log entries after they have been read.

For example, if container logs are being collected you may want to utilize the stanza container parser operator to add relevant attributes to the log entries.

otelcol.receiver.filelog "default" {
    ...
    operators = [
      {
        type = "container"
      }
    ]
}

Blocks

You can use the following blocks with otelcol.receiver.filelog:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

`header`

The header block configures logic for parsing a log header line into additional attributes added to each log entry. It may only be used when start_at is set to beginning. The following arguments are supported:

Name	Type	Description	Default	Required
`metadata_operators`	`lists(map(string)`	A list of operators used to parse metadata from the header.		yes
`pattern`	`string`	A regular expression that matches the header line.		yes

If a header block isn’t set, no log lines will be treated as header metadata.

The metadata_operators list is a list of stanza operators that parses metadata from the header. Any attributes created from the embedded operators pipeline will be applied to all log entries in the file.

For example, you might use a regex_parser to process a header line that has been identified by the pattern expression. The following example shows a fictitious header line, and then the header block that would parse an environment attribute from it.

HEADER_IDENTIFIER env="production"
...

otelcol.receiver.filelog "default" {
    ...
    header {
      pattern = '^HEADER_IDENTIFIER .*$'
      metadata_operators = [
        {
          type = "regex_parser"
          regex = 'env="(?P<environment>.+)"'
        }
      ]
    }
}

`multiline`

The multiline block configures logic for splitting incoming log entries. The following arguments are supported:

Name	Type	Description	Default	Required
`line_end_pattern`	`string`	A regular expression that matches the end of a log entry.		yes*
`line_start_pattern`	`string`	A regular expression that matches the beginning of a log entry.		yes*
`omit_pattern`	`bool`	Omit the start/end pattern from the split log entries.	`false`	no

A multiline block must contain either line_start_pattern or line_end_pattern.

If a multiline block isn’t set, log entries won’t be split.

`ordering_criteria`

The ordering_criteria block configures the order in which log files discovered will be processed. The following arguments are supported:

Name	Type	Description	Default	Required
`group_by`	`string`	A named capture group from the `regex` attribute used for grouping pre-sort.	`""`	no
`regex`	`string`	A regular expression to capture elements of log files to use in ordering calculations.	`""`	no
`top_n`	`int`	The number of top log files to track when using file ordering.	`1`	no

`sort_by`

The sort_by repeatable block configures the way the fields parsed in the ordering_criteria block will be applied to sort the discovered log files. The following arguments are supported:

Name	Type	Description	Default	Required
`sort_type`	`string`	The type of sorting to apply.		yes
`ascending`	`bool`	Whether to sort in ascending order.	`true`	no
`layout`	`string`	The layout of the timestamp to be parsed from a named `regex` capture group.	`""`	no
`location`	`string`	The location of the timestamp.	`"UTC"`	no
`regex_key`	`string`	The named capture group from the `regex` attribute to use for sorting.	`""`	no

sort_type must be one of numeric, lexicographic, timestamp, or mtime. When using numeric, lexicographic, or timestamp sort_type, a named capture group defined in the regex attribute in ordering_criteria must be provided in regex_key. When using mtime sort_type, the file’s modified time will be used to sort.

The location and layout arguments are only applicable when sort_type is timestamp.

The location argument specifies a Time Zone identifier. The available locations depend on the local IANA Time Zone database. Refer to the list of tz database time zones in Wikipedia for a non-comprehensive list.

`retry_on_failure`

The retry_on_failure block configures the retry behavior when the receiver encounters an error downstream in the pipeline. A backoff algorithm is used to delay the retry upon subsequent failures. The following arguments are supported:

Name	Type	Description	Default	Required
`enabled`	`bool`	If set to `true` and an error occurs, the receiver will pause reading the log files and resend the current batch of logs.	`false`	no
`initial_interval`	`duration`	The time to wait after first failure to retry.	`"1s"`	no
`max_elapsed_time`	`duration`	The maximum age of a message before the data is discarded.	`"5m"`	no
`max_interval`	`duration`	The maximum time to wait after applying backoff logic.	`"30s"`	no

If max_elapsed_time is set to 0 data is never discarded.

Exported fields

otelcol.receiver.filelog doesn’t export any fields.

Component health

otelcol.receiver.filelog is only reported as unhealthy if given an invalid configuration.

Debug metrics

otelcol.receiver.filelog doesn’t expose any component-specific debug metrics.

Example

This example reads log entries using the otelcol.receiver.filelog receiver and they’re logged by a otelcol.exporter.debug component. It expects the logs to start with an ISO8601 compatible timestamp and parses it from the log using the regex_parser operator.

otelcol.receiver.filelog "default" {
  include = ["/var/log/*.log"]
  operators = [{
    type = "regex_parser",
    regex = "^(?P<timestamp>\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3,6}Z)",
    timestamp = {
      parse_from = "attributes.timestamp",
      layout = "%Y-%m-%dT%H:%M:%S.%fZ",
      location = "UTC",
    },
  }]
  output {
      logs = [otelcol.exporter.debug.default.input]
  }
}

otelcol.exporter.debug "default" {}

Compatible components

otelcol.receiver.filelog can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.fluentforward

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.fluentforward`

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement. To enable and use an experimental component, you must set the stability.level flag to experimental.

otelcol.receiver.fluentforward accepts log messages over a TCP connection via the Fluent Forward Protocol and forwards them as logs to other otelcol.* components.

Note
otelcol.receiver.fluentforward is a wrapper over the upstream OpenTelemetry Collector fluentforward receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.receiver.fluentforward components by giving them different labels.

Usage

otelcol.receiver.fluentforward "<LABEL>" {
  endpoint = "<IP_ADDRESS:PORT>"

  output {
    logs    = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.fluentforward:

Name	Type	Description	Default	Required
`endpoint`	`string`	The `<HOST:PORT>` or `unix://<path to socket>` address to listen to for logs messages.		yes

Blocks

You can use the following blocks with otelcol.receiver.fluentforward:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no

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

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

otelcol.receiver.fluentforward doesn’t export any fields.

Component health

otelcol.receiver.fluentforward is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.fluentforward doesn’t expose any component-specific debug information.

Debug metrics

otelcol.receiver.fluentforward doesn’t expose any component-specific debug metrics.

Example

This example receives log messages using Fluent Forward Protocol on TCP port 8006 and logs them.

otelcol.receiver.fluentforward "default" {
    endpoint = "localhost:8006"
    output {
        logs = [otelcol.exporter.debug.default.input]
    }
}

otelcol.exporter.debug "default" {}

Compatible components

otelcol.receiver.fluentforward can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

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.

otelcol.receiver.googlecloudpubsub

Mon, 13 Apr 2026 07:37:47 +0000

`otelcol.receiver.googlecloudpubsub`

Community: This component is developed, maintained, and supported by the Alloy user community. Grafana doesn’t offer commercial support for this component. To enable and use community components, you must set the --feature.community-components.enabled flag to true.

Refer to Community components for more information.

otelcol.receiver.googlecloudpubsub receives OpenTelemetry signals from a Google Cloud Pub/Sub subscription and forwards them to other otelcol.* components for processing or export.

Note
otelcol.receiver.googlecloudpubsub is a wrapper over the upstream OpenTelemetry Collector googlecloudpubsub receiver. Bug reports or feature requests will be redirected to the upstream repository, if necessary.

You can specify multiple otelcol.receiver.googlecloudpubsub components by giving them different labels.

Usage

otelcol.receiver.googlecloudpubsub "<LABEL>" {
  subscription = "projects/<PROJECT-ID>/subscriptions/<SUBSCRIPTION-NAME>"

  output {
    logs = [...]
    metrics = [...]
    trace = [...]
  }
}

Arguments

You can use the following arguments with otelcol.receiver.googlecloudpubsub:

Name	Type	Description	Default	Required
`subscription`	`string`	The subscription name to receive OTLP data from. The subscription name should be a fully qualified resource name, for example: `projects/otel-project/subscriptions/otlp`.	`""`	yes
`compression`	`string`	The compression used on data received from the subscription. Only `gzip` is supported. This is only used when no content-encoding attribute is present.	`""`	no
`encoding`	`string`	The encoding used to receive data from the subscription. This can either be `otlp_proto_trace`, `otlp_proto_metric`, `otlp_proto_log` or an encoding extension. This is only used when no media type attribute is present.	`""`	no
`endpoint`	`string`	Override the default Pub/Sub endpoint. This is useful when connecting to the Pub/Sub emulator instance or switching between global and regional service endpoints.	`""`	no
`ignore_encoding_error`	`bool`	Ignore errors when the configured encoder fails to decode Pub/Sub messages. Ignoring the error causes the receiver to drop the message.	false	no
`insecure`	`bool`	Allows performing insecure SSL connections and transfers. This is useful when connecting to a local emulator instance. Only has effect if you set `endpoint`.	false	no
`project`	`string`	The Google Cloud Project project identifier.	`""`	no
`timeout`	`Duration`	Timeout for calls to the Pub/Sub API.	`"12s"`	no

Blocks

You can use the following blocks with otelcol.receiver.googlecloudpubsub:

Block	Description	Required
`client_auth`	Configures client authentication credentials for exporters.	no
`debug_metrics`	Configures the metrics that this component generates to monitor its state.	no
`htpasswd`	Configures server authentication using htpasswd format for receivers.	no

`output`

Required

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

The following arguments are supported:

Name	Type	Description	Default	Required
`logs`	`list(otelcol.Consumer)`	List of consumers to send logs to.	`[]`	no
`metrics`	`list(otelcol.Consumer)`	List of consumers to send metrics to.	`[]`	no
`traces`	`list(otelcol.Consumer)`	List of consumers to send traces to.	`[]`	no

`debug_metrics`

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

The following arguments are supported:

Name	Type	Description	Default	Required
`disable_high_cardinality_metrics`	`boolean`	Whether to disable certain high cardinality metrics.	`true`	no

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

Exported fields

otelcol.receiver.googlecloudpubsub doesn’t export any fields.

Component health

otelcol.receiver.googlecloudpubsub is only reported as unhealthy if given an invalid configuration.

Debug information

otelcol.receiver.googlecloudpubsub doesn’t expose any component-specific debug information.

Example

The following example collects signals from Google Cloud Pub/Sub subscription and forwards logs through a batch processor:

otelcol.receiver.googlecloudpubsub "default" {
  subscription = "projects/my-gcp-project/subscriptions/my-pubsub-subscription"

  output {
    logs = [otelcol.processor.batch.default.input]
  }
}

otelcol.processor.batch "default" {
  output {
    logs = [otelcol.exporter.otlphttp.default.input]
  }
}

otelcol.exporter.otlphttp "default" {
  client {
    endpoint = env("<OTLP_ENDPOINT>")
  }
}

Compatible components

otelcol.receiver.googlecloudpubsub can accept arguments from the following components:

Components that export OpenTelemetry otelcol.Consumer

otelcol.receiver.googlecloudpubsub has exports that can be consumed by the following components:

Components that consume OpenTelemetry otelcol.Consumer

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.