[skill-drift] update(sentry-flutter-sdk): v9.14.0 → v9.20.0, span-first tracing, breaking navigation change

[github-actions]

Warning

Auto-generated from external SDK content. Review all links and code suggestions before acting on them.

cc @getsentry/support

Summary

The sentry-flutter-sdk skill documents sentry_flutter ≥9.14.0 (February 19, 2026) but the latest stable release is 9.20.0 (May 7, 2026) — 6 minor versions behind. Several new features and one breaking behavior change need documentation.

Key Changes

1. Version Bump: 9.14.0 → 9.20.0

Update version references in:

• Line 23: SDK version comment
• Line 163: pubspec.yaml example
• Line 308: sentry package version for Dart-only

2. New Feature: Span-First Trace Lifecycle (9.19.0)

Experimental opt-in streaming span API that sends spans as they finish instead of buffering into transactions.

New option:

options.traceLifecycle = SentryTraceLifecycle.stream; // default: SentryTraceLifecycle.static

New APIs:

// Async span
final result = await Sentry.startSpan('operation', (span) async {
  span.setAttribute('key', SentryAttribute.string('value'));
  return await doWork();
});

// Sync span
final total = Sentry.startSpanSync('calculate', (span) => compute());

// Manual span
final span = Sentry.startInactiveSpan('payment');
span.end();

Where to document:

• Add traceLifecycle to "Tracing Options" table (lines 456–468)
• Consider adding a new section or reference file for span-first tracing patterns
• Note that auto-instrumentations (navigation, HTTP, DB) automatically use streaming when enabled

Source: PR #3659, Release 9.19.0

3. Breaking Change: enableNewTraceOnNavigation Now Opt-In (9.19.0)

Before 9.19.0: SentryNavigatorObserver generated a fresh trace ID on every push/pop/replace by default.

After 9.19.0: Default behavior is one trace per session (preserves continuity across navigations). Old behavior requires explicit opt-in:

SentryNavigatorObserver(
  enableNewTraceOnNavigation: true, // opt back in to old behavior
)

Where to document:

• Update the Navigation Observer section (lines 207–256) to clarify the default behavior
• Add a note or callout explaining the behavior change in 9.19.0 for users upgrading

Source: PR #3657, Release 9.19.0

4. New Feature: Cross-Organization Trace Prevention (9.20.0)

Prevents accidental trace continuation across organizations. Auto-enabled by default.

New options:

• strictTraceContinuation (bool, default false): when true, both SDK org ID and incoming baggage org ID must match
• orgId (string): explicitly set org ID for self-hosted/Relay setups

options.strictTraceContinuation = true;
options.orgId = 'o123456'; // for self-hosted setups

Where to document:

• Add both options to "Tracing Options" table (lines 456–468)
• Briefly explain the default behavior and when to use strictTraceContinuation or orgId

Source: PR #3567, Release 9.20.0

Non-Actionable Changes

The following merged PRs in the last 7 days do not require skill updates:

• PR #3727: Android SDK 8.42.0 → 8.43.0 (adds ReplayFrameObserver JNI binding, but not exposed in Flutter public API)
• PR #3726: Cocoa SDK 8.58.2 → 8.58.3 (bug fixes only)
• PR #3722: Bug fix for sampleRate forwarding to native SDKs (existing option already documented)
• PR #3715: Android SDK 8.41.0 → 8.42.0 (adds attachRawTombstone JNI binding, but not exposed in Flutter public API)
• PR #3713: Performance optimization (internal refactor, no API changes)

Recommendation

This requires manual review because:

1. Multiple interconnected sections need updates (version numbers, config tables, navigation behavior)
2. Breaking change needs migration guidance for users upgrading from <9.19.0
3. Span-first tracing is experimental and needs judgment on how to present it (dedicated section vs. inline note)
4. Cross-org trace prevention is auto-enabled and affects distributed tracing setups

Files to Update

• skills/sentry-flutter-sdk/SKILL.md (lines 23, 163, 207-256, 308, 456-468)
• Possibly skills/sentry-flutter-sdk/references/tracing.md (for span-first APIs and new options)