BootAudit class final

Persistent boot audit trail. Survives across app restarts (web reloads, PWA cold starts, native process restarts when backed by appropriate storage). The only thing that clears it is an explicit clear call.

Why this exists: in-memory logs from a prior run are gone by the time you open devtools on the next run. Bugs that only reproduce on the second or third launch leave no breadcrumbs in Log.items because the queue was reset. BootAudit is the cross-boot companion to that in-memory queue: a small, append-only stream of named events that you can read back from any later boot.

Usage

Create one BootAudit near the start of main() and call bootInit before any other work. Then log named events from anywhere:

final audit = BootAudit(
  appKey: 'myapp',
  storage: LocalStorageBootAuditStorage(), // web; or InMemoryBootAuditStorage()
);

void main() {
  audit.bootInit();
  audit.log('CACHE_INIT', {'sizeBytes': cacheBytes});
  runApp(const MyApp());
}

Reading the trail

In-process: readAll returns every entry across every boot.

From the browser console (web backend):

JSON.parse(localStorage.getItem('<appKey>_boot_audit_v1'))
    .forEach(e => console.log(e.b, e.e, e.t, e.d || ''));

Bounded size

The trail is capped at maxEntries (oldest dropped first) so a chatty app can't grow the storage payload without bound.

Constructors

BootAudit({required String appKey, required BootAuditStorage storage, int maxEntries = 400})

Properties

appKey → String: Prefix for the storage keys this instance reads and writes. Pick a short, app-specific token (e.g. 'myapp') so two apps sharing the same backend don't collide.
final
bootNumber → int: Monotonically-increasing counter incremented once per bootInit call. 0 until bootInit runs.
no setter
hashCode → int: The hash code for this object.
no setterinherited
maxEntries → int: Hard cap on the number of entries kept on disk. Newer entries win: when the cap is exceeded the oldest entries are dropped on the next log call.
final
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
storage → BootAuditStorage: Backend used to persist the trail. Stays small — JSON-encoded entries in a single key. See BootAuditStorage for bundled implementations.
final

Methods

bootInit({Map<String, dynamic>? bootDetails}) → void: Call once at the very start of main(). Reads the prior trail, mirrors it to Log with a banner, increments the boot counter, then writes a fresh BOOT_START event with bootDetails.
clear() → void: Wipe the trail and reset the boot counter. Don't call this automatically — the whole point of the trail is that it survives. Reserve clear for an explicit debug button or test setup.
log(String event, [Map<String, dynamic>? details]) → void: Append an event to the trail (also mirrored to Log.info for live tails). details is an optional map of arbitrary JSON-encodable values.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
readAll() → List<Map<String, dynamic>>: Read every entry on the trail, across every boot, oldest first. Returns an unmodifiable view of the in-memory cache.
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Constants

kBootNumberKey → const String: Detail-map key for the boot number an entry belongs to.
kDetailsKey → const String: Detail-map key for the optional details map.
kEventKey → const String: Detail-map key for the event name.
kTimestampKey → const String: Detail-map key for the ISO-8601 timestamp of an entry.