Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components otelcol otelcol.processor.span

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.

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

Usage

alloy Copy

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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.

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:

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 Copy

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 Copy

{
  "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 Copy

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

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

alloy Copy

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 Copy

{
  "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 Copy

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 Copy

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 Copy

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 Copy

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:

• 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