tp: stdlib: let android.cujs consume CUJs with typed vsync args and cross-process frames
Generalise the android.cujs stdlib so that a CUJ producer which cannot emit
the Android-framework style dynamic instant markers
(`J<X>#FT#beginVsync#<id>`, `#FT#endVsync#<id>`, `#FT#end#0`, `#FT#cancel#0`)
and whose frames are produced by a different process than the one emitting
the `J<X>` slice can still be analysed by android_jank_cuj and friends.
The first such producer is Chrome, which (crrev.com/c/8705993 and follow-ups)
emits a `J<WebContentsScroll>` TrackEvent slice in the renderer process with
`ChromeTrackEvent.android_cuj_metrics.{begin_vsync_id,end_vsync_id,canceled}`
as typed args, while the SurfaceFlinger frame timeline for the scroll belongs
to the GPU process (`com.android.chrome:privileged_process0`). Nothing in the
stdlib is Chrome-specific though; any process emitting the same shape of data
is handled identically.
Changes (all additive, existing paths unchanged):
* base.sql
- New `_cuj_typed_args`: reads `android_cuj_metrics.begin_vsync_id`,
`end_vsync_id` and `canceled` from the CUJ slice's arg set.
- `_cuj_instant_events.begin_vsync/end_vsync`: `coalesce(typed arg,
FT# marker)` - typed args win when present, otherwise identical to before.
- New `_android_jank_cuj_state(cuj_id)`: typed `canceled` (1/0) first, then
the existing FT#cancel / FT#end marker logic. Used by `android_jank_cuj`
and `android_jank_cuj_slice_summary` instead of two inline copies.
- Layer resolution split into `_android_jank_cuj_hwui_layer_name` (the
existing explicit-marker / single-layer inference, unchanged) and a new
Tier-3 `_android_jank_cuj_frame_timeline_layer`. Tier 3 only applies to
CUJs that carry explicit begin/end vsync ids AND have no HWUI frames
(`_all_frames_in_cuj` empty), so anything resolved by Tier 1/2 is never
touched. It picks the `actual_frame_timeline_slice` layer, owned by the
CUJ process or a sibling process of the same package (name up to ':'),
that presented at both the begin and the end vsync; ties prefer the own
process, then most frames in range. It also returns the owning
`timeline_upid`. Public `android_jank_cuj_layer_name` (schema unchanged)
is the union of both.
* boundaries.sql
- `_android_jank_cuj_vsync_boundary`: CUJs are included if they have
`Choreographer#doFrame`s (as before) OR a Tier-3 resolved layer. For the
latter `upid` is the layer-owning process so that the downstream
`expected/actual_frame_timeline_slice` joins (which key on
`boundary.upid`) attribute frames to the right process. Column set is
unchanged (metrics/sql/android/jank/cujs_boundaries.sql does SELECT *).
* frames.sql
- `android_jank_cuj_slice_summary.state` uses `_android_jank_cuj_state`.
* protos/third_party/chromium/chrome_track_event.proto
- Mirror of crrev.com/c/8705993 (`AndroidCujMetrics`, field 1087). Copybara
will import the identical hunk from Chromium; included here so the diff
test can decode the typed args.
Behavioural impact on existing traces:
- CUJs without the typed args and with doFrames: byte-identical output
(verified on a SystemUI trace with BACK_PANEL_ARROW CUJs and a Gmail
trace with ThreadListScroll/ThreadListSwipe, plus all 50 existing
CUJ/Jank diff tests).
- The one intentional change: a marker-only CUJ that has explicit
beginVsync/endVsync markers but no HWUI frames at all previously got no
boundary/frames; it can now get them if exactly one same-package
frame-timeline layer spans its vsync range. CUJs without explicit vsync
bounds are unaffected (Tier 3 requires both).
Tests: new ChromeCujs diff-test suite with a synthetic trace
(chrome_web_contents_scroll_cuj.py): renderer-emitted J<WebContentsScroll>
slices with typed args (one completed, one canceled), GPU-process frame
timeline with one app-missed frame, and distractor frames from the browser
process and SystemUI at overlapping vsyncs. Covers android_jank_cuj, state,
boundary + layer, slice summary and per-frame attribution.
Perfetto is an open-source suite of tools for recording, visualizing and analyzing traces: timelines of what software and the system under it were doing. It is the default tracing system for Android and Chromium. System-wide recording works on Android and Linux. The tracing SDK, the UI and Trace Processor also run on macOS and Windows.
perf, Firefox Profiler, macOS Instruments, pprof, systrace, Fuchsia and more.Open an example Android trace without installing anything, or drag your own trace file onto ui.perfetto.dev.
On Android, with a device connected over adb:
curl -O https://raw.githubusercontent.com/google/perfetto/main/tools/record_android_trace python3 record_android_trace -o trace.pftrace -t 10s sched freq gfx view am wm
The trace opens in the Perfetto UI when recording finishes.
On Linux, record scheduling activity with tracebox:
curl -LO https://get.perfetto.dev/tracebox && chmod +x tracebox curl -LO https://raw.githubusercontent.com/google/perfetto/main/test/configs/scheduling.cfg sudo ./tracebox -o trace.pftrace --txt -c scheduling.cfg
For Chrome, use the recording page in the UI. To trace your own app, see in-app tracing.
curl -LO https://get.perfetto.dev/trace_processor && chmod +x trace_processor ./trace_processor query trace.pftrace \ "SELECT name, COUNT(*) AS cnt FROM slice GROUP BY name ORDER BY cnt DESC LIMIT 10"
Or from Python:
pip install perfetto
from perfetto.trace_processor import TraceProcessor tp = TraceProcessor(trace='trace.pftrace') print(tp.query('SELECT ts, dur, name FROM slice LIMIT 10').as_pandas_dataframe())
ftrace. (Linux cookbook)chrome://tracing, for debugging the browser, V8 and Blink. (Chrome tracing)Not sure where to start? How do I start using Perfetto? picks a path based on what you want to do.
Perfetto is a collection of components that work together:
traced, traced_probes) collect data from many processes and the kernel into a single trace file.See the documentation for the full picture.
See Community and getting help for more. We follow Google's Open Source Community Guidelines.
Contributions are welcome. The contributor guide covers building, testing and sending pull requests.
The Debian packaging of Perfetto is maintained in the Debian Perfetto Salsa repository.
Apache 2.0. See LICENSE for details.