Align span queue attribute with OTel semconv (`queue` → `messaging.destination.name`)

[hardbyte]

Summary

Awa emits the queue name on spans under two different keys depending on which span you look at.

ADR-039 spans follow the OTel messaging semantic conventions and use messaging.destination.name (send {queue}, job.execute {kind}, and — since #450 — the dispatcher's receive {queue}). Everything else uses a bare queue attribute: the queue_storage.* spans (claim_runtime_batch, queue_counts, acquire_queue_claimer, …), some maintenance.* spans, and the dispatcher's own field.

The practical cost is that no single TraceQL predicate finds all spans for a queue. { span.messaging.destination.name = "email" } misses every storage span; { span.queue = "email" } misses the messaging ones. Anyone building a per-queue trace view has to write both.

Scope

Roughly 27 #[tracing::instrument] sites carry the bare form today:

File	Sites
awa-worker/src/dispatcher.rs	16
awa-model/src/queue_storage.rs	9
awa-worker/src/maintenance.rs	2

Options

1. Emit both — add messaging.destination.name alongside the existing queue on every span that has one. Nothing breaks; costs one duplicated attribute per span. Deprecate queue and drop it in a later minor.
2. Rename outright — replace queue with messaging.destination.name. Cleanest end state; silently breaks any saved TraceQL, Grafana trace panel, or Tempo metrics-generator rule keyed on span.queue.
3. Leave it — document the split in docs/grafana/README.md so people know to query both.

Option 1 is probably right if this happens at all: span names and attributes are not a compatibility surface under docs/stability.md (only metric names, types, and attribute keys are), so a rename is technically permitted — but users' saved queries are real, and the dual-emit path costs nothing but bytes.

Worth deciding alongside whether awa.* metric attributes should move the same way; the metrics surface is covered by the stability policy, so that half is a breaking change and a separate decision.

Notes

Not urgent and not a correctness issue. Surfaced while reviewing #450, which added the messaging conventions to the dispatcher's now-root poll span and made the inconsistency visible: the poll span carries both keys, so it is the one span that matches either query.

[hardbyte]

The dual-emit half of this landed in #450 as b0e666c — messaging.destination.name is now emitted alongside queue, on log events as well as spans:

Site	Count
queue_storage.* spans with a concrete queue	8
Log events (dispatcher 16, storage 1, maintenance 2)	19

{ span.messaging.destination.name = "email" } now matches the messaging spans and the storage spans together, and the same key is available on log records for Loki-side filtering. The bare queue key is unchanged, so existing queries keep working — nothing breaks.

Two deliberate exclusions: the bulk_move_failed_to_dlq and bulk_retry_from_dlq spans keep only queue, because theirs is an Option filter for a bulk operation rather than a destination (messaging.destination.name = None would be meaningless). And in the striped-claim warning, only the logical queue gets the mirror — stripe_queue is the physical stripe, and emitting both would put two identical keys on one event.

Remaining for this issue

1. Whether to drop the bare queue eventually, and on what deprecation schedule. Cheap to keep; the argument for dropping is only tidiness.
2. Metric attributes. awa.* metrics still use their own attribute keys, and metric names/types/attribute keys are a compatibility surface under docs/stability.md — so aligning those is a breaking change and needs its own decision, not a rider on this one.
3. Other attributes with semconv equivalents. job_id versus messaging.message.id (already on the job.execute span), and whether kind maps to anything standard — I'd guess not, since job kind is an awa concept rather than a messaging one.

Leaving this open for those three. The query-ability problem that prompted it is solved.

---

Generated by Claude Code