Attributs, événements et état des spans

A span knows its duration automatically, but raw timing is rarely enough. Enriching spans with attributes, events, and status makes traces tell a story.

Attributes are key-value pairs that add context to a span, like the route handled or the number of rows returned.

Prefer standard semantic-convention keys for common data so backends understand them. Use custom keys only for domain-specific context.

Like metric labels, avoid high-cardinality or huge values. Do not stuff entire payloads into an attribute.

• Good: order count, region
• Bad: full request body, raw stack trace as attribute

An event is a timestamped annotation inside a span marking something that happened at a moment, like a retry or cache miss.

Exceptions are recorded as a special event capturing the type, message, and stack, so failures show up in the trace timeline.

Status tells whether the operation succeeded. The default is Unset; set Error on failure so backends can highlight broken spans.

Recording an exception adds detail but does not by itself mark the span failed. Always also set the status to Error.

Use attributes for facts true for the whole span; use events for things that happen at a point in time within it.

Span names should be low cardinality, describing the operation type, not the specific instance. Put the variable part in attributes.

A diagnostic span has a clean name, a few bounded attributes, events for notable moments, and an accurate status.

You learned to enrich spans with bounded attributes (preferring semantic conventions), to mark point-in-time moments and failures with events and record_exception, and to set status to Error explicitly. Low-cardinality span names plus rich context turn traces into real diagnostics.