gracker/perfetto-skills/perfetto-performance-analysis

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

1. 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.

1. Record every input trace path, SHA-256, requested process/thread, time range,

and trace side before analysis.

1. Run scripts/perfetto_probe.py before domain queries. Treat unavailable

tables, modules, tracks, or trace signals as limitations, not negative evidence.

1. Select one primary workflow below. Load its Markdown file directly, then

follow its availability gate and evidence sequence.

1. 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.

1. Before executing authored or modified SQL, run

the SQL guardrail script. Resolve blocking findings and review advisories using the SQL guardrail contract.

1. 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.

1. For comparisons, analyze each trace independently before computing deltas.

Never use a missing metric on one side as proof that the other side regressed.

1. 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

Pass only the Skill's declared inputs through --param; the runner rejects any other name before touching the trace. A Skill with a process identity gate also accepts its identity aliases (package, process_name, ...): the gate verifies the named process with the process_identity_resolver Skill and rewrites the alias to the verified process.name. An unverified or ambiguous target is refused with the reason (identity_blocked); pick an exact process name from that Skill's candidates instead of retrying the same name. A verified upid (or a pid with one UPID) runs the Skill on exactly that process; a Skill whose SQL cannot run that way is refused with the Skills that can.

Complete Skill runs and --query-id runs verify the selected processor's commit, RPC API, platform, and SHA-256 against the release lock 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. A placeholder ${name|default} uses its default when name is omitted, resolves to JSON null, or indexes past the rows of a saved result, so a defaulted path to an empty prior step needs no --result:

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.