feat(tracing): Add extend app start API for standalone app start (#6392)

* feat(tracing): Add extend app start API for standalone app start (RN-675)

Add experimental `extendAppStart()`, `finishExtendedAppStart()`, and
`getExtendedAppStartSpan()` to keep the standalone `app.start` transaction open
past the auto-detected end so post-init work (remote config, session restore,
etc.) is included and can be broken down into child spans under an
`app.start.extended` span.

- `extendAppStart()` cancels the deferred auto-capture, holds the transaction
  open, and starts a 30s deadline.
- `finishExtendedAppStart()` finalizes: trims the end to the last child (floored
  at the default app start end) and sets the measurement at finalization.
- On the deadline the transaction is captured but the `app.vitals.start`
  measurement is suppressed (never emit a ~30s app start).
- `attachAppStartToTransactionEvent` now takes `suppressMeasurement` and returns
  whether it attached, so the finalize path decides send vs skip.

Standalone-only. `appLoaded()` stays as-is for now; its deprecation and removal,
plus making standalone the default, are handled together in RN-676 (v9).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Update changelog

* fix(tracing): Address extend app start review feedback (RN-675)

- extendAppStart(): claim the run only after confirming a recording span, so a
  sampled-out/disabled run falls back to the normal capture path.
- Cap the 60s app start sanity check on the native window, not the extended end,
  so a legitimately extended app start is not dropped.
- Thread the extended end explicitly instead of mutating shared appStartEndData,
  so the extended end survives without wrap()/appLoaded().
- Guard app start attach with a run generation so a finish suspended at the
  native-data await bails when a new runApplication run starts, instead of
  corrupting the new run's state.
- finishExtendedAppStart() returns Promise<void> so callers can await before flush().

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(tracing): Re-check run generation after frames-delay await (RN-675)

The app start attach also awaits fetchNativeFramesDelay (~2s) after the first
generation check; a runApplication reset during that window could still send a
stale standalone transaction. Re-check the generation before reporting success.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(tracing): Trim extended app start to last child, not finish() time (RN-675)

- getLatestChildSpanEndTimestamp was computed on the root transaction, which
  includes the extended (wrapper) span itself; since the wrapper ends at
  finalization time, the transaction was pinned to the finishExtendedAppStart()
  call rather than the last instrumented child. Compute the trim from the
  wrapper's children (excluding the wrapper) on the explicit-finish path, end the
  wrapper at that trimmed time so it never outlives the root, and keep the
  full-window end on the deadline path. Floored at the default app start end and
  the wrapper start.
- Regenerate the API report against @sentry/core 10.63.0 (restores the
  deeplinkIntegration signature that a stale local build had reverted).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* chore: Merge main and move extend app start changelog entry to Unreleased

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: antonis

CHANGELOG.md

@@ -8,6 +8,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add experimental `extendAppStart`/`finishExtendedAppStart`/`getExtendedAppStartSpan` to extend the standalone app start window and instrument post-init work ([#6392](https://github.com/getsentry/sentry-react-native/pull/6392))
+
 ### Fixes
 
 - Skip iOS source maps upload on `Debug` builds ([#6405](https://github.com/getsentry/sentry-react-native/pull/6405))

packages/core/etc/sentry-react-native.api.md

@@ -305,6 +305,9 @@ export const expoRouterIntegration: (options?: ExpoRouterIntegrationOptions) =>
 // @public
 export const expoUpdatesListenerIntegration: () => Integration;
 
+// @public
+export function extendAppStart(): void;
+
 export { extraErrorDataIntegration }
 
 export { FeatureFlagsIntegration }
@@ -353,6 +356,9 @@ export const feedbackIntegration: (initOptions?: Partial<FeedbackFormProps> & {
     enableShakeToReport?: boolean;
 }) => FeedbackIntegration;
 
+// @public
+export function finishExtendedAppStart(): Promise<void>;
+
 // @public
 export function flush(): Promise<boolean>;
 
@@ -384,6 +390,9 @@ export function getDataFromUri(uri: string): Promise<Uint8Array | null>;
 // @public
 export function getDefaultIdleNavigationSpanOptions(): StartSpanOptions;
 
+// @public
+export function getExtendedAppStartSpan(): Span;
+
 export { getGlobalScope }
 
 export { getIsolationScope }

packages/core/src/js/index.ts

@@ -109,6 +109,9 @@ export {
   withScope,
   crashedLastRun,
   appLoaded,
+  extendAppStart,
+  getExtendedAppStartSpan,
+  finishExtendedAppStart,
   pauseAppHangTracking,
   resumeAppHangTracking,
 } from './sdk';

packages/core/src/js/sdk.tsx

@@ -1,5 +1,5 @@
 /* oxlint-disable eslint(complexity) */
-import type { Breadcrumb, BreadcrumbHint, Integration, Scope } from '@sentry/core';
+import type { Breadcrumb, BreadcrumbHint, Integration, Scope, Span } from '@sentry/core';
 
 import {
   debug,
@@ -25,7 +25,12 @@ import { shouldEnableNativeNagger } from './options';
 import { enableSyncToNative } from './scopeSync';
 import { TouchEventBoundary } from './touchevents';
 import { ReactNativeProfiler } from './tracing';
-import { _appLoaded } from './tracing/integrations/appStart';
+import {
+  _appLoaded,
+  _extendAppStart,
+  _finishExtendedAppStart,
+  _getExtendedAppStartSpan,
+} from './tracing/integrations/appStart';
 import { useEncodePolyfill } from './transports/encodePolyfill';
 import { DEFAULT_BUFFER_SIZE, makeNativeTransportFactory } from './transports/native';
 import { getDefaultEnvironment, isExpoGo, isRunningInMetroDevServer, isWeb } from './utils/environment';
@@ -250,6 +255,64 @@ export function appLoaded(): void {
   _appLoaded();
 }
 
+/**
+ * Extends the app start window so work done after initialization (remote config, session restore,
+ * splash screen dismissal, etc.) is included in the app start measurement. Call
+ * {@link finishExtendedAppStart} when the app is ready, or attach child spans via
+ * {@link getExtendedAppStartSpan} to break the extended work down.
+ *
+ * Requires standalone app start tracing (`_experiments.enableStandaloneAppStartTracing`). No-ops if
+ * the app start transaction was already created, if extend was already called, or if called before
+ * `Sentry.init()`.
+ *
+ * @experimental This API is subject to change in future versions.
+ *
+ * @example
+ * ```ts
+ * Sentry.extendAppStart();
+ * await initializeRemoteConfig();
+ * Sentry.finishExtendedAppStart();
+ * ```
+ */
+export function extendAppStart(): void {
+  _extendAppStart();
+}
+
+/**
+ * Returns the extended app start span for attaching child spans, or a no-op span when there is no
+ * active extension. Only meaningful between {@link extendAppStart} and {@link finishExtendedAppStart}.
+ *
+ * @experimental This API is subject to change in future versions.
+ *
+ * @example
+ * ```ts
+ * Sentry.extendAppStart();
+ * const parentSpan = Sentry.getExtendedAppStartSpan();
+ * const child = Sentry.startInactiveSpan({ parentSpan, op: 'app.init', name: 'fetch remote config' });
+ * await loadRemoteConfig();
+ * child.end();
+ * Sentry.finishExtendedAppStart();
+ * ```
+ */
+export function getExtendedAppStartSpan(): Span {
+  return _getExtendedAppStartSpan();
+}
+
+/**
+ * Finishes the app start extension started with {@link extendAppStart}, finalizing the app start
+ * transaction (its duration is trimmed to the last child span). No-ops if there is no active
+ * extension.
+ *
+ * Returns a promise that resolves once the app start transaction has been captured. `await` it
+ * before {@link flush} (e.g. before a code-push/expo update) to make sure the app start data is
+ * queued.
+ *
+ * @experimental This API is subject to change in future versions.
+ */
+export function finishExtendedAppStart(): Promise<void> {
+  return _finishExtendedAppStart();
+}
+
 /**
  * Flushes all pending events in the queue to disk.
  * Use this before applying any realtime updates such as code-push or expo updates.