When should you use a span attribute versus a span event?

MCQ·Medium·4.0 · 0·~1 min·Asked atBrowserbase Razorpay Together Ai

Attempt it

**Attributes** and **events** are two slots OpenTelemetry gives you on every span. They look similar (both attach data to a span) but they have different jobs. **Attribute = property of the span.** It describes the span as a whole. Examples are `gen_ai.request.model = 'gpt-5.5'`, `user.id = 'abc-123'`, `http.response.status_code = 200`. The backend indexes attributes, so you can filter and group on them: 'show me all spans where model=gpt-5.5', 'group p99 latency by user tier'. **Event = something that happened during the span.** It is a time-ordered record nested inside the span timeline. Each event has its own timestamp and its own attributes. Examples: an individual chat message in a multi-turn call, a streamed-chunk arrival, a retry attempt firing, a tool call starting. In practice, anything you want to filter or group dashboards by goes in attributes. Anything that is one of many time-ordered records inside the span goes in events. Option B is correct. Option A is wrong (attributes for everything breaks the index and loses the time order that events keep). Option C is wrong (attributes are the dominant slot, not just for internals). Option D is wrong (the split is by purpose, not by data type).

**Attributes describe the span; events record occurrences within it.** - **Attribute**: key-value property of the span as a whole. Indexed by the observability backend. Use for anything you filter, group, or chart on: gen_ai.request.model, gen_ai.usage.input_tokens, user.id, session.id, http.response.status_code. - **Event**: time-ordered record inside the span. Each event has a timestamp, a name, and its own attribute payload. Use for things that happen one or many times during the span: individual chat messages, streamed chunks, retry firings, tool-call starts. The rule of thumb is **cardinality and orderedness**: - Low-cardinality, span-wide property → attribute. - Time-ordered, possibly many per span occurrence → event. **Why the split matters in practice:** - Putting per-message data into attributes explodes attribute cardinality and breaks indexes. Backends index attribute keys. If every chat message is its own attribute (`message.1`, `message.2`, ...), the index grows unbounded. - Putting span-wide properties into events loses indexability. You cannot filter 'spans where model=gpt-5.5' if model is hidden in an event payload. The backend does not index event contents the same way. **Concrete OTel GenAI mapping:** - **Attributes**: gen_ai.provider.name, gen_ai.request.model, gen_ai.operation.name, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.response.finish_reasons. - **Messages**: opt-in structured attributes gen_ai.system_instructions, gen_ai.input.messages and gen_ai.output.messages, or one gen_ai.client.inference.operation.details event. The OTel GenAI conventions do not use one key per message. Chat history goes in one structured value per direction, so the attribute set stays finite. Attributes carry the per-span metadata around it.

TL;DR

Attribute = property of the span (indexed, filterable). Event = time-ordered occurrence inside the span (model name attribute; streamed-chunk event).

Memory aid

Easy to grasp

Think of a single page in a diary about one day. The date, the weather, and the place at the top of the page are attributes. They describe the whole day, and you can flip through your diary by date or weather to find similar days. The bullet points down the page that say what happened at 9am and 11am and 3pm are events. They are time-ordered things that happened during the day. You would not put 'lunch at noon' in the page header, and you would not write the date next to every event line. The two slots have different jobs. Span attributes and span events split the same way.

Key concepts

Observability & Tracing

Concept explanation~2 min read

Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.

OpenTelemetry gives spans two ways to attach data: attributes and events. They are structurally similar (both are roughly key-value payloads on a span). But they exist for different purposes, and observability backends treat them differently. Confusing them is one of the most common instrumentation bugs in LLM applications. There, multi-message chats and streaming outputs make the choice feel ambiguous when it actually is not.

Mental model: attribute is an adjective describing the span. Event is a verb describing something that happened during the span. Backends index adjectives for fast filtering. They timestamp verbs for the span timeline view.

The definitions and the cardinality argument

Span attribute

It is a key-value property of the span as a whole. Each attribute has a key (gen_ai.request.model) and a value ('gpt-5.5'). The full set of attributes describes the span's static metadata: what it was, who triggered it, what it returned.

Attributes are indexed by the observability backend. That index is what makes filtering ('show me all chat spans where model=gpt-5.5') and grouping ('aggregate cost by user.tier') fast.

Span event

It is a time-ordered record nested inside the span timeline. Each event has its own timestamp, a name (gen_ai.client.inference.operation.details, retry.attempt), and an optional attribute payload. A span can have zero or many events, and their order is preserved.

Events are searchable but not pre-aggregated the same way attributes are. The span timeline view renders them as inline annotations.

The cardinality argument

Attribute keys live in the backend's index. The index has cost (memory, storage, query latency). Some backends cap or price by attribute-key cardinality.

Low-cardinality attribute keys (tens of distinct values across the system): cheap, fine.
High-cardinality attribute keys (millions of distinct values): expensive, often capped.
Unbounded attribute keys (new key per span, like message.1, message.2, ...): they break the index.

The rule that emerges: attributes should be span-wide and low to medium cardinality. Anything per-occurrence or unboundedly variable goes in events.

The indexability argument

In the other direction, events are not indexed for filtering the same way attributes are. Hiding model_name inside an event means you cannot filter dashboards by model. Putting everything in events is convenient ('it is more flexible'), but that convenience has a cost. The data is no longer queryable in the fast path.

How OTel GenAI semantic conventions apply the rule

Failure modes when the split is wrong

Practical patterns for tricky cases

Situations where this technique stops working.

2–4 min · Everything important, quickly.

Real products, models, and research that use this idea.

OpenTelemetry GenAI semantic conventions use attributes for per-span metadata and record chat history as opt-in structured attributes (gen_ai.input.messages, gen_ai.output.messages).
Langfuse, Arize Phoenix, and Datadog LLM Observability all index on attributes and render events on the span timeline.

What an interviewer would ask next. Try answering before peeking at the approach.

QHow would you record retry attempts on an LLM call?

Each retry is a time-ordered occurrence inside the parent span. Use events with names like retry.attempt and payload {attempt_number, error_code, backoff_ms}. Aggregate retry count as a custom derived attribute such as app.retry_count for filtering.

2 more follow-ups an interviewer would ask next. Sign in to reveal them.

Red flags & common mistakes

The phrases that signal junior thinking. Click to expand.

Most common mistake

Recording per-message data as attributes. Cardinality explodes and the index breaks. Messages belong in events.

60 second bullets to scan on the way to the call.

Definition of span attribute vs span event
Cardinality and indexing as the reason for the split

Primary sources. Browse if you want the original framing.