---
title: "Normalize span names with semantic conventions | Grafana Cloud documentation"
description: "Describes how Adaptive Traces rewrites span names to follow OpenTelemetry semantic conventions so that high-cardinality names collapse into a stable, queryable form."
---

# Normalize span names with semantic conventions

Adaptive Traces can rewrite span names to follow [OpenTelemetry semantic conventions](https://opentelemetry.io/docs/specs/semconv/) before traces are sampled and stored. This turns high-cardinality names like `/api/users/7f3a` into a stable form such as `GET /api/users/{id}`, so that aggregations, searches, and span metric generation behave consistently regardless of how each service chose to label its spans. Generated span metrics are especially sensitive to high cardinality because every unique name becomes its own time series.

Span name normalization is opt-in. When it’s enabled, Adaptive Traces processes each span during ingestion, replaces the span name, and preserves the original value in the `grafana.original_span_name` attribute so you can always recover it.

## What gets normalized

Normalization reads the semantic-convention attributes already present on each span (such as `http.request.method`, `http.route`, `db.system.name`, and `rpc.service`) and rewrites the span name to a canonical form. The following span kinds are covered:

Expand table

| Span kind       | Example normalized name |
|-----------------|-------------------------|
| HTTP server     | `GET /users/{id}`       |
| HTTP client     | `POST /orders`          |
| RPC server      | `UserService/GetUser`   |
| RPC client      | `UserService/GetUser`   |
| Messaging       | `publish orders`        |
| Database client | `SELECT users`          |

Spans that don’t have the attributes required for a given convention are left unchanged.

## How it works

1. Adaptive Traces observes each span as it’s ingested.
2. If the span matches one of the supported patterns, its name is rewritten using the attributes already on the span.
3. The original span name is copied into the `grafana.original_span_name` attribute, but only on spans that were actually rewritten.
4. The normalized span continues through the rest of the Adaptive Traces pipeline, including sampling policies, rate limiting, and storage, using its new name.

> Warning
> 
> Anything that depends on the original span name may need to be updated after you enable normalization. This includes sampling policies that match on span name (for example, OTTL conditions referencing `name`), TraceQL queries and saved Explore views, dashboard panels, alert rules, and derived span metrics. Review and update these before enabling normalization. Policies that match on span attributes such as `http.request.method` or `db.system.name` are not affected.

## Impact on stored traces

- **Span names in Tempo are the normalized values.** Queries, service graphs, and operation lists reflect the normalized form.
- **The original span name is preserved** in the `grafana.original_span_name` attribute on rewritten spans. You can always recover it through Explore or trace search.
- **Span attributes are not modified.** Only the span name changes.
- **Traces that don’t match a supported pattern are untouched**, and no `grafana.original_span_name` attribute is added.

## Enable normalization

1. Navigate to **Adaptive Traces**.
2. Open the **Overview** page.
3. Enable span name normalization.

The setting takes effect within a minute. Only spans ingested after that point are normalized; previously stored traces and metrics are not rewritten.

## Disable normalization

1. Navigate to **Adaptive Traces**.
2. Open the **Overview** page.
3. Disable span name normalization.

Span names ingested after normalization is disabled are stored as-is. Previously normalized traces are not reverted.