Menu
Grafana Cloud

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

alloy
otelcol.processor.span "LABEL" {
  output {
    traces  = [...]
  }
}

Arguments

otelcol.processor.span doesn’t support any arguments and is configured fully through inner blocks.

Blocks

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

HierarchyBlockDescriptionRequired
outputoutputConfigures where to send received telemetry data.yes
namenameConfigures how to rename a span and add attributes.no
name > to_attributesto-attributesConfiguration to create attributes from a span name.no
statusstatusSpecifies a status which should be set for this span.no
includeincludeFilter for data included in this processor’s actions.no
include > regexpregexpRegex cache settings.no
include > attributeattributeA list of attributes to match against.no
include > resourceresourceA list of items to match the resources against.no
include > librarylibraryA list of items to match the implementation library against.no
excludeexcludeFilter for data excluded from this processor’s actionsno
exclude > regexpregexpRegex cache settings.no
exclude > attributeattributeA list of attributes to match against.no
exclude > resourceresourceA list of items to match the resources against.no
exclude > librarylibraryA list of items to match the implementation library against.no
debug_metricsdebug_metricsConfigures the metrics that this component generates to monitor its state.no

The > symbol indicates deeper levels of nesting. For example, include > attribute refers to an attribute block defined inside an include block.

If both an include block and an excludeblock are specified, the include properties are checked before the exclude properties.

name block

The name block configures how to rename a span and add attributes.

The following attributes are supported:

NameTypeDescriptionDefaultRequired
from_attributeslist(string)Attribute keys to pull values from, to generate a new span name.[]no
separatorstringSeparates attributes values in the new span name.""no

Firstly from_attributes rules are applied, then 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 is not used with to-attributes.

to_attributes block

The to_attributes block configures how to create attributes from a span name.

The following attributes are supported:

NameTypeDescriptionDefaultRequired
ruleslist(string)A list of regex rules to extract attribute values from span name.yes
break_after_matchboolConfigures if processing of rules should stop after the first match.falseno

Each rule in the rules list is a regex pattern string.

  1. The span name is checked against each regex in the list.
  2. If it matches, then all named subexpressions of the regex are extracted as attributes and are added to the span.
  3. Each subexpression name becomes an attribute name and the subexpression matched portion becomes the attribute value.
  4. The matched portion in the span name is replaced by extracted attribute name.
  5. If the attributes already exist in the span then they will be overwritten.
  6. The process is repeated for all rules in the order they are specified.
  7. Each subsequent rule works on the span name that is the output after processing the previous rule.

break_after_match specifies if processing of rules should stop after the first match. If it is false, rule processing will continue to be performed over the modified span name.

status block

The status block specifies a status which should be set for this span.

The following attributes are supported:

NameTypeDescriptionDefaultRequired
codestringA status code.yes
descriptionstringAn 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.

include block

The include block provides an option to include data being fed into the name and status blocks based on the properties of a span.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
match_typestringControls how items to match against are interpreted.yes
serviceslist(string)A list of items to match the service name against.[]no
span_nameslist(string)A list of items to match the span name against.[]no
span_kindslist(string)A list of items to match the span kind 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, resource, or library must be specified with a non-empty value for a valid configuration.

exclude block

The exclude block provides an option to exclude data from being fed into the name and status blocks based on the properties of a span.

The following arguments are supported:

NameTypeDescriptionDefaultRequired
match_typestringControls how items to match against are interpreted.yes
serviceslist(string)A list of items to match the service name against.[]no
span_nameslist(string)A list of items to match the span name against.[]no
span_kindslist(string)A list of items to match the span kind 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, resource, or library must be specified with a non-empty value for a valid configuration.

regexp block

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:

NameTypeDescriptionDefaultRequired
cache_enabledboolDetermines whether match results are LRU cached.falseno
cache_max_num_entriesintThe max number of entries of the LRU cache that stores match results.0no

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.

attribute block

This block specifies an attribute to match against:

  • More than one attribute block can be defined.
  • 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:

NameTypeDescriptionDefaultRequired
keystringThe attribute key.yes
valueanyThe attribute value to match against.no

If value isn’t set, any value will match. The type of value could be a number, a string, or a boolean.

resource block

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:

NameTypeDescriptionDefaultRequired
keystringThe resource key.yes
valueanyThe resource value to match against.no

If value is not set, any value will match. The type of value could be a number, a string, or a boolean.

library block

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:

NameTypeDescriptionDefaultRequired
namestringThe attribute key.yes
versionstringThe version to match against.nullno

If version is unset, any version matches. If version is set to an empty string, it only matches a library version, which is also an empty string.

output block

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

The following arguments are supported:

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

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

debug_metrics block

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

The following arguments are supported:

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

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

Note

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

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

Exported fields

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

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

input accepts otelcol.Consumer OTLP-formatted data for traces telemetry signals. Logs and metrics are not supported.

Component health

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

Debug information

otelcol.processor.attributes does not expose any component-specific debug information.

Examples

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

alloy
otelcol.processor.span "default" {
  name {
    separator        = "::"
    from_attributes  = ["db.svc", "operation", "id"]
  }

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

For a span with the following attributes key/value pairs, the above configuration will change the span name to "location::get::1234":

json
{
  "db.svc": "location",
  "operation": "get",
  "id": "1234"
}

For a span with the following attributes key/value pairs, the above configuration will not change the span name. This is because the attribute key operation isn’t set:

json
{
  "db.svc": "location",
  "id": "1234"
}

Creating a new span name from attribute values (no separator)

alloy
otelcol.processor.span "default" {
  name {
    from_attributes = ["db.svc", "operation", "id"]
  }

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

For a span with the following attributes key/value pairs, the above configuration will change the span name to "locationget1234":

json
{
  "db.svc": "location",
  "operation": "get",
  "id": "1234"
}

Renaming a span name and adding attributes

Example input and output using the configuration below:

  1. Let’s assume input span name is /api/v1/document/12345678/update
  2. The span name will be changed to /api/v1/document/{documentId}/update
  3. A new attribute "documentId"="12345678" will be added to the span.
alloy
otelcol.processor.span "default" {
  name {
    to_attributes {
      rules = ["^\\/api\\/v1\\/document\\/(?P<documentId>.*)\\/update$"]
    }
  }

  output {
      traces = [otelcol.exporter.otlp.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 is not donot/change.
alloy
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.otlp.default.input]
  }
}

Setting a status

This example changes the status of a span to “Error” and sets an error description.

alloy
otelcol.processor.span "default" {
  status {
    code        = "Error"
    description = "some additional error description"
  }

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

Setting a status depending on an attribute value

This example sets the status to success only when attribute http.status_code is equal to 400.

alloy
otelcol.processor.span "default" {
  include {
    match_type = "strict"
    attribute {
      key   = "http.status_code"
      value = 400
    }
  }
  status {
    code = "Ok"
  }

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

Compatible components

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

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

Note

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