Perfetto Performance Analysis
License: AGPL-3.0-or-later. Source: Perfetto Skills.
Analyze traces from evidence instead of guessing from symptom names. Use the
bundled scripts for deterministic queries and load only the references needed
for the selected workflow.
Requirements
Use Python 3.11+, local filesystem and terminal access, and a checksum-verified
Perfetto trace_processor_shell. Run independently after installation; neither
SmartPerfetto nor an upstream Perfetto checkout is required.
Operating contract
- Resolve the Skill root as the directory containing this
SKILL.md. Convert
script and reference paths to absolute paths before executing them; do not
assume a client-specific environment variable exists.
- Record every input trace path, SHA-256, requested process/thread, time range,
and trace side before analysis.
- Run
scripts/perfetto_probe.py before domain queries. Treat unavailable
tables, modules, tracks, or trace signals as limitations, not negative
evidence.
- Select one primary workflow below. Load its Markdown file directly, then
follow its availability gate and evidence sequence.
- Execute a complete exported Skill through
scripts/perfetto_skill.py run,
or one manifest query through scripts/perfetto_query.py --query-id. Keep query source,
parameters, trace identity, timestamps, durations, units, and returned row
bounds with every saved result.
- Before executing authored or modified SQL, run
the SQL guardrail script. Resolve blocking findings and review
advisories using the SQL guardrail contract.
- Separate observations, correlations, mechanisms, and verified root causes.
Do not promote a hypothesis without evidence that supports the claimed
process, thread, time window, and trace.
- For comparisons, analyze each trace independently before computing deltas.
Never use a missing metric on one side as proof that the other side regressed.
- Emit the structure in
assets/report-schema.json. List missing evidence and
unresolved alternatives under limitations.
Read the evidence contract, then use
identity rules,
missing-data rules, and
claim verification before writing
conclusions.
Workflow routing
- Trace health, bounds, identity, and broad triage: trace overview
- Cold, warm, hot, and first-frame startup: startup
- Frame production, presentation, scrolling, and jank: scrolling
- Touch, click, input dispatch, response, and navigation: interaction
- ANR, Binder, locks, futex, and blocking chains: ANR and blocking
- CPU load, topology, frequency, idle, IRQ, and scheduler latency: CPU scheduling
- RSS, heap, GC, LMK, DMA-BUF, and allocation: memory
- GPU, SurfaceFlinger, fences, VRR, and frame composition: GPU rendering
- Rails, wakelocks, battery, thermal, and throttling: power and thermal
- Filesystem, block IO, network, modem, media, and WebView: IO, network, and media
- Compose, Flutter, React Native, games, and vendor signals: frameworks and games
- Rendering architecture detection and teaching: rendering pipeline
- Cross-domain event sequence reconstruction: scene reconstruction
- Two or more traces or saved result sets: trace comparison
Use the machine-readable workflow index when
selecting or validating workflow IDs.
Runtime commands
List or run a deterministic portable Skill graph:
python3 <skill-root>/scripts/perfetto_skill.py list
python3 <skill-root>/scripts/perfetto_skill.py run /absolute/trace.pftrace \
--skill startup_analysis --param 'package="com.example"' \
--output-dir /absolute/output/run
Complete Skill runs and --query-id runs verify the selected processor's
v57.2 commit, RPC API, platform, and SHA-256 before executing SQL. Inspect that
identity independently with:
python3 <skill-root>/scripts/perfetto_doctor.py
Use --allow-unsupported-processor only for an explicitly labeled canary; it
does not turn the result into verified evidence. A capability-gated query runs
only after an automatic probe for the same trace proves its required schema;
the gate result remains in the evidence sidecar. --allow-unverified is a
separate opt-in only for a query explicitly classified as unverified and never
bypasses a missing capability.
Probe a trace:
python3 <skill-root>/scripts/perfetto_probe.py /absolute/path/to/trace.pftrace \
--output /absolute/path/to/output/probe.json
Run a referenced SQL asset:
python3 <skill-root>/scripts/perfetto_query.py /absolute/path/to/trace.pftrace \
--sql-file <skill-root>/references/generated/sql/<query>.sql \
--format json --output /absolute/path/to/output/query.json
Bind SmartPerfetto DSL placeholders through the public wrapper instead of
editing SQL text. --param NAME=JSON safely binds scalar inputs and JSON
arrays (rendered as SQL literal lists for IN (...)),
--module android.example.module loads declared prerequisites, and
--result NAME=/path/prior.json exposes a non-empty saved row array as a
relation for a dependent step. Pipeline expressions such as
${prior_step.data[0].upid} select a scalar field from those rows:
python3 <skill-root>/scripts/perfetto_query.py /absolute/trace.pftrace \
--sql-file <skill-root>/references/generated/sql/<skill>/<step>.sql \
--module android.frames.timeline \
--param 'package="com.example"' --param start_ts=123 \
--result prior_step=/absolute/output/prior-step.json \
--output /absolute/output/current-step.json
The runtime rejects unresolved placeholders and caps trace-processor stdout and
stderr at 16 MiB by default. Lower the bound with --max-output-bytes; increase
it only for a reviewed, explicitly bounded query.
For comparison, first write one side-summary file per independently analyzed
trace using assets/comparison-input-schema.json, then run
scripts/perfetto_compare.py --side baseline=a.json --side candidate=b.json --baseline baseline.
If trace_processor_shell is unavailable, run
scripts/bootstrap_trace_processor.py or provide a locked executable through
--trace-processor or PERFETTO_TRACE_PROCESSOR.
Reference discovery
Generated references are numerous. Find a SmartPerfetto Skill, SQL step, table,
or signal without loading the whole catalog:
rg -n "<skill-id|table|signal>" <skill-root>/references/generated
Load the directly linked result and its source provenance. Do not infer step
semantics from a filename alone.
Compatibility
Require Python 3.11+, filesystem access, terminal execution, and a compatible
Perfetto trace_processor_shell. The portable instructions work in Codex,
Claude Code, OpenCode, and other clients that implement Agent Skills and expose
those capabilities. Cloud-only agents without local file or terminal access can
use the methodology references but cannot execute trace queries.
1---2name: perfetto-performance-analysis3description: Analyze Android, Linux, and Chromium Perfetto traces with local trace_processor_shell evidence. Use for startup, scrolling or jank, input latency, ANR, CPU scheduling, memory or GC, Binder or IO, GPU or SurfaceFlinger, power or thermal, rendering-pipeline identification, trace capture guidance, scene reconstruction, and single- or multi-trace performance comparison.4---56# Perfetto Performance Analysis78License: AGPL-3.0-or-later. Source: [Perfetto Skills](https://github.com/Gracker/Perfetto-Skills).910Analyze traces from evidence instead of guessing from symptom names. Use the11bundled scripts for deterministic queries and load only the references needed12for the selected workflow.1314## Requirements1516Use Python 3.11+, local filesystem and terminal access, and a checksum-verified17Perfetto `trace_processor_shell`. Run independently after installation; neither18SmartPerfetto nor an upstream Perfetto checkout is required.1920## Operating contract21221. Resolve the Skill root as the directory containing this `SKILL.md`. Convert23 script and reference paths to absolute paths before executing them; do not24 assume a client-specific environment variable exists.252. Record every input trace path, SHA-256, requested process/thread, time range,26 and trace side before analysis.273. Run `scripts/perfetto_probe.py` before domain queries. Treat unavailable28 tables, modules, tracks, or trace signals as limitations, not negative29 evidence.304. Select one primary workflow below. Load its Markdown file directly, then31 follow its availability gate and evidence sequence.325. Execute a complete exported Skill through `scripts/perfetto_skill.py run`,33 or one manifest query through `scripts/perfetto_query.py --query-id`. Keep query source,34 parameters, trace identity, timestamps, durations, units, and returned row35 bounds with every saved result.366. Before executing authored or modified SQL, run37 [the SQL guardrail script](scripts/perfetto_sql_guardrails.py). Resolve blocking findings and review38 advisories using [the SQL guardrail contract](references/evidence/sql-guardrails.md).397. Separate observations, correlations, mechanisms, and verified root causes.40 Do not promote a hypothesis without evidence that supports the claimed41 process, thread, time window, and trace.428. For comparisons, analyze each trace independently before computing deltas.43 Never use a missing metric on one side as proof that the other side regressed.449. Emit the structure in `assets/report-schema.json`. List missing evidence and45 unresolved alternatives under `limitations`.4647Read [the evidence contract](references/evidence/evidence-contract.md), then use48[identity rules](references/evidence/identity.md),49[missing-data rules](references/evidence/missing-data.md), and50[claim verification](references/evidence/claim-verification.md) before writing51conclusions.5253## Workflow routing5455- Trace health, bounds, identity, and broad triage: [trace overview](references/workflows/trace-overview.md)56- Cold, warm, hot, and first-frame startup: [startup](references/workflows/startup.md)57- Frame production, presentation, scrolling, and jank: [scrolling](references/workflows/scrolling.md)58- Touch, click, input dispatch, response, and navigation: [interaction](references/workflows/interaction.md)59- ANR, Binder, locks, futex, and blocking chains: [ANR and blocking](references/workflows/anr-blocking.md)60- CPU load, topology, frequency, idle, IRQ, and scheduler latency: [CPU scheduling](references/workflows/cpu-scheduling.md)61- RSS, heap, GC, LMK, DMA-BUF, and allocation: [memory](references/workflows/memory.md)62- GPU, SurfaceFlinger, fences, VRR, and frame composition: [GPU rendering](references/workflows/gpu-rendering.md)63- Rails, wakelocks, battery, thermal, and throttling: [power and thermal](references/workflows/power-thermal.md)64- Filesystem, block IO, network, modem, media, and WebView: [IO, network, and media](references/workflows/io-network-media.md)65- Compose, Flutter, React Native, games, and vendor signals: [frameworks and games](references/workflows/frameworks-games.md)66- Rendering architecture detection and teaching: [rendering pipeline](references/workflows/rendering-pipeline.md)67- Cross-domain event sequence reconstruction: [scene reconstruction](references/workflows/scene-reconstruction.md)68- Two or more traces or saved result sets: [trace comparison](references/workflows/trace-comparison.md)6970Use [the machine-readable workflow index](references/workflow-index.json) when71selecting or validating workflow IDs.7273## Runtime commands7475List or run a deterministic portable Skill graph:7677```bash78python3 <skill-root>/scripts/perfetto_skill.py list79python3 <skill-root>/scripts/perfetto_skill.py run /absolute/trace.pftrace \80 --skill startup_analysis --param 'package="com.example"' \81 --output-dir /absolute/output/run82```8384Complete Skill runs and `--query-id` runs verify the selected processor's85v57.2 commit, RPC API, platform, and SHA-256 before executing SQL. Inspect that86identity independently with:8788```bash89python3 <skill-root>/scripts/perfetto_doctor.py90```9192Use `--allow-unsupported-processor` only for an explicitly labeled canary; it93does not turn the result into verified evidence. A capability-gated query runs94only after an automatic probe for the same trace proves its required schema;95the gate result remains in the evidence sidecar. `--allow-unverified` is a96separate opt-in only for a query explicitly classified as unverified and never97bypasses a missing capability.9899Probe a trace:100101```bash102python3 <skill-root>/scripts/perfetto_probe.py /absolute/path/to/trace.pftrace \103 --output /absolute/path/to/output/probe.json104```105106Run a referenced SQL asset:107108```bash109python3 <skill-root>/scripts/perfetto_query.py /absolute/path/to/trace.pftrace \110 --sql-file <skill-root>/references/generated/sql/<query>.sql \111 --format json --output /absolute/path/to/output/query.json112```113114Bind SmartPerfetto DSL placeholders through the public wrapper instead of115editing SQL text. `--param NAME=JSON` safely binds scalar inputs and JSON116arrays (rendered as SQL literal lists for `IN (...)`),117`--module android.example.module` loads declared prerequisites, and118`--result NAME=/path/prior.json` exposes a non-empty saved row array as a119relation for a dependent step. Pipeline expressions such as120`${prior_step.data[0].upid}` select a scalar field from those rows:121122```bash123python3 <skill-root>/scripts/perfetto_query.py /absolute/trace.pftrace \124 --sql-file <skill-root>/references/generated/sql/<skill>/<step>.sql \125 --module android.frames.timeline \126 --param 'package="com.example"' --param start_ts=123 \127 --result prior_step=/absolute/output/prior-step.json \128 --output /absolute/output/current-step.json129```130131The runtime rejects unresolved placeholders and caps trace-processor stdout and132stderr at 16 MiB by default. Lower the bound with `--max-output-bytes`; increase133it only for a reviewed, explicitly bounded query.134135For comparison, first write one side-summary file per independently analyzed136trace using `assets/comparison-input-schema.json`, then run137`scripts/perfetto_compare.py --side baseline=a.json --side candidate=b.json138--baseline baseline`.139140If `trace_processor_shell` is unavailable, run141`scripts/bootstrap_trace_processor.py` or provide a locked executable through142`--trace-processor` or `PERFETTO_TRACE_PROCESSOR`.143144## Reference discovery145146Generated references are numerous. Find a SmartPerfetto Skill, SQL step, table,147or signal without loading the whole catalog:148149```bash150rg -n "<skill-id|table|signal>" <skill-root>/references/generated151```152153Load the directly linked result and its source provenance. Do not infer step154semantics from a filename alone.155156## Compatibility157158Require Python 3.11+, filesystem access, terminal execution, and a compatible159Perfetto `trace_processor_shell`. The portable instructions work in Codex,160Claude Code, OpenCode, and other clients that implement Agent Skills and expose161those capabilities. Cloud-only agents without local file or terminal access can162use the methodology references but cannot execute trace queries.
gracker