Prepare a reproducible migration fixture
This playbook is for a service owner upgrading OpenTelemetry semantic conventions, not for an incident commander searching every available signal. Start with a sanitized before-change log, the current instrumentation or Collector snippet, a representative request that crosses at least two services, and the convention versions on both sides. Run structured-log-analyzer to identify fields already present. If the sample is logfmt, use logfmt-to-json-structured-log-bridge to expose quoted values, coercion and duplicate keys before comparing attributes; a JSON log does not need that detour. Remove personal or secret data before sharing fixtures. The pii-log-redaction workflow is the boundary for a full disclosure review.
Separate renameable fields from design changes
Run otel-semantic-convention-migration-tool on a copy of the relevant code, Collector configuration or dashboard JSON. Record the source and target version, proposed renames, removed attributes and anything unmapped. Its output is a proposed migration, not an automatic production deployment. A field such as http.target may require a deliberate split into path and query rather than a mechanical rename. Decide those cases with service owners, then deploy the reviewed change through the usual pipeline. Comparing only the count of renamed fields is not enough: a dashboard query or collector transform can still reference an old attribute.
Prove continuity with headers and a real export
Feed representative W3C traceparent, tracestate, baggage and OTLP export headers to opentelemetry-w3c-traceparent-tracestate-baggage-and-otlp-protobuf-headers-propagation-validator. Check that a downstream hop keeps the trace-id while using a different nonzero span-id. Valid headers do not prove that instrumentation actually emitted spans, so inspect a post-change JSON export with distributed-trace-decoder-waterfall-visualizer. Compare expected service hops, parent-child order, error spans and durations; write down any missing span rather than filling the gap with assumptions.
Tie the result to an explicit release gate
If the release has a latency objective, use api-latency-budget-planner to compare the observed stage durations with the pre-agreed allocations. A single trace suggests where time went, not a statistically valid P99. The acceptance note should contain the fixture version, attribute diff, header check, trace evidence, missing or unmapped fields, and any budget exception. If the original need is incident response or API payload replay rather than planned instrumentation migration, switch to observability-debugging or api-request-replay-and-debugging respectively.