Span Attributes and Tags
What you'll learn: How to enrich spans with metadata that makes your distributed traces searchable, filterable, and useful for debugging.
The Core Idea
In distributed tracing, a span represents a unit of work (like a function call or HTTP request). On its own, a span tells you what happened and when. Span attributes (also called tags in some systems) are key-value pairs you attach to spans that answer questions like how, who, what parameters, and what outcome.
Think of a span as a shipping package. The basic tracking tells you when it left the warehouse and when it arrived. Attributes are like the detailed labels: weight, destination city, fragile/non-fragile, contents description. Without those labels, finding "all fragile packages sent to Boston" would be impossible.
Why Attributes Matter
Attributes transform raw traces into a powerful debugging tool:
- Filtering: Find all spans where
http.status_code=500oruser.id=12345 - Contextual debugging: See that a slow database query had
db.statement="SELECT * FROM users"anddb.rows_returned=50000 - Root cause analysis: Identify patterns like "all errors happen when
region=us-east-1"
Common Attribute Categories
Standard semantic conventions define common attributes:
- HTTP:
http.method,http.status_code,http.url - Database:
db.system,db.statement,db.operation - Infrastructure:
service.name,service.version,host.name - Custom business logic:
user.id,order.total,cart.item_count
Attributes live within the span context you've been propagating, enriching each span with meaningful metadata without breaking the trace flow.
Key Takeaway: Span attributes are the metadata labels that transform basic "what happened" traces into searchable, filterable records that reveal why and under what conditions operations succeeded or failed.