Span attributes (tags)
Searchable key-value details on a trace span, such as route, cache hit, or retry count, that explain why one operation behaved differently.
See it
What it is
Span attributes are key-value facts attached to one operation in a trace: the route template, cache hit, retry count, plan tier, or result size. OpenTelemetry calls them attributes; tracing products often call the same idea tags. They turn a timing waterfall into searchable data, so 'show slow checkout spans where cache_hit is false' becomes a query.
Add attributes that divide failures or latency into useful groups, and prefer OpenTelemetry semantic convention names when one exists. Put facts about the operation on the span and facts about the process, such as service.name and deployment.environment.name, on the resource so that every span receives them automatically. Record attributes before the span ends, because later updates will not reach the exporter.
Gotcha: attributes are indexed in many tracing backends, so unbounded values such as raw user IDs, full URLs, SQL text, and request bodies can explode cost and leak private data. Use route templates instead of raw paths, small enums instead of prose, and counts instead of whole collections. More tags are not more observability if nobody can safely query them.
Ask AI for it
Add useful OpenTelemetry span attributes to the manual spans in this codebase. Use Span.setAttribute and OTel semantic convention names where they exist. Attach the route template, operation name, cache hit, retry count, item count, result size, and a small plan-tier enum at the point where each value becomes known. Put service.name, service.version, and deployment.environment.name on the OpenTelemetry Resource instead of each span. Never attach email addresses, tokens, request bodies, raw URL paths, or SQL parameters, and add tests proving attributes are recorded before the span ends on both success and failure.