tools/trace.md hands out --engine PATH to a reader who downloaded
trace_processor_shell themselves, and nothing read the path: an empty value, a
typo, a folder or a file without its execute bit went into
TraceProcessor(trace=..., config=...), the first thing that starts the engine.
Perfetto answers the first three with a bare Exception('Path to binary is not
valid (<path>)') and the fourth with PermissionError out of subprocess - each a
traceback, exit 1 (the status a run that read a trace and failed returns), and
a message naming neither --engine nor tools/trace.md.
opener() now judges the path first, so flamechart.py (which opens its traces
with the same opener) answers the same way: exit 2, the path named, and the two
ways out (download one, or leave --engine out). A path that is a runnable file
still reaches Perfetto, and no --engine still means download one.
Conflict on merge: the FrameTimeline guard from this PR wraps the missed-deadline count, and the function keeps returning (out, anchor, end) as #951's flame chart needs.
The second of the performance tools proposed in #564: a PNG for a pull request that shows where a
change's time went.
- One panel per trace, one lane per thread, every slice on the same time scale, so the faster run is
visibly shorter. Slices matching --highlight are magenta and totalled, a match's children once,
with the change against the first panel.
- A folder draws its median run (by time to the first frame, or the median frame time for nav), not
its best, and the panel says which run it is.
- --window first-frame (start to first frame drawn), start:MS, or all; --threads picks the lanes.
- It reuses trace_report.py's queries: start_window() now returns the start and first-frame times
the report already worked out.
- Pillow joins perfetto in the optional tools/requirements-perf.txt. Drawing uses Pillow's own font,
so it renders the same on any system.
- tools/flamechart.md says how to draw the two charts a Home change usually needs, and how to read
one honestly.
Tests run without the query engine and, apart from the one drawing test, without Pillow.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The first of the performance tools proposed in #564. tools/bench.py gives the headline numbers;
these show where the launcher's time goes:
- trace.py records a Perfetto trace on the TV around a scenario (home, cold, coldsys, nav, or your
own setup and steps). Setup runs before the recording starts, so it stays out of the trace. A
force-stop's accessibility helpers are put back after the last run with bench.py's own helpers.
Recording needs nothing beyond tools/requirements.txt.
- trace_report.py reports each run, the median and range, and with --vs the change in each median:
start to first frame drawn and the lifecycle steps inside it, frames and missed deadlines after
it, and for nav the frame and GPU times. --markdown prints tables for a pull request; a run over
twice the median is starred.
- tools/requirements-perf.txt holds the one optional dependency, perfetto. tools/requirements.txt is
unchanged, and nothing under launcher/ changes.
- tools/trace.md is the guide: when to use which tool, the one download and how to avoid it, the
scenarios, and what can mislead.
The tests run offline. trace_report's SQL is plain SQLite, so it runs against an in-memory table
laid out like a trace; the one test that needs the real query engine skips unless it is installed
and CLEANYOURTV_TRACE names a trace.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Sandiv Dathunarachchi