Expose a public API to manually start a new trace (parity with JS SDK's startNewTrace())

[pcrock-thmdo]

Problem Statement

There's no supported way for app code to say "start a new trace here." Trace boundaries are currently only ever created by:

• SentryNavigatorObserver on navigation events
• App foreground/background transitions (mobile, 30s threshold)

Everything that manages this — Hub.generateNewTrace(), Scope.propagationContext, and the PropagationContext class itself — is marked @internal.

This is a real gap for apps with background work that isn't tied to navigation: polling loops, timers, retries, or any repeated operation that runs for as long as a screen stays open. Any such call falls back to Sentry.startTransaction() when it has no active parent span — but that transaction still inherits whatever trace_id is sitting in the scope from the last navigation event, even if that navigation's transaction finished seconds or minutes ago. The result: unrelated background operations all get glued into one trace that spans the entire screen session, rather than each getting its own trace.

Solution Brainstorm

Comparison to @sentry/core (JS)

The JavaScript SDK exposes exactly this as a stable, documented, public function:

export function startNewTrace(): void

used precisely for this scenario (SPA route changes without a router integration). The Dart/Flutter SDK has the equivalent capability (Hub.generateNewTrace()), it's just never been promoted out of @internal.

Workaround today

// ignore: invalid_use_of_internal_member
Sentry.currentHub.generateNewTrace();

This works (it's literally what SentryNavigatorObserver calls internally), but it's not covered by semver guarantees, so a minor/patch bump could rename or remove it without a deprecation cycle.

Ask

Expose a public, stable API — e.g. Sentry.startNewTrace() — mirroring the JS SDK, so apps with non-navigation-driven background work can manage trace boundaries without reaching into @internal SDK guts.

Are you willing to submit a PR?

None

[linear-code]

DART-450

[buenaflor]

@pcrock-thmdo hi the JS SDK ships a callback based version

// Sentry JavaScript:
function startNewTrace<T>(callback: () => T): T

it could look something like this in Dart

Sentry.startNewTrace(() {
  bgWork1();
  bgWork2();
}

which I would also opt for the Dart SDK unless you have a specific use case that would not covered by this?

[pcrock-thmdo]

I think that makes sense as long as it handles async work properly within the callback. Our use case is a Timer-driven poll (Future<T> Function() fetch()), so we'd need the trace context to survive the whole async execution, the same way SentryFlutter.init's appRunner already runs inside a managed Zone via runZonedGuarded. If it's implemented that way, this API works great for us.

[buenaflor]

If I understand correctly something like this is your use case? This should work. The new trace stays scoped to the startNewTrace() callback and won’t override the global scope like generateNewTrace() does today.

// tick 1 → trace A
// tick 2 → trace B
// tick 3 → trace C

Timer.periodic(const Duration(seconds: 30), (_) {
  unawaited(Sentry.startNewTrace(() async {
    final transaction = Sentry.startTransaction(
      'background-poll',
      'task',
    );

    try {
      final value = await fetch();
      transaction.setData('poll.items', value.length);
      transaction.status = const SpanStatus.ok();
    } catch (e, st) {
      transaction.throwable = e;
      transaction.status = const SpanStatus.internalError();
      await Sentry.captureException(e, stackTrace: st);
      rethrow;
    } finally {
      await transaction.finish();
    }
  }));
});