Span Attributes
Span attributes are structured key-value metadata on spans — user id, tenant, cache hit, retry count — that turn traces from timings into queryable records of what happened and why.
Definition
Span attributes are typed key-value pairs attached to a span, recording request-scoped context: identifiers, flags, sizes, outcomes. Standardized namespaces (OpenTelemetry semantic conventions) make attributes comparable across services, so fleet-wide queries on database system or row counts work uniformly.
Context and scope
Populated at instrumentation points — HTTP middleware, database drivers, queue consumers. Governed by schema conventions and cardinality budgets.
Common misconceptions
- Attributes are free-form labels — un-governed keys fragment into synonyms — userid, user_id, enduser.id — that defeat cross-service querying
- More attributes mean better observability — every high-cardinality attribute multiplies index size and retention cost; curation beats abundance
- Attributes only describe the span — attributes carry request context: they are how traces answer business questions, not just timing questions
Anti-patterns
- Stuffing full payloads, SQL text, and headers into attributes and blowing trace sizes and privacy budgets
- Using different attribute names per service for the same concept and losing fleet-wide queries
- Recording PII in attributes without redaction pipelines, leaking user data into observability stores
Related concepts
Related examples
Authoritative source
https://opentelemetry.io/docs/specs/otel/trace/semantic_conventions/span-attributes/
What it is
A span with only a name and duration is a stopwatch. Attributes make it a record: which tenant, which cache outcome, which retry attempt, which outcome branch. The difference is between knowing something was slow and knowing why.
How it works
Instrumentation sets attributes at well-defined points. Semantic conventions reserve namespaces — http, db, messaging, faas — with standard names and types. Custom namespaces cover domain concepts. Attributes propagate into the trace store where they become query dimensions; tail-based sampling policies can filter on them.
When to invest
Define the attributes your incidents actually query: tenant and user identifiers, feature flags, cache hit flags, retry counts, batch sizes. Standardize through conventions before divergence sets in.
Pitfalls
Cardinality: user id as an attribute on millions of traces is indexable in tracing systems but unaffordable as metric labels — know which store you are feeding. Payload capture bloats spans past transport limits and drags secrets into retention. Schema drift between teams silently breaks the cross-service queries that justified the investment.