Skip to content

Prototype performance measurement

Compose compiler reports

From the repository root, run:

scripts/android/compose-compiler-report.sh

The script compiles :control-proxy:compileReleaseKotlin --rerun with -Pautomobile.composeCompilerReports=true. Only the exact property value true enables compiler reports and metrics; normal builds do not configure their output destinations. The rerun forces compiler execution even with cached outputs. The reports land in the compose-compiler-reports directory of the control-proxy module’s Gradle build output: control-proxy-composables.txt is at its root and the module metrics are in release/control-proxy-module.json. The property alone does not force a recompile, so an up-to-date or cached compile writes nothing.

To summarize existing reports without Gradle, use --reports-dir DIR. Use --package PREFIX to select fully qualified function names starting with PREFIX. (default: dev.jasonpearson.automobile.ctrlproxy.prototype). Use --write-doc docs/how-it-works/plat/android/prototype-compose-compiler-report.md to overwrite the generated Compose compiler report page; stdout still contains the same deterministic summary.

The totals count listed functions, including value-returning helpers and overloads. The table sorts simple function names, preserving report order for overloads. Restartable means Compose can independently restart the function; skippable means it can skip a call when its arguments have not changed. Unstable parameters list explicit unstable markers; the final column lists parameters with no compiler stability marker. Stable parameters are omitted, and — means none. Default-value annotations are removed. The module-wide line reports counts for the entire module, not just the selected package.

With strong skipping on (featureFlags.StrongSkipping = true), every restartable composable is skippable, so the useful signal is the unstable and unmarked parameters, which are compared by instance identity rather than equals when unstable at runtime. The captured module aggregate has different totals from this package listing; compare the same report scope across measurements.

Frame-time benchmark

Prerequisites: a connected Android device explicitly selected by ID, a compatible CtrlProxy with its accessibility service enabled, adb, bun, jq, and an already running AutoMobile daemon. The script never starts or configures a daemon. If the device belongs to a session, export its AUTOMOBILE_SESSION_UUID; the script passes it as --session-uuid on every CLI call. Measure a release-like build; debug numbers are only comparable with debug numbers (see #12129).

scripts/android/prototype-frame-benchmark.sh --device DEVICE_ID
scripts/android/prototype-frame-benchmark.sh --list
scripts/android/prototype-frame-benchmark.sh --dry-run --device DEVICE_ID
scripts/android/prototype-frame-benchmark.sh --device DEVICE_ID --scenario tab-switch --markdown

The fixed fullscreen spec is benchmark/prototype-frame/spec.json, ID perf-benchmark. It expands to approximately 900 mapped nodes, including hidden subtrees, 150 list rows, 30 images, four state-selected tab bodies, four pager pages, and more than 70 visibility conditions. Individual repeats stay within the 128-item contract limit. The pager, controls, tab body, and collapsing section have bounded regions so the long list can scroll without moving the scenario controls offscreen.

The image contract requires asset IDs. The 30 nodes reference benchmark-image; missing assets render placeholders. To record an image-decoding baseline, first upload a representative PNG/JPEG/WebP as benchmark-image through prototype’s assets argument. The default script does not push assets, so it measures placeholders and its results must be labelled that way.

benchmark/prototype-frame/scenarios.json is the single source of truth. Each entry has name, description, repeat, settleMs, and steps; idle additionally has durationMs. Each step has tool and text; swipes additionally have direction. The script converts text to a tap selector or swipe container and explicitly uses layer: prototype. It sleeps after each complete repetition, or for idle’s specified duration. Other steps have no extra sleep between commands.

Scenario Repeats Steps per repeat Settle
idle 1 No input; count frames rendered in 3 seconds 3000 ms duration
tab-switch 5 Tab 2, Tab 3, Tab 4, Tab 1 600 ms
section-collapse 4 Toggle section twice (collapse, reopen) 600 ms
pager-swipe 4 Swipe Benchmark pager left, right 600 ms
scroll 4 Swipe Benchmark list up, down 600 ms
overlay-open 1 Open overlay, Close overlay 600 ms
three-write-tap 5 three-write tap (three independent counter increments) 600 ms

The script shows the spec once and waits --show-settle-ms N (default 2000 ms) for initial composition before the first reset. N must be a non-negative integer; 0 skips this wait. It resets dumpsys gfxinfo before each scenario, captures it afterward, and always attempts to dismiss this prototype on exit. Plain output is exactly one line per scenario:

scenario=tab-switch frames=100 janky_pct=5.00 p50_ms=8 p90_ms=12 p95_ms=16 p99_ms=22 slow_ui=1
scenario=idle error=missing-fields

Percentiles and slow UI counts come directly from gfxinfo. Capture failures or missing fields produce an error line, continue with remaining scenarios, and exit 1. An idle dump with no percentile fields reports an error rather than inventing zero latency; its acceptance metric remains the actual frames rendered in 3 seconds. The --markdown option prints a table with the same fields and an error column. The --scenario option is repeatable; selected scenarios retain file order. The --package, --spec, and --scenarios options override defaults. The --device option is mandatory except for --list and --dry-run; dry-run prints every command, including sleep and cleanup, and runs none. The PROTOTYPE_BENCH_ADB and PROTOTYPE_BENCH_CLI variables accept executable paths, such as private CLI wrappers; the default CLI is bun <repo>/src/index.ts --cli.

Feed benchmark

The feed driver reuses the gfxinfo harness with a deterministic fullscreen perf-feed lazy list (1,000 rows by default, up to the contract cap of 2,000). It needs the same Android prerequisites and an existing daemon/session. Measure a release-like build on API 37; the target is p95 < 16 ms per scenario.

scripts/android/prototype-feed-benchmark.sh --device DEVICE_ID --rows 1000 --markdown
scripts/android/prototype-feed-benchmark.sh --device DEVICE_ID --enforce
scripts/android/prototype-feed-benchmark.sh --dry-run
bun scripts/prototype/generate-feed-benchmark-spec.ts --rows 1000 --out /tmp/feed.json
bun scripts/prototype/generate-feed-benchmark-spec.ts --rows 1000 --paging --page-url http://localhost:8080/page --out /tmp/paged-feed.json
scripts/ios/prototype-feed-benchmark.sh --device SIMULATOR_UDID --rows 1000 --swipes 6

feed-scenarios.json defines feed-idle (three seconds without input), feed-scroll-down (two up/up/down/down repetitions), and feed-fling-roundtrip (three consecutive up swipes then three down). The latter uses ordinary swipeOn commands: the harness has no velocity setting and does not guarantee a physical fling. There are 14 swipe calls and 4.8 seconds of scenario waits, plus the initial two-second settle; the intended run budget is under three minutes with a responsive CLI/device. The Benchmark feed content description selects the list container.

The Android wrapper prints the harness plain output, an optional Markdown verdict table, and a verdict line per scenario. A numeric p95 of 16 ms or higher fails; zero-frame or unavailable percentiles are n/a. The default reports timing failures; --enforce makes them exit nonzero. Harness capture/CLI errors always retain their nonzero status. --package selects the gfxinfo package, and PROTOTYPE_FEED_BENCH_FRAME overrides the harness executable for offline testing.

Rows contain a local-asset avatar, author, caption, counters and a Like state action. The harness supplies the tiny benchmark-image PNG. This measures placeholder/local-asset rows, not remote-image loading or representative image decoding (remote images are unavailable, #14181). The default spec has no network actions. The --paging option requires an HTTP(S) --page-url reachable from the device; the fixture response is {"items":[...]} with the same row fields and globally unique IDs. The request.append action extends /data/feed/items; the bounded list trims oldest rows at the contract cap. Use fresh IDs and an empty final page to stop end-triggered loading. This optional fixture variant needs a separate show/scroll acceptance run; the wrapper measures the pure-scroll variant.

The iOS driver shows the same spec, uses placeholder avatars, scrolls up for the first half of the calls and down for the rest, then dismisses it. It requires an already available compatible prototype host and daemon, accepts PROTOTYPE_BENCH_CLI, and forwards AUTOMOBILE_SESSION_UUID. It reports elapsed wall-clock milliseconds for each CLI swipe step and for the scroll loop, including CLI/transport overhead and excluding show/dismiss. These are not frame times; simulators expose no gfxinfo. --swipes accepts 1–100 (default 6); --dry-run prints commands without executing them.

Trace sections

The renderer emits nine trace sections (#12128). The names are stable so Perfetto queries can be shared between measurements. All sections use the framework android.os.Trace (no new dependency). All sections are emitted only while tracing is enabled via Trace.isEnabled (API 29+); below API 29 none is emitted and no android.os.Trace method is called. The async-section calls also need API 29.

Section name Insertion point Kind Status
Prototype.interact PrototypeController.interact, inside mutex.withLock, from after the stale-runtime check to the end Async section (the body suspends and may resume on another thread) in renderer
Prototype.validateStateWrite PrototypeRuntime.validated, whole body Synchronous in renderer
Prototype.prepareStateWrites PrototypeRuntime.validated, only the branch that calls prepareStateWrites(from) (first write, and after a host replace) Synchronous, nested in Prototype.validateStateWrite in renderer
Prototype.mapRenderTree PrototypeRenderMapper.map, the miss path only (after the same-snapshot early return) Synchronous in renderer
Prototype.mapPrototypeSpec mapPrototypeSpec in PrototypeRenderModel.kt, whole body (the uncached full mapping used outside a runtime) Synchronous in renderer
Prototype.syncAppearance PrototypeController.interact, around syncAppearance(runtime, model) and syncTextFieldFocus(model) Async section (appearance event delivery and host focus updates can suspend) in renderer
Prototype.compose PrototypeRuntimeContent, around the PrototypeSpecContent call Synchronous, begin/end without try (composable calls) in renderer
Prototype.node RenderPrototypeNodeContent, first and last statement of the body Synchronous, constant name; slices per frame = nodes recomposed in renderer
Prototype.host.show PrototypeHost.showOnMain, whole body Synchronous in renderer

Count Prototype.node slices per frame (per Choreographer#doFrame) to measure the number of nodes recomposed, the target metric for renderer work. Those inside Prototype.compose come from a new render model; node-local recompositions can run outside that slice. Prototype.mapRenderTree should appear at most once per Prototype.interact.

Vertical scroll first-show cost

scroll composes and measures every child up front (Box(verticalScroll), no LazyColumn), so every row stays findable. The gated PrototypeScrollMeasurementTest (PROTOTYPE_SCROLL_MEASURE=1, optional PROTOTYPE_SCROLL_MEASURE_OUT=<file>) disposes and recomposes a fullscreen scroll of 36 dp rows 15 times after 5 warm-ups under Robolectric. It times setContent through waitForIdle (first composition plus measure and layout; no draw). Robolectric numbers are not device frame times; the on-device figure for the benchmark list comes from scripts/android/prototype-frame-benchmark.sh --scenario scroll.

Background