Startup and database waits
Upgrade the Flutter valence runtime and ship a host build to get these diagnostics
(contracts section 5.1.1). No schema, codegen or web bundle change is needed.
The existing Valence.open(log: ...) callback receives them; the default logger
prefixes lines with [valence] in logcat.
Locate the last startup phase
Section titled “Locate the last startup phase”Valence.open reports entry and completion for binding, links, directories,
store, state, services, seed, and the configured notifications and push
phases. elapsedMs measures time since open began and phaseMs measures time in
the named phase:
startup: phase=store status=begin elapsedMs=12 phaseMs=0startup: phase=store status=complete elapsedMs=48 phaseMs=36startup: phase=state status=begin elapsedMs=48 phaseMs=0What each phase does
Section titled “What each phase does”A duration is not a judgement until there is something to compare it with, so here is the shape rather than a budget:
| phase | what it does |
|---|---|
binding |
in-process |
state |
reads state.json |
store |
opens SQLite, and may run a migration |
seed |
loads the bundled seed asset, and imports it when it is new (see below) |
directories |
resolves the application support directory |
links, push |
initialize their transports |
services |
constructs the platform secure store, plus the sync and update services |
notifications |
initializes the local notification plugin, when one is configured |
The last five rows each cross a platform channel — the boundary between your Dart code and the Java/Kotlin or Swift the OS speaks — and that is where a cold start’s time actually goes.
seed is not free after the first launch. If you declare any data bucket, the
phase loads the whole seed asset before it can tell whether the import is needed,
because the completion stamp is the host build and the asset’s byte length together. So
its floor is proportional to your seed’s size on every launch. What happens only on a
first launch and after a host upgrade is the import, not the phase — and the import
also re-runs if seed.db has gone missing or if the asset’s length changed at the same
host build.
links costs nothing if you declare no link origins, and it runs first so it can
take the OS intent before anything else. If that is you, the one-off cost below lands on
the first phase that does cross a channel, which is directories.
They carry a one-off registration cost on the first launch after an install, and it
is not proportional to what you declared. On one device, an app with a single
custom-scheme origin and no App Links — nothing to verify, no assetlinks.json —
measured links at 2292 ms of a 3268 ms first open, against directories 25 ms,
store 105 ms, state 0 ms and services 610 ms; on a warm restart links was
732 ms and still the largest phase by roughly an order of magnitude. One device and one
app is not a benchmark, but it is enough to say which phases are expected to dominate.
If one of the five channel-crossing phases is your largest number on a first launch,
that is the platform channel and not your own code — look at the phases around it before
you instrument your own.
A failure reports status=failed before rethrowing the original error. A phase
entry without completion is the last observed boundary; it does not establish the
cause. startup: complete means open returned. The host widget’s server, bundle
verification/selection, WebView and ready() are later work. It is not proof that
the page painted, a trial committed or an ANR cannot occur.
Time app-owned initialization
Section titled “Time app-owned initialization”An app may await media, reminder or link setup after Valence.open and before
runApp. Those awaits are outside the runtime phases. Time the existing calls
in their existing order before assigning a cause to the gap.
This helper belongs in your host code. Keep labels fixed at source; never pass a route, file path, token, user value or exception into the log.
import 'package:flutter/widgets.dart';
enum AppStartupPhase { media, reminders, links }
void startupLog(String message) { try { debugPrint(message); } catch (_) { // Diagnostics must not change startup or replace an initialization error. }}
Future<T> timeAppStartup<T>( AppStartupPhase phase, Future<T> Function() action,) async { final watch = Stopwatch()..start(); void report(String status) => startupLog( 'app-startup: phase=${phase.name} status=$status ' 'phaseMs=${watch.elapsedMilliseconds}', ); report('begin'); try { final result = await action(); report('complete'); return result; } catch (_) { report('failed'); rethrow; } finally { watch.stop(); }}
void markFirstFlutterFrame() { final watch = Stopwatch()..start(); WidgetsBinding.instance.addPostFrameCallback((_) { watch.stop(); startupLog( 'app-startup: boundary=firstFrame elapsedMs=${watch.elapsedMilliseconds}', ); });}For example, wrap an existing await initializeMedia() as
await timeAppStartup(AppStartupPhase.media, initializeMedia). Use the same
pattern for your other existing setup calls, preserving their results and order.
After the existing binding initialization, call markFirstFlutterFrame()
immediately before your existing runApp. The marker’s elapsed time starts at
registration, separately from runtime startup and each app phase.
A begin without a matching completion locates the last observed await; it
does not prove a deadlock or identify a blocking plugin. A firstFrame can be
only a Flutter loading screen. Meaningful web paint and the web app’s existing
ready() call remain separate observations; do not call ready() from this
callback. Keep the failed attempt, process IDs and resource conditions alongside
any successful retry. These observations add no retries or timeout changes and
do not justify clearing the account or database.
Identify pending database work
Section titled “Identify pending database work”Operations pending for ten seconds log every ten seconds, then report completion or failure. Concurrent operations carry separate ids, scoped to the named isolate:
store: waiting operation=store.get id=23 isolate=789 elapsedMs=10002store: completed operation=store.get id=23 isolate=789 elapsedMs=10831Labels cover runtime reads, writes, prefs, seed import, database opening and configuration, sync status, observation writes and lease acquisition. Confirmed lock errors and existing retry lines also name their operation. A pending future may be waiting on a lock, sqflite scheduling or execution; these lines do not identify the holder or prove deadlock. Timers depend on the event loop, so an engine stall can delay or prevent output.
These logs do not cancel work, add retries or change lock/lease deadlines.
Fast operations produce no wait logs. Timers stop on success or failure. Labels
contain no SQL, arguments, paths, keys, values, tokens or account ids. Direct
app/plugin queries through store.db need their own instrumentation. The first
opener owns the cached store’s logger in each isolate; direct ValenceStore.open
callers can pass log too.
Find out why a sync says busy
Section titled “Find out why a sync says busy”A busy reply means a run was refused because another one holds the sync lease.
The log names which one, and for how long it had held it:
sync: took the lease kind=background pid=4893 (dated 2951ms ago)sync: another sync holds the lease; skipping this run holder=background heldForMs=7001 refused=foregroundsync: released the lease kind=background heldForMs=11280kind is foreground (UI start, resume, reconnect, sync.now, or an update
check’s data pull), background (the periodic job) or push (woken by a
data-only message). The same two facts are readable from the page through
sync.status().leaseKind and .leaseAgeMs
(sync outcomes).
It names the class of run, not the individual run. The UI isolate has one
sync driver, so two foreground triggers overlapping — the UI-start sync and the
connectivity sync, which fire milliseconds apart on a reconnect — read
holder=foreground refused=foreground. That rules out the background isolate,
which is usually what you are asking about. To tell the two foreground triggers
apart, read the trigger lines immediately above (sync: connectivity came back,
update: ...) and match the refused run’s heldForMs against the holder’s
take-time, which the next paragraph explains how to find.
Date the hold from (dated <n>ms ago), not from the took the lease line’s own
timestamp. The line is written after the time it records — the row insert, the
commit and the hops back out all sit in between — so the trail on the line is how
far back the take-time really is. Without it, bracketing took and released
understates the hold: on a loaded device the two lines sat 91 ms apart around a
hold the host correctly reported as heldForMs=3039. The trail is not the
database wait — the host samples the clock after that wait on purpose, so that a
sibling’s renewal cannot read as future-dated — and the store’s own waiting line
is what reports the wait. The trail never goes negative.
Every heldForMs here — on a refusal and on a release alike — is measured from
when the holder took the lease, so subtracting it from the line’s own
timestamp lands on the take-time: the took the lease line’s timestamp minus
its own trail. Before 0.4.0-beta.0 the refusal
lines measured from the host’s internal lease renewal instead, which happens after
every applied page: during a long sync they counted up from zero again on each
page, so a refusal could report tens of milliseconds for a lease that was minutes
old. Only the release line was right. If you are reading logs from an older build,
date the holder from its took the lease line and ignore the refusals’ number.
The pair of lines is the thing to look for. A took the lease with no
matching released the lease is a run that was torn down while holding it — a
cancelled background job gets no chance to clean up — and the background isolate
brackets its whole run as well:
sync: background isolate entered kind=background pid=4893sync: background isolate left kind=background pid=4893An entered with no left, followed by busy replies naming
holder=background, is a lease a cancelled isolate did not give back. The next
run takes it over once it passes its two-minute expiry, so this is slow rather
than permanent — but it is now something the log shows rather than something you
infer from a busy. If you see it, that is a reportable bug: include these lines,
the adb shell dumpsys activity exit-info output below, and the PID.
The take and release lines come from the lease itself, so a path that acquires without a full run — an update check’s data pull, the garbage collector’s pair step, an account switch — is bracketed too.
These lines change no lease deadline and no takeover rule. A lease past its expiry, at least its expiry ahead, or left by a process that is gone is taken over, and each of the three says which it was:
sync: taking over a lease (kind=background, written 183001ms ago): past its 2-minute expiryA takeover whose reason reads “dated in the future” with a negative age was a
bug, and it is fixed in 0.4.0-beta.0. If you see this in logs from an earlier
build:
sync: taking over a lease (kind=background, written -11080ms ago): dated in the future, so the clock movedyour device’s clock did not move. The host sampled the clock before the lease
transaction, and that transaction waits for whatever the other isolate is
writing — so on a busy device it started seconds later and read a renewal newer
than its own “now”. The row looked future-dated, so a foreground run took the
lease from a background sync that was still working, and two syncs ran over one
database. The symptom to confirm it: two released the lease lines, one of each
kind, milliseconds apart, with no released between the took lines.
The fix samples the clock inside the transaction, and a lease row this process
wrote now counts as held whichever side of “now” it falls, until it is further
ahead than the two-minute expiry — a PID that is yours means a sibling isolate
that is running, while a clock that genuinely moved backwards still frees the
lease. No number reported as an age can be negative any more: a displaced row
ahead of “now” logs dated <n>ms in the future and names the expiry it exceeded.
One thing to know about a heldForMs above 120000 on a release line: the lease
had already expired and may have been taken over mid-run, and releasing deletes
the row unconditionally, so it clears the new holder’s lease out from under it.
That behaviour is not new — this number is the first thing that makes it visible.
Capture a recurrence
Section titled “Capture a recurrence”Record the installed build and snapshot revision, and establish that Android finished booting before interpreting a startup attempt. Capture logs before a restart clears useful evidence:
adb logcat --pid=<app-pid> -v threadtimeadb shell dumpsys activity exit-info <app-id>Use your actual app PID and package id. A logcat PID filter ends at process death; capture the next PID separately for a restarted app. Keep captures local and review existing app/native logs for private data before sharing them.
Recognise a WebView eviction
Section titled “Recognise a WebView eviction”One kind of death writes no host line at all, and the silence is the signature.
The WebView runs its page in a separate, lower-priority process. Under memory
pressure Android kills that one first, and because webview_flutter_android
4.14.1 exposes no onRenderProcessGone callback, the WebView then kills your app
process — within about 70 ms, with no Dart frame in between. There is no failed
phase, no exception and no ANR to find, and the user lands back on the launcher.
Read it out of exit-info rather than the log: a renderer exiting LOW_MEMORY,
then the host exiting SIGNALED in the same second, from the background.
process=com.google.android.webview:sandboxed_process0:…SandboxedProcessService0:0 reason=3 (LOW_MEMORY) … rss=208MBprocess=<your app> reason=2 (SIGNALED) subreason=0 (UNKNOWN) status=9 importance=400 … rss=529MBIn logcat the same moment reads:
lowmemorykiller: Kill '…SandboxedProcessService0:0' (19933) … min watermark is breachedchromium: [ERROR:…/aw_browser_terminator.cc:124] Render process (19933) kill (OOM or update) wasn't handed by all associated webviews, killing application.The Chromium termination line establishes the unhandled-renderer-loss path for
that process. Exit-info alone does not establish the cause: correlate timestamps
and PIDs with full logcat. A direct lmkd kill of the host names your package in
the lowmemorykiller line; handling a renderer callback cannot prevent that kill.
An ANR names the affected package in dumpsys activity anr or /data/anr.
Neither this signature nor a successful relaunch establishes a Valence memory
leak or rules out memory use by the app.
Valence 0.4 cannot prevent it on Android, because the callback that would is not exposed by any released version of the plugin; closing it needs native code.
It has one consequence worth planning for. Because no host code runs, the next launch cannot tell this apart from the app crashing on the bundle’s own page — and that check is what makes OTA rollback work. So an eviction while a release is on trial spends one of its two strikes, and two of them retire a healthy release on that install. Nothing in 0.4 can distinguish the two cases; rolling out to 10% first is the practical answer, and the logs above are how you tell afterwards that memory, not your release, was the cause.
Where a platform does report the loss — iOS, as a webContentProcessTerminated
resource error, where the app is not killed — the host reloads the same bundle at
the route you were on, counts no trial failure against it, and after three
recoveries releases the WebView and clears serving in state.json. It retains
trial and its existing failure count, so the next launch retries that trial
without charging a strike for this reported renderer loss. Within the recovery
limit your page sees an ordinary reload; at the cap the host shows its error view.
A recovery that happens while the app is in the background arms the trial’s
15-second ready window without starting it, and the resume starts it: the clock
counts foreground time and is stopped by the pause transition, which has already
been delivered by then, so a clock started there would have run unwatched through
however long the app stayed backgrounded and spent a strike on a release that was
never on screen.
iOS remains experimental and untested on hardware.
Keep durable state in SQLite (it survives either way) and treat a relaunch as expected on a device under pressure. Contracts section 3, “Renderer loss”, carries the full statement.
The other death: Android kills the host directly
Section titled “The other death: Android kills the host directly”A direct low-memory kill of your own process is a different failure with the same ending, and the log is the only thing that tells them apart. Here the renderer is not the cause — lmkd names your package, and there is no Chromium termination line claiming an unhandled renderer loss:
lowmemorykiller: Kill 'com.example.app' (5151) … min watermark is breachedprocess=com.example.app reason=3 (LOW_MEMORY) … rss=533MBCompare that with the signature above: there, the lowmemorykiller line names a
SandboxedProcessService, the renderer’s exit-info reason is LOW_MEMORY, and
the host’s is SIGNALED because the WebView killed it. Here the host’s own
reason is LOW_MEMORY and nothing was signalled. Do not read the second as the
first. They lead to different conclusions: a renderer loss is a plugin gap that
native code could close, and a direct host kill is the OS reclaiming a process
that was using half a gigabyte. Neither establishes a leak in Valence, and
neither is established by exit-info alone — correlate the PIDs and timestamps
with full logcat, and capture both before letting the app restart, because an
ordinary relaunch overwrites the evidence.
It is likeliest during an excursion to another app — native Settings, a photo picker, a camera — because your process is then backgrounded and cached, which is exactly what lmkd chooses. What the user sees on return is a cold start rather than the page they left.
What recovery you get, and what you do not. Durable data survives: SQLite,
the secure store, state.json and the outbox are all on disk and untouched.
state.restore() may give you back the route and blob, because ValenceApp
records them into the OS task snapshot — but OS snapshots are best effort
(contracts §4.8). A kill while backgrounded usually keeps the task, and the next
launch resumes it; a task the OS drops, or one the user swipes out of Recents,
starts at / with null. So save small UI changes as they happen rather than
only on the way out, and never put anything in that blob you could not
regenerate. Nothing keeps the process alive. No callback, no Dart code and no
amount of renderer handling prevents a direct host kill; the only levers are the
app’s own memory use and how long it stays backgrounded.
Distinguish a camera or picker failure
Section titled “Distinguish a camera or picker failure”If capture stops responding, preserve full logcat, exit-info and the ANR record
before recovery. Record which package owns the foreground activity and which
package the ANR names. An ANR in com.android.camera2 is an external camera
failure; it does not establish an ANR in the Valence host or a renderer eviction.
App-c iteration 37 recorded this distinction after a successful Settings return.
Exclude the failed capture from acceptance. After preserving the evidence, retry the external activity and verify that the returned image actually decodes. A successful retry is a separate result; it does not identify or repair the earlier failure. Preserve the host’s database and account, and record any process stop or data reset explicitly. Custom media handlers remain responsible for their own cancellation and error results; these diagnostics add no automatic recovery.
Preserve the database and account. A successful restart does not isolate the cause of an earlier stall, and absence of a wait line does not prove absence of a lock. Unit regression coverage is separate from Android device acceptance; iOS is experimental and untested.
See the host, seed recovery and data and sync for the work these phases observe.