Skip to content

Debloat any Android or Google TV over Wi-Fi and get an Apple TV-style home.

tools: trace_report.py judges its --engine path before Perfetto starts

xbsheng97dd9fb0e6c5
diff --git a/tests/test_trace_report.py b/tests/test_trace_report.py
index bc0eeb7bf..140768062 100644
--- a/tests/test_trace_report.py
+++ b/tests/test_trace_report.py
@@ -354,6 +354,85 @@ class FilesTest(unittest.TestCase):
self.assertIn("requirements-perf.txt", str(caught.exception.code))
+class EnginePathTest(unittest.TestCase):
+ """--engine is judged before Perfetto is imported and before a trace is opened.
+
+ Perfetto answers a path that is not a binary with a bare Exception("Path to binary is not valid
+ (<path>)") and a file without its execute bit with PermissionError out of subprocess: both a traceback
+ with exit 1, the status a run that read a trace and failed returns, naming neither --engine nor
+ tools/trace.md. Perfetto is made unimportable here, so a value that slips past the check is answered
+ with its install line instead of an engine being started.
+ """
+
+ def refuse(self, engine):
+ """stderr from opener(engine), with the run refusing it as an argument error."""
+ err, out = io.StringIO(), io.StringIO()
+ with mock.patch.dict(sys.modules, {"perfetto": None, "perfetto.trace_processor": None}), \
+ contextlib.redirect_stderr(err), contextlib.redirect_stdout(out), \
+ self.assertRaises(SystemExit) as caught:
+ report.opener(engine)
+ self.assertEqual(caught.exception.code, 2, f"{engine!r} was not answered as an argument error")
+ self.assertEqual(out.getvalue(), "")
+ message = err.getvalue()
+ self.assertNotIn("Traceback", message)
+ self.assertNotIn("requirements-perf.txt", message) # not Perfetto's answer: ours, before the import
+ self.assertIn("No trace was read.", message)
+ return message
+
+ def test_a_path_that_is_not_there_names_the_path_and_the_way_out(self):
+ message = self.refuse("/nope/trace_processor_shell")
+ self.assertIn("--engine /nope/trace_processor_shell is not a file", message)
+ self.assertIn("tools/trace.md", message)
+
+ def test_an_empty_engine_is_not_read_as_no_engine(self):
+ for engine in ("", " "):
+ with self.subTest(engine=engine):
+ self.assertIn("--engine is empty", self.refuse(engine))
+
+ def test_a_folder_is_not_a_file(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ message = self.refuse(tmp)
+ self.assertIn(f"--engine {tmp} is not a file", message)
+
+ @unittest.skipUnless(os.name == "posix", "the execute bit is POSIX's; on Windows the engine is an .exe")
+ def test_a_downloaded_engine_without_its_execute_bit(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ engine = Path(tmp, "trace_processor_shell")
+ engine.write_bytes(b"#!/bin/sh\n")
+ engine.chmod(0o644)
+ message = self.refuse(str(engine))
+ self.assertIn(f"--engine {engine} is not executable", message)
+ self.assertIn("chmod +x", message)
+
+ def test_an_engine_that_can_be_run_still_reaches_perfetto(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ engine = Path(tmp, "trace_processor_shell")
+ engine.write_bytes(b"#!/bin/sh\n")
+ engine.chmod(0o755)
+ with mock.patch.dict(sys.modules, {"perfetto": None, "perfetto.trace_processor": None}), \
+ contextlib.redirect_stderr(io.StringIO()), self.assertRaises(SystemExit) as caught:
+ report.opener(str(engine))
+ self.assertIn("requirements-perf.txt", str(caught.exception.code),
+ "the good path was refused instead of tried")
+
+ def test_no_engine_at_all_is_left_to_perfetto_to_download(self):
+ with mock.patch.dict(sys.modules, {"perfetto": None, "perfetto.trace_processor": None}), \
+ contextlib.redirect_stderr(io.StringIO()) as err, self.assertRaises(SystemExit) as caught:
+ report.opener(None)
+ self.assertIn("requirements-perf.txt", str(caught.exception.code))
+
+ def test_the_report_answers_a_typo_before_it_reads_the_trace(self):
+ with tempfile.TemporaryDirectory() as tmp:
+ trace = Path(tmp, "home-1.pftrace")
+ trace.write_bytes(b"")
+ with contextlib.redirect_stderr(io.StringIO()) as err, \
+ contextlib.redirect_stdout(io.StringIO()) as out, self.assertRaises(SystemExit) as caught:
+ report.main([str(trace), "--engine", "/nope/trace_processor_shell"])
+ self.assertEqual(caught.exception.code, 2)
+ self.assertEqual(out.getvalue(), "")
+ self.assertIn("/nope/trace_processor_shell is not a file", err.getvalue())
+
+
class MainTest(unittest.TestCase):
def open_trace(self, path):
q = fake_trace(frames=[16])
diff --git a/tools/trace.md b/tools/trace.md
index a639a4f94..a5630b5d1 100644
--- a/tools/trace.md
+++ b/tools/trace.md
@@ -12,7 +12,10 @@ tools/venv/bin/pip install -r tools/requirements-perf.txt
Recording needs only `tools/requirements.txt` and a TV on Android 9 or later. The report's first run
downloads Perfetto's query engine (about 13 MB, SHA-256 checked) to `~/.local/share/perfetto`. To avoid
-that, download `trace_processor_shell` yourself and pass `--engine PATH`.
+that, download `trace_processor_shell` yourself and pass `--engine PATH`. The path is read before any
+trace is opened, so it has to be a file with its execute bit set: an empty one, a typo, a folder or a
+file you forgot to `chmod +x` is answered with exit 2 and the path named, rather than a traceback out of
+Perfetto that names neither. `tools/flamechart.py` takes the same option and answers the same way.
On Android 9 and 10, the TV's tracing services must be enabled first; they are enabled by default only
from Android 11. See Perfetto's [tracing-service setup](https://perfetto.dev/docs/quickstart/android-tracing#starting-the-tracing-services)
diff --git a/tools/trace_report.py b/tools/trace_report.py
index 8947cd7dd..7ba6e26f9 100644
--- a/tools/trace_report.py
+++ b/tools/trace_report.py
@@ -7,7 +7,11 @@
TRACES are .pftrace files or folders of them. Needs the optional `perfetto` package
(tools/venv/bin/pip install -r tools/requirements-perf.txt). Its first run downloads Perfetto's query
-engine; --engine PATH uses a trace_processor_shell you downloaded yourself. Read tools/trace.md first.
+engine; --engine PATH uses a trace_processor_shell you downloaded yourself, which has to be a file this
+script can run. Read tools/trace.md first.
+
+Exit status: 0 the tables printed, 1 a trace could not be read or the engine failed, 2 --engine names
+something that is not a file this script can run.
For a start (cold, coldsys, home and custom traces) it reports the time from the launcher starting
(bindApplication in a new process, else performStart) to its first frame drawn, the lifecycle steps
@@ -176,8 +180,40 @@ def _run_order(path):
return (re.sub(r"-\d+\.pftrace$", "", path), int(m.group(1)) if m else 0)
+def engine_path(engine):
+ """The --engine path, judged before Perfetto is imported and before any trace is read.
+
+ tools/trace.md hands out "--engine PATH" to a reader who downloaded trace_processor_shell instead of
+ letting Perfetto fetch one, and nothing here read the path: an empty value, a typo, a folder or a file
+ without its execute bit went straight into TraceProcessor(trace=..., config=...), which is the first
+ thing that starts the engine. Perfetto answers the first three with a bare
+ Exception("Path to binary is not valid (<path>)") - not its own error class, so no caller can catch it -
+ and the fourth with PermissionError out of subprocess, each a traceback with exit 1, the status a run
+ that read a trace and failed returns, naming neither --engine nor tools/trace.md. flamechart.py opens
+ its traces with this same opener(), so it is answered here too.
+ """
+ if engine is None:
+ return None
+ if not engine.strip():
+ raise ValueError("--engine is empty: name the trace_processor_shell you downloaded, or leave "
+ "--engine out to have Perfetto download one (tools/trace.md)")
+ if not os.path.isfile(engine):
+ raise ValueError(f"--engine {engine} is not a file: it is the trace_processor_shell you downloaded "
+ "yourself (tools/trace.md), or leave --engine out to have Perfetto download one")
+ # Windows has no execute bit to read; the engine there is an .exe, and a wrong one fails to start.
+ if os.name == "posix" and not os.access(engine, os.X_OK):
+ raise ValueError(f"--engine {engine} is not executable: run chmod +x on the trace_processor_shell "
+ "you downloaded (tools/trace.md)")
+ return engine
+
+
def opener(engine=None):
"""open(path) -> q(sql) returning rows as dicts, plus close(), using Perfetto's query engine."""
+ try:
+ engine = engine_path(engine)
+ except ValueError as e:
+ print(f"{e}. No trace was read.", file=sys.stderr)
+ sys.exit(2)
try:
from perfetto.trace_processor import TraceProcessor, TraceProcessorConfig
except ImportError: