perfetto-trace-analysis

Run the analyze_lens_trace.py script with the trace file path to get a structured JSON summary of slow frames, top slices, thread activity, and frame timing percentiles. Install the perfetto Python package first using the provided requirements file.

The analysis detects depth-0 slices exceeding the frame budget (16.7ms for Spectacles at 60fps, 33.3ms for mobile at 30fps) and reports p50/p90/p99 frame timing stats. A large p50-to-p90 gap indicates spike-based jank, while consistently high p50 means the main render path is too slow.

Yes, the script auto-detects the capture profile by scoring keywords in thread names, slice names, and metadata, with a confidence level. Spectacles traces use a 16.67ms frame budget while mobile traces use 33.3ms.

You need Python 3.9 or later with perfetto (version 0.16.0+) and pandas, installable from the included requirements-perfetto.txt file. The perfetto library loads the binary trace into an in-memory SQLite database, and pandas formats query results as CSV.

Use Phase 2 SQL drilling when slice names are too generic, you need the call hierarchy inside a slow operation, you suspect CPU scheduling preemption, or capture profile confidence is low. If the JSON summary already supports concrete optimization fixes, stop at Phase 1.

The -u flag disables Python's stdout buffering, which is mandatory because buffered output can deadlock the pipe between the server and the querying process. The server communicates over stdin/stdout using a line-based protocol terminated by END_OF_QUERY.