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

otelcol.processor.span doesn’t support any arguments.

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

Required

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

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

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

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:

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:

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:

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:

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