Course contentsShow
← System Design
Lesson 1225 of 1,91931. Observability: TracingFree lesson

Span Attributes and Tags

Enriching spans with metadata like HTTP status codes, database queries, or user IDs for debugging context.

Span Attributes and Tags

What you'll learn: How to enrich distributed tracing spans with contextual metadata that makes debugging and analysis dramatically easier.

The Core Idea

A span represents a unit of work in your distributed system, but by itself it only tells you "something happened between time X and time Y." That's not enough for meaningful debugging. Span attributes (also called tags or labels) let you attach key-value metadata to spans, transforming them from skeletal timing information into rich, searchable debugging narratives.

Think of a span like a police report. The timestamps tell you when something happened, but the attributes are the witness statements, physical evidence, and contextual details that help you understand what actually occurred.

What to Include as Attributes

Common attributes that add tremendous debugging value include:

  • HTTP context: http.status_code=500, http.method=POST, http.url=/api/users
  • Database operations: db.statement=SELECT * FROM users WHERE id=?, db.system=postgresql
  • User context: user.id=12345, user.role=admin
  • Business domain: order.id=abc-123, payment.method=credit_card
  • Error information: error=true, error.message=Connection timeout

These attributes let you filter, group, and search traces. Instead of manually scanning hundreds of traces, you can query: "Show me all spans where http.status_code >= 500 and db.system=mysql."

Avoiding Common Pitfalls

Keep cardinality reasonable—don't use attributes with unbounded unique values like raw SQL queries with literal values or unique timestamps. Use parameterized versions instead.

Key Takeaway: Span attributes transform raw timing data into searchable, contextual narratives by attaching metadata like HTTP status codes, database queries, and user IDs—making it possible to quickly isolate and understand failures in distributed systems.