perf(startup): instrument startup phases

Author: ethicnology

lib/core/utils/startup_phase_tracker.dart

@@ -0,0 +1,50 @@
+import 'dart:developer' as developer;
+
+enum StartupPhase {
+  bindingInitialized,
+  wizardChecked,
+  wizardCompleted,
+  logsInitialized,
+  pendingChoicesRead,
+  reportInitialized,
+  nativeInitialized,
+  locatorInitialized,
+  pendingChoicesApplied,
+  settingsLoaded,
+  workmanagerCancelled,
+  migrationCompleted,
+  loading,
+  packageLoaded,
+  walletsChecked,
+  legacyResolved,
+  credentialsResolved,
+  torCheckCompleted,
+  terminalResolved,
+}
+
+typedef StartupPhaseSink =
+    void Function(StartupPhase phase, Map<String, Object> arguments);
+
+class StartupPhaseTracker {
+  final StartupPhaseSink _sink;
+  StartupPhase? _lastPhase;
+
+  StartupPhaseTracker({StartupPhaseSink? sink}) : _sink = sink ?? _timelineSink;
+
+  StartupPhase? get lastPhase => _lastPhase;
+
+  void mark(StartupPhase phase) {
+    if (_lastPhase != null && phase.index <= _lastPhase!.index) return;
+
+    _lastPhase = phase;
+    try {
+      _sink(phase, {'phase': phase.name});
+    } catch (_) {
+      // Startup instrumentation must never affect startup itself.
+    }
+  }
+
+  static void _timelineSink(StartupPhase phase, Map<String, Object> arguments) {
+    developer.Timeline.instantSync('bull.startup.phase', arguments: arguments);
+  }
+}

lib/features/app_startup/app_startup_locator.dart

@@ -4,6 +4,7 @@ import 'package:bb_mobile/core/seed/data/repository/seed_repository.dart';
 import 'package:bb_mobile/core/settings/data/settings_repository.dart';
 import 'package:bb_mobile/core/storage/data/datasources/key_value_storage/key_value_storage_datasource.dart';
 import 'package:bb_mobile/core/utils/constants.dart';
+import 'package:bb_mobile/core/utils/startup_phase_tracker.dart';
 import 'package:bb_mobile/core/wallet/data/repositories/wallet_repository.dart';
 import 'package:bb_mobile/features/app_startup/data/wallet_startup_adapter.dart';
 import 'package:bb_mobile/features/app_startup/domain/app_startup_wallet_port.dart';
@@ -20,7 +21,7 @@ import 'package:get_it/get_it.dart';
 import 'package:bull_tor/tor.dart';
 
 class AppStartupLocator {
-  static void setup(GetIt locator) {
+  static void setup(GetIt locator, {StartupPhaseTracker? startupPhaseTracker}) {
     locator.registerLazySingleton<AppStartupWalletPort>(
       () => WalletStartupAdapter(locator<WalletRepository>()),
     );
@@ -69,6 +70,7 @@ class AppStartupLocator {
         checkLegacyInstallUsecase: locator<CheckLegacyInstallUsecase>(),
         checkBackupUsecase: locator<CheckBackupUsecase>(),
         initializeRequiredTorUsecase: locator<InitializeRequiredTorUsecase>(),
+        startupPhaseTracker: startupPhaseTracker,
       ),
     );
   }

lib/features/app_startup/presentation/bloc/app_startup_bloc.dart

@@ -3,6 +3,7 @@ import 'dart:async';
 import 'package:bb_mobile/core/storage/data/datasources/key_value_storage/keychain_locked_exception.dart';
 import 'package:bb_mobile/core/utils/logger.dart';
 import 'package:bb_mobile/core/utils/result.dart';
+import 'package:bb_mobile/core/utils/startup_phase_tracker.dart';
 import 'package:bb_mobile/features/app_startup/domain/usecases/check_for_existing_default_wallets_usecase.dart';
 import 'package:bb_mobile/features/app_startup/domain/usecases/check_legacy_install_usecase.dart';
 import 'package:bb_mobile/features/app_startup/domain/usecases/initialize_required_tor_usecase.dart';
@@ -30,7 +31,9 @@ class AppStartupBloc extends Bloc<AppStartupEvent, AppStartupState>
     required this._checkLegacyInstallUsecase,
     required this._checkBackupUsecase,
     required this._initializeRequiredTorUsecase,
+    StartupPhaseTracker? startupPhaseTracker,
   }) : super(const AppStartupState.initial()) {
+    _startupPhaseTracker = startupPhaseTracker ?? StartupPhaseTracker();
     on<AppStartupStarted>(_onAppStartupStarted);
     WidgetsBinding.instance.addObserver(this);
   }
@@ -42,6 +45,7 @@ class AppStartupBloc extends Bloc<AppStartupEvent, AppStartupState>
   final CheckLegacyInstallUsecase _checkLegacyInstallUsecase;
   final CheckBackupUsecase _checkBackupUsecase;
   final InitializeRequiredTorUsecase _initializeRequiredTorUsecase;
+  late final StartupPhaseTracker _startupPhaseTracker;
 
   /// True while we're sitting on the splash because a startup step
   /// threw `KeychainLockedException` (iOS pre-first-unlock pre-warm).
@@ -69,28 +73,37 @@ class AppStartupBloc extends Bloc<AppStartupEvent, AppStartupState>
     Emitter<AppStartupState> emit,
   ) async {
     emit(const AppStartupState.loadingInProgress());
+    _startupPhaseTracker.mark(StartupPhase.loading);
 
     try {
       // Log app version on startup
       final packageInfo = await PackageInfo.fromPlatform();
       log.info(
         'App started: ${packageInfo.appName} v${packageInfo.version}+${packageInfo.buildNumber}',
       );
+      _startupPhaseTracker.mark(StartupPhase.packageLoaded);
 
       final doDefaultWalletsExist = await _checkForExistingDefaultWalletsUsecase
           .execute();
+      _startupPhaseTracker.mark(StartupPhase.walletsChecked);
 
       // Pre-v5 ("BULL") installs are no longer migrated: gate them behind a
       // backup screen. Only when the new DB is empty — the legacy marker can
       // survive a failed migration while the user has since set up working
       // v5+ wallets, and those current seeds are not legacy-format: gating
       // such an install would show a backup screen missing its live wallets
       // and instruct deleting them.
-      if (!doDefaultWalletsExist &&
-          await _checkLegacyInstallUsecase.execute()) {
-        log.warning('Legacy (pre-v5) install detected — backup gate shown');
-        emit(const AppStartupState.legacyBackupRequired());
-        return;
+      if (!doDefaultWalletsExist) {
+        final isLegacyInstall = await _checkLegacyInstallUsecase.execute();
+        _startupPhaseTracker.mark(StartupPhase.legacyResolved);
+        if (isLegacyInstall) {
+          log.warning('Legacy (pre-v5) install detected — backup gate shown');
+          emit(const AppStartupState.legacyBackupRequired());
+          _startupPhaseTracker.mark(StartupPhase.terminalResolved);
+          return;
+        }
+      } else {
+        _startupPhaseTracker.mark(StartupPhase.legacyResolved);
       }
 
       bool isPinCodeSet = false;
@@ -99,6 +112,7 @@ class AppStartupBloc extends Bloc<AppStartupEvent, AppStartupState>
         switch (await _checkPinCodeExistsUsecase.execute()) {
           case Ok(:final value):
             isPinCodeSet = value;
+            _startupPhaseTracker.mark(StartupPhase.credentialsResolved);
           case Err(failure: AppUnlockKeychainLockedFailure()):
             _waitForKeychainUnlock();
             return;
@@ -111,18 +125,21 @@ class AppStartupBloc extends Bloc<AppStartupEvent, AppStartupState>
         //  there from a previous install.
         //  (e.g. secure storage data on iOS like the pin code)
         await _resetAppDataUsecase.execute();
+        _startupPhaseTracker.mark(StartupPhase.credentialsResolved);
       }
 
       // Warm the embedded client without delaying the startup screen. The
       // coordinator makes this single-flight with any concurrent consumer.
       unawaited(_initializeTorInBackground());
 
+      _startupPhaseTracker.mark(StartupPhase.torCheckCompleted);
       emit(
         AppStartupState.success(
           isPinCodeSet: isPinCodeSet,
           hasDefaultWallets: doDefaultWalletsExist,
         ),
       );
+      _startupPhaseTracker.mark(StartupPhase.terminalResolved);
     } on KeychainLockedException catch (_) {
       // iOS pre-first-unlock pre-warm: the keychain is locked, so any
       // seed read (CheckForExistingDefaultWalletsUsecase →

lib/locator.dart

@@ -4,6 +4,7 @@ import 'package:bb_mobile/core/storage/sqlite_database.dart';
 import 'package:bb_mobile/core/sync/sync_locator.dart';
 import 'package:bb_mobile/core/sync/sync_coordinator.dart';
 import 'package:bb_mobile/core/utils/result.dart';
+import 'package:bb_mobile/core/utils/startup_phase_tracker.dart';
 import 'package:bb_mobile/payjoin_setup.dart';
 import 'package:bb_mobile/features/address_view/address_view_locator.dart';
 import 'package:bb_mobile/features/all_seed_view/all_seed_view_locator.dart';
@@ -63,6 +64,7 @@ class AppLocator {
     bool startPayjoinRecovery = true,
     bool startOrderSwapWatcher = true,
     bool startAutoswapWatcher = true,
+    StartupPhaseTracker? startupPhaseTracker,
   }) async {
     locator.enableRegisteringMultipleInstancesOfOneType();
 
@@ -123,7 +125,7 @@ class AppLocator {
     TorSettingsLocator.setup(locator);
     PinCodeLocator.setup(locator);
     WizardLocator.setup(locator);
-    AppStartupLocator.setup(locator);
+    AppStartupLocator.setup(locator, startupPhaseTracker: startupPhaseTracker);
     AppUnlockLocator.setup(locator);
     OnboardingLocator.setup(locator);
     AllSeedViewLocator.setup(locator);

lib/main.dart

@@ -11,6 +11,7 @@ import 'package:bb_mobile/core/themes/app_theme.dart';
 import 'package:bb_mobile/core/utils/constants.dart';
 import 'package:bb_mobile/core/utils/logger.dart';
 import 'package:bb_mobile/core/utils/report.dart';
+import 'package:bb_mobile/core/utils/startup_phase_tracker.dart';
 
 import 'package:bb_mobile/features/app_startup/presentation/bloc/app_startup_bloc.dart';
 import 'package:bb_mobile/features/app_startup/ui/app_startup_widget.dart';
@@ -62,8 +63,13 @@ void resumePayjoinsOnAppResume(
 }
 
 class Bull {
-  static Future<void> init({String? payjoinDatabasePath}) async {
+  static Future<void> init({
+    String? payjoinDatabasePath,
+    StartupPhaseTracker? startupPhaseTracker,
+  }) async {
+    final tracker = startupPhaseTracker ?? StartupPhaseTracker();
     await initLogs();
+    tracker.mark(StartupPhase.logsInitialized);
     // The pre-init wizard writes consent to prefs via the bloc's
     // `SavePendingWizardChoicesUsecase` right before this runs. Pull
     // it so Sentry initializes with the user's freshest answer rather
@@ -73,18 +79,28 @@ class Bull {
     final pending = await ReadPendingWizardChoicesUsecase(
       repository: preInitRepo,
     ).execute();
+    tracker.mark(StartupPhase.pendingChoicesRead);
     await Report.init(wizardConsent: pending?.reportingConsent);
+    tracker.mark(StartupPhase.reportInitialized);
     await initFlutterRustBridgeDependencies();
+    tracker.mark(StartupPhase.nativeInitialized);
     // The Locator setup might depend on the initialization of the libraries above
     //  so it's important to call it after the initialization
-    await initLocator(payjoinDatabasePath: payjoinDatabasePath);
+    await initLocator(
+      payjoinDatabasePath: payjoinDatabasePath,
+      startupPhaseTracker: tracker,
+    );
+    tracker.mark(StartupPhase.locatorInitialized);
     // Flush wizard pending values (if any) to SQLite now that the
     // settings repository is available, then mark the wizard complete.
     await locator<ApplyPendingWizardChoicesUsecase>().execute();
+    tracker.mark(StartupPhase.pendingChoicesApplied);
     final settings = locator<SettingsRepository>();
     Report.consent = (await settings.fetch()).isErrorReportingEnabled;
+    tracker.mark(StartupPhase.settingsLoaded);
     if (Platform.isAndroid || Platform.isIOS) {
       await initWorkmanager();
+      tracker.mark(StartupPhase.workmanagerCancelled);
     }
     // Emits the install/upgrade transition event (no-op on a normal
     // launch) and advances the persisted version marker. The shout is
@@ -96,6 +112,7 @@ class Bull {
       await log.shout(message: type.name, category: ReportCategory.migration);
       await Report.commitVersion();
     }
+    tracker.mark(StartupPhase.migrationCompleted);
   }
 
   static Future<void> initFlutterRustBridgeDependencies() async {
@@ -135,11 +152,15 @@ class Bull {
     }
   }
 
-  static Future<void> initLocator({String? payjoinDatabasePath}) async {
+  static Future<void> initLocator({
+    String? payjoinDatabasePath,
+    StartupPhaseTracker? startupPhaseTracker,
+  }) async {
     await AppLocator.setup(
       locator,
       SqliteDatabase(),
       payjoinDatabasePath: payjoinDatabasePath,
+      startupPhaseTracker: startupPhaseTracker,
     );
     Bloc.observer = AppBlocObserver();
   }
@@ -158,6 +179,8 @@ Future main() async {
     () async {
       try {
         WidgetsFlutterBinding.ensureInitialized();
+        final startupPhaseTracker = StartupPhaseTracker();
+        startupPhaseTracker.mark(StartupPhase.bindingInitialized);
         // Wizard runs BEFORE `Bull.init` for everyone — fresh installs
         // and upgrades alike — so consent is collected before
         // migrations / Sentry init / Drift schema work fires off, and
@@ -167,12 +190,14 @@ Future main() async {
         final isComplete = await IsWizardCompleteUsecase(
           repository: preInitRepo,
         ).execute();
+        startupPhaseTracker.mark(StartupPhase.wizardChecked);
         if (!isComplete) {
           final completer = Completer<void>();
           runApp(WizardApp(onDone: (_) => completer.complete()));
           await completer.future;
         }
-        await Bull.init();
+        startupPhaseTracker.mark(StartupPhase.wizardCompleted);
+        await Bull.init(startupPhaseTracker: startupPhaseTracker);
       } catch (error, stackTrace) {
         log.severe(message: 'App Init Error', error: error, trace: stackTrace);
         runApp(AppInitErrorScreen(error: error));

test/core_test/utils/startup_phase_tracker_test.dart

@@ -0,0 +1,31 @@
+import 'package:bb_mobile/core/utils/startup_phase_tracker.dart';
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test('emits each phase once and ignores regressions', () {
+    final phases = <StartupPhase>[];
+    final payloads = <Map<String, Object>>[];
+    final tracker = StartupPhaseTracker(
+      sink: (phase, arguments) {
+        phases.add(phase);
+        payloads.add(arguments);
+      },
+    );
+
+    tracker
+      ..mark(StartupPhase.nativeInitialized)
+      ..mark(StartupPhase.nativeInitialized)
+      ..mark(StartupPhase.logsInitialized)
+      ..mark(StartupPhase.locatorInitialized);
+
+    expect(phases, [
+      StartupPhase.nativeInitialized,
+      StartupPhase.locatorInitialized,
+    ]);
+    expect(payloads, [
+      {'phase': 'nativeInitialized'},
+      {'phase': 'locatorInitialized'},
+    ]);
+    expect(tracker.lastPhase, StartupPhase.locatorInitialized);
+  });
+}