---
title: "otelcol.processor.span | Grafana Alloy documentation"
description: "Learn about 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.

> Note
> 
> `otelcol.processor.span` is a wrapper over the upstream OpenTelemetry Collector [`span`](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.147.0/processor/spanprocessor) 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 ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
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`:

No valid configuration blocks found.

If both an `include` block and an `exclude`block 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:

Expand table

| Name     | Type                     | Description                          | Default | Required |
|----------|--------------------------|--------------------------------------|---------|----------|
| `traces` | `list(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`

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

The following arguments are supported:

Expand table

| Name                               | Type      | Description                                          | Default | Required |
|------------------------------------|-----------|------------------------------------------------------|---------|----------|
| `disable_high_cardinality_metrics` | `boolean` | Whether to disable certain high cardinality metrics. | `true`  | no       |

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

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

### `exclude`

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

The following arguments are supported:

Expand table

| Name         | Type           | Description                                          | Default | Required |
|--------------|----------------|------------------------------------------------------|---------|----------|
| `match_type` | `string`       | Controls how items to match against are interpreted. |         | yes      |
| `services`   | `list(string)` | A list of items to match the service name against.   | `[]`    | no       |
| `span_kinds` | `list(string)` | A list of items to match the span kind against.      | `[]`    | no       |
| `span_names` | `list(string)` | A list of items to match the span name 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`]\[attribute], \[`resource`]\[resource], or \[`library`]\[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:

Expand table

| Name    | Type     | Description                           | Default | Required |
|---------|----------|---------------------------------------|---------|----------|
| `key`   | `string` | The attribute key.                    |         | yes      |
| `value` | `any`    | The attribute value to match against. |         | no       |

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:

Expand table

| Name      | Type     | Description                   | Default | Required |
|-----------|----------|-------------------------------|---------|----------|
| `name`    | `string` | The attribute key.            |         | yes      |
| `version` | `string` | The version to match against. | null    | no       |

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:

Expand table

| Name                    | Type   | Description                                                           | Default | Required |
|-------------------------|--------|-----------------------------------------------------------------------|---------|----------|
| `cache_enabled`         | `bool` | Determines whether match results are LRU cached.                      | `false` | no       |
| `cache_max_num_entries` | `int`  | The max number of entries of the LRU cache that stores match results. | `0`     | no       |

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:

Expand table

| Name    | Type     | Description                          | Default | Required |
|---------|----------|--------------------------------------|---------|----------|
| `key`   | `string` | The resource key.                    |         | yes      |
| `value` | `any`    | The resource value to match against. |         | no       |

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`]\[name] and \[`status`]\[status] blocks based on the properties of a span.

The following arguments are supported:

Expand table

| Name         | Type           | Description                                          | Default | Required |
|--------------|----------------|------------------------------------------------------|---------|----------|
| `match_type` | `string`       | Controls how items to match against are interpreted. |         | yes      |
| `services`   | `list(string)` | A list of items to match the service name against.   | `[]`    | no       |
| `span_kinds` | `list(string)` | A list of items to match the span kind against.      | `[]`    | no       |
| `span_names` | `list(string)` | A list of items to match the span name 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`]\[attribute], \[`resource`]\[resource], or \[`library`]\[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:

Expand table

| Name              | Type           | Description                                                      | Default | Required |
|-------------------|----------------|------------------------------------------------------------------|---------|----------|
| `from_attributes` | `list(string)` | Attribute keys to pull values from, to generate a new span name. | `[]`    | no       |
| `separator`       | `string`       | Separates attributes values in the new span name.                | `""`    | no       |

Firstly `from_attributes` rules are applied, then \[`to-attributes`]\[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].

### `to_attributes`

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

The following attributes are supported:

Expand table

| Name                 | Type           | Description                                                                     | Default | Required |
|----------------------|----------------|---------------------------------------------------------------------------------|---------|----------|
| `rules`              | `list(string)` | A list of regular expression rules to extract attribute values from span name.  |         | yes      |
| `break_after_match`  | `bool`         | Configures if processing of rules should stop after the first match.            | `false` | no       |
| `keep_original_name` | `bool`         | Configures if the original span name should be kept after processing the rules. | `false` | no       |

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:

Expand table

| Name          | Type     | Description                                       | Default | Required |
|---------------|----------|---------------------------------------------------|---------|----------|
| `code`        | `string` | A status code.                                    |         | yes      |
| `description` | `string` | An 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`.

## Exported fields

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

Expand table

| Name    | Type               | Description                                                      |
|---------|--------------------|------------------------------------------------------------------|
| `input` | `otelcol.Consumer` | A 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 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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

  output {
      traces = [otelcol.exporter.otlphttp.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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

### Create a new span name from attribute values (no separator)

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

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

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

JSON ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```json
{
  "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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
otelcol.processor.span "default" {
  name {
    to_attributes {
      rules = ["^\\/api\\/v1\\/document\\/(?P<documentId>.*)\\/update$"]
    }
  }

  output {
      traces = [otelcol.exporter.otlphttp.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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```alloy
otelcol.processor.span "keep_original_name" {
  name {
    to_attributes {
      keep_original_name = true
      rules = [`^\/api\/v1\/document\/(?P<documentId>.*)\/update$`]
    }
  }

  output {
      traces = [otelcol.exporter.otlphttp.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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```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.otlphttp.default.input]
  }
}
```

### Set a status

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

Alloy ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

  output {
      traces = [otelcol.exporter.otlphttp.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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

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

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

## Compatible components

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

- Components that export [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-exporters)

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

- Components that consume [OpenTelemetry `otelcol.Consumer`](../../../compatibility/#opentelemetry-otelcolconsumer-consumers)

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