Field notes: trace naming that survives refactors

Span names are not tattoos, but teams treat them that way. In Distributed tracing labs this quarter, the diffs that sailed through review shared a boring trait: they described work units, not file paths. A span called checkout.validate.payment is easier to deprecate than one named after a class that will move packages next month.

We also saw fewer arguments when teams adopted a short verb list: validate, persist, enqueue, fetch. Verbs are not laws of nature; they are guardrails so humans scanning traces do not invent a fresh vocabulary per service. The boring list wins because it keeps muscle memory aligned across repositories owned by different squads.

If you inherit a trace forest that already smells poetic, rename in slices. Ship one service boundary at a time, document the mapping in the runbook stub, and give reviewers a screenshot of before and after. The cohort capstone rewards that kind of patient diff over sweeping renames that look heroic in week one and cruel in week four.

We keep field notes short on purpose. Longer walkthroughs with diagrams live in the community forum threads tagged tracing-hygiene.