feat: add IHub.RecordTransaction to record completed transactions and spans

[jamescrosswell]

Overview

Draft to spitball the shape of an API for recording transactions/spans that completed elsewhere — e.g. work measured on another machine or process and replayed through a proxy, which is the use case in #2683.

Closes #2683

Approach

The obvious option is public start/end setters on ISpan. We discussed a few reasons not to:

• The live-tracing timestamps are derived from a monotonic stopwatch; a bare StartTimestamp setter that doesn't reset the stopwatch baseline lets you produce a span that starts in the past but ends "now" (inflated duration). The start/end pair has an invariant a lone setter can't enforce.
• It widens/pollutes ISpan (the most-implemented interface) with mutation that only makes sense for replayed data.

Instead this adds a builder-style recorder:

hub.RecordTransaction("checkout", "http.server", start, duration,
    traceId: originTraceId, spanId: originRootSpanId, configure: tx =>
    {
        tx.Release = "1.2.3";
        tx.RecordSpan("db.query", childStart, childDuration, spanId: originChildId, configure: c =>
        {
            c.Description = "SELECT ...";
            c.RecordSpan("db.connect", gcStart, gcDuration); // arbitrary nesting
        });
    });

Why this shape

• Timing is up-front (start + duration), so a recorded span can't be half-specified and duration can't be negative — the original footgun is structurally unreachable rather than merely diagnosed.
• Nesting lives on the recorder itself (ISpanRecorder.RecordSpan), so a whole tree can be built with plain recursion. Parent is structural; only spanId is overridable per node.
• Trace stitching: origin traceId / spanId / parentSpanId can be preserved.
• Captured once when the callback returns — no stopwatch, idle timer, or sampling roll. It's not a live transaction, so those don't apply.
• No live-scope bleed: captured against a clean scope so the current process's breadcrumbs/user/tags/contexts don't attach to work that happened elsewhere.

Public surface

Intentionally minimal — RecordTransaction is an extension method on IHub, so IHub / ISpan / ITransaction are all unchanged (no breaking interface changes needed to ship). New public types: ISpanRecorder, ITransactionRecorder. Internally it reuses the existing TransactionTracer/SpanTracer → SentryTransaction conversion path, so there are no changes to serialization.

Open questions for reviewers

• duration vs end: went with start + duration so the value can't express a reversed pair. Alternative is a required end (matches the wire protocol and the origin data, which usually carries start+end). Easy to offer both.
• Discoverability: currently only on IHub. Worth mirroring on the SentrySdk static facade?
• Scope isolation: draft uses a fresh Scope(options). Do we want any current-scope data (release/environment/dist) to flow through, or keep it fully isolated and rely on the Release/Environment setters?
• BeforeSendTransaction still runs (last-chance scrubbing); only the sampling roll is skipped. Confirm that's the desired split.

Tests

HubExtensionsRecordTests covers name/operation/timing, id preservation, nested span-tree construction with parent pointers + trace-id inheritance, metadata (release/environment/status/tags/data), and negative-duration guards. An end-to-end scope-isolation test against a real hub is a follow-up.

[codecov]

Codecov Report

❌ Patch coverage is 89.83051% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 74.21%. Comparing base (951d98f) to head (3b71273).

Files with missing lines	Patch %	Lines
src/Sentry/Internal/SpanRecorder.cs	85.29%	5 Missing ⚠️
src/Sentry/SentrySdk.cs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5333      +/-   ##
==========================================
+ Coverage   74.15%   74.21%   +0.06%     
==========================================
  Files         508      509       +1     
  Lines       18353    18412      +59     
  Branches     3586     3595       +9     
==========================================
+ Hits        13610    13665      +55     
- Misses       3870     3875       +5     
+ Partials      873      872       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jamescrosswell]

Note: Arguably we don't need SpanRecorderBase (TransactionRecorder could descend from `SpanRecorder and we just fold all the stuff from the Base class into here). That would give us one less class.

Probably the main reason to do this is so that we can add the sealed keyword to SpanRecorder. Since the cost of doing this is minimal, I've left the base class in for the time being (unless anyone has really strong opinions about this).