This is documentation for the next version of Agent. For the latest stable release, go to the latest version.

Documentation Grafana Agent Flow mode Reference Components reference otelcol.processor.span

otelcol.processor.span

EXPERIMENTAL: This is an experimental component. Experimental components are subject to frequent breaking changes, and may be removed with no equivalent replacement.

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

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

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.

river 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 Flow 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 Flow 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)

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

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

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

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

river 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