Documentation 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

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:

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.

output

debug_metrics

exclude

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.

attribute

library

regexp

resource

include

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.

name

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’s not used with to-attributes.

to_attributes

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 regular expression pattern string.

1. The span name is checked against each regular expression in the list.
2. If it matches, then all named subexpressions of the regular expression 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’re specified.
7. 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:

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:

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.

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 changes 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 won’t change the span name. This is because the attribute key operation isn’t set:

JSON Copy

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

Create 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 changes the span name to "locationget1234":

JSON Copy

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

Rename a span name and adding attributes

Example input and output using the configuration below:

1. Assume the 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]
  }
}

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

alloy Copy

otelcol.processor.span "keep_original_name" {
  name {
    to_attributes {
      keep_original_name = true
      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 isn’t 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]
  }
}

Set 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]
  }
}

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.

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