Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Adaptive Telemetrybreadcrumb arrow Adaptive Tracesbreadcrumb arrow Additional configurationbreadcrumb arrow Normalize span names
Grafana Cloud

Note

Span name normalization is currently in public preview. Grafana Labs offers limited support, and breaking changes might occur prior to the feature being made generally available.

Normalize span names with semantic conventions

Adaptive Traces can rewrite span names to follow OpenTelemetry semantic conventions 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:

Span kindExample normalized name
HTTP serverGET /users/{id}
HTTP clientPOST /orders
RPC serverUserService/GetUser
RPC clientUserService/GetUser
Messagingpublish orders
Database clientSELECT 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.