Skip to main content
In this lesson we cover span attributes: what they are, why they matter, and how to use them effectively with OpenTelemetry. Span attributes are key-value pairs attached to individual spans to provide contextual metadata about the operation being tracked. Without attributes, a span is essentially a timestamped name; attributes make spans rich, searchable, and actionable for filtering, debugging, aggregation, and alerting.
The image is a diagram about "Span Attributes," describing them as key-value pairs attached to spans. It highlights two points: carrying metadata about the operation being tracked, and enriching spans with contextual information.
Why use span attributes?
  • Provide business context (order IDs, payment types) that makes traces searchable.
  • Improve debugging by attaching relevant runtime details to an operation.
  • Enable fine-grained alerting and aggregation (e.g., only alert on errors for a specific payment method).
  • Support metric generation by aggregating attribute values across spans.
Example: e-commerce order processing
  • Add order_id, payment_method, or inventory_status to the process_order span.
  • Use these attributes to filter traces (for example, all spans where payment_method is "Credit Card"), or to group and analyze failures for specific products.
The image illustrates "Span Attributes" showing an example of attributes such as order ID, customer ID, payment method, and inventory status used to enrich spans for filtering, alerts, and analysis.
Span attributes power trace filtering, aggregation, and targeted alerts. For example, you can configure your observability backend to surface exceptions only for spans related to credit card payments if it supports slicing trace data by attributes.
The image describes the importance of span attributes, highlighting trace filtering, aggregation, and alerting with corresponding icons.
Types of attributes to capture
  • Business data: order_id, payment_method, product_sku
  • User data: user_id, account_tier
  • Technical data: http.status_code, db.system, cache hit/miss
Combining these categories provides a 360-degree view of what occurred in a span and enables both technical troubleshooting and business analytics.
The image illustrates the concept of exposing business, user, and technical metadata with a graphic showing a person using a laptop, surrounded by a cloud and various devices. It is titled "Importance of Span Attributes."
Attributes are especially valuable for modeling the lifecycle of business processes. For example, a process_order span that contains order_id, payment_method, and inventory_status lets you filter and debug fulfillment issues by order attributes.
The image shows a table with attributes related to e-commerce, including order ID, payment method, and inventory status with their corresponding values.
How to set attributes (Python example) Manual instrumentation is how you add business-focused attributes. With OpenTelemetry Python you obtain a span from the tracer and call set_attribute on the span object:
Use the span object’s set_attribute method (dot notation) to attach keys and values. Keys are strings and values must conform to supported types (see rules below). Add important attributes as early as possible so they are available for SDK-level sampling decisions.
The image illustrates the use of span attributes in e-commerce for tracing order life cycles, filtering orders by payment method, and debugging inventory fulfillment issues. The information is presented with a three-part circular diagram.
Attribute rules and best practices
RuleRecommendation
Key typeKeys must be non-null strings. Use concise, consistent naming.
Value typesValues may be string, boolean, integer, float, or arrays of these primitives.
Avoid nullsDo not record null values; omit attributes when the value is unknown.
Key namingPrefer short, stable keys; use semantic conventions for common technical attributes.
When to setAdd business-critical attributes early in execution to influence sampling and availability.
The image shows a set of attribute rules for key-value pairs, emphasizing non-null keys, specific data types for values, and guidance on adding attributes. There's also an illustration of a person standing next to a checklist.
Use semantic conventions (standardized attribute keys such as http.method, db.system, messaging.operation) where possible. These conventions promote consistency across services and make cross-system analysis easier.
Semantic attributes are predefined keys from the OpenTelemetry semantic conventions. Many auto-instrumentation libraries populate these automatically (for example, HTTP libraries add http.method, http.url, etc.), so you often do not need to add them manually. Use manual attributes for business-specific metadata (e.g., order_id, payment_method) to make traces searchable and filterable by business context. Summary — key takeaways
  • Span attributes are key-value metadata attached to spans to provide contextual, queryable information.
  • Keys must be non-null strings; values must be primitives (string, boolean, integer, float) or arrays of primitives.
  • Use semantic conventions for technical attributes; use manual instrumentation for business attributes.
  • Add attributes early so they are available to sampling and analysis.
  • Attributes enable trace filtering, aggregation, and more precise alerting based on business context.
The image lists five key takeaways related to span attributes, including guidelines on metadata, keys, business context, SDK rules, and trace management. The takeaways are presented in a sequential, numbered format.
Attributes are attached to individual spans and do not automatically propagate to child spans (unlike the trace ID). If you need to propagate key-value pairs across process boundaries or between spans, use baggage.
Span attributes are not propagated across spans. To propagate key-value pairs across process boundaries, use baggage instead.
Links and references

Watch Video