Skip to content

feat(tracing): validate spans mapper against live Transaction Search - #73

Merged
gibbsie merged 1 commit into
mainfrom
feat/spans-trace-backend
Aug 14, 2026
Merged

feat(tracing): validate spans mapper against live Transaction Search#73
gibbsie merged 1 commit into
mainfrom
feat/spans-trace-backend

Conversation

@gibbsie

@gibbsie gibbsie commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Summary

The spans mapper was written against unverified assumptions; this change validates and corrects it against a raw span sample captured from the live account (OTel-shaped events: resource attributes traceld, spanId/parentSpanId, *UnixNano timestamps, status.code, _aws.xray envelope, subsegments arriving as separate events).

  • utils/spans-waterfall.ts - annotation attributes resolved via annotation_keys enumeration; _aws.xray envelope fallbacks for name/namespace/cause; UnixNano→seconds conversion; flat-subsegment reassembly via parentSpanId with in-progress/completed dedup.
  • utils/trace-span-query.ts, utils/spans-query.ts - query filter fields aligned to the attributes.* locations observed in real spans.
  • trace-query-handler.ts - wiring for the above.
  • All four test suites rebuilt on the verbatim captured sample shape instead of synthetic fixtures.

Testing

  • tsc --noEmit: clean; eslint: clean.
  • Full backend Jest suite: 6,344 passed / 0 failed (421 suites)
  • The 4 modified suites re-verified on the committed tree: 107/107.
  • Live end-to-end queries are deliberately deferred to cutover (see below).

Not in this PR (deliberate)

TRACE_BACKEND remains xray. The flip to spans is an env-only change on the telemetry stack applied at deploy time - deploys are manual in this repo, so merging this does not change runtime behavior. Cutover procedure and live verification: docs/TRACING_RUNBOOK.md. Follow-up after verified cutover: remove the xray:Get* IAM grant and flip the pinned telemetry test to assert its absence.

Known gaps (minor, non-blocking)

  • status.code = OK was not observed in the captured sample; mapping is defensive but unconfirmed against live data.
  • Exception-type extraction has no _aws.xray cause fallback yet.
  • normalizeToSpansTraceId has behavioral-only test coverage.

@gibbsie
gibbsie merged commit 837a4f8 into main Aug 14, 2026
14 checks passed
@gibbsie
gibbsie deleted the feat/spans-trace-backend branch August 14, 2026 22:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant