License: AGPL-3.0-or-later. Source: Perfetto Skills.
\nAnalyze traces from evidence instead of guessing from symptom names. Use the\nbundled scripts for deterministic queries and load only the references needed\nfor the selected workflow.
\nUse Python 3.11+, local filesystem and terminal access, and a checksum-verified\nPerfetto trace_processor_shell. Run independently after installation; neither\nSmartPerfetto nor an upstream Perfetto checkout is required.
SKILL.md. Convert\nscript and reference paths to absolute paths before executing them; do not\nassume a client-specific environment variable exists.scripts/perfetto_probe.py before domain queries. Treat unavailable\ntables, modules, tracks, or trace signals as limitations, not negative\nevidence.scripts/perfetto_skill.py run,\nor one manifest query through scripts/perfetto_query.py --query-id. Keep query source,\nparameters, trace identity, timestamps, durations, units, and returned row\nbounds with every saved result.assets/report-schema.json. List missing evidence and\nunresolved alternatives under limitations.Read the evidence contract, then use\nidentity rules,\nmissing-data rules, and\nclaim verification before writing\nconclusions.
\nUse the machine-readable workflow index when\nselecting or validating workflow IDs.
\nList or run a deterministic portable Skill graph:
\npython3 <skill-root>/scripts/perfetto_skill.py list\npython3 <skill-root>/scripts/perfetto_skill.py run /absolute/trace.pftrace \\\n --skill startup_analysis --param 'package=\"com.example\"' \\\n --output-dir /absolute/output/run\nPass only the Skill's declared inputs through --param; the runner rejects\nany other name before touching the trace. A Skill with a process identity gate\nalso accepts its identity aliases (package, process_name, ...): the gate\nverifies the named process with the process_identity_resolver Skill and\nrewrites the alias to the verified process.name. An unverified or ambiguous\ntarget is refused with the reason (identity_blocked); pick an exact process\nname from that Skill's candidates instead of retrying the same name. A\nverified upid (or a pid with one UPID) runs the Skill on exactly that\nprocess; a Skill whose SQL cannot run that way is refused with the Skills that\ncan.
Complete Skill runs and --query-id runs verify the selected processor's\ncommit, RPC API, platform, and SHA-256 against the release lock before\nexecuting SQL. Inspect that\nidentity independently with:
python3 <skill-root>/scripts/perfetto_doctor.py\nUse --allow-unsupported-processor only for an explicitly labeled canary; it\ndoes not turn the result into verified evidence. A capability-gated query runs\nonly after an automatic probe for the same trace proves its required schema;\nthe gate result remains in the evidence sidecar. --allow-unverified is a\nseparate opt-in only for a query explicitly classified as unverified and never\nbypasses a missing capability.
Probe a trace:
\npython3 <skill-root>/scripts/perfetto_probe.py /absolute/path/to/trace.pftrace \\\n --output /absolute/path/to/output/probe.json\nRun a referenced SQL asset:
\npython3 <skill-root>/scripts/perfetto_query.py /absolute/path/to/trace.pftrace \\\n --sql-file <skill-root>/references/generated/sql/<query>.sql \\\n --format json --output /absolute/path/to/output/query.json\nBind SmartPerfetto DSL placeholders through the public wrapper instead of\nediting SQL text. --param NAME=JSON safely binds scalar inputs and JSON\narrays (rendered as SQL literal lists for IN (...)),\n--module android.example.module loads declared prerequisites, and\n--result NAME=/path/prior.json exposes a non-empty saved row array as a\nrelation for a dependent step. Pipeline expressions such as\n${prior_step.data[0].upid} select a scalar field from those rows. A\nplaceholder ${name|default} uses its default when name is omitted,\nresolves to JSON null, or indexes past the rows of a saved result, so a\ndefaulted path to an empty prior step needs no --result:
python3 <skill-root>/scripts/perfetto_query.py /absolute/trace.pftrace \\\n --sql-file <skill-root>/references/generated/sql/<skill>/<step>.sql \\\n --module android.frames.timeline \\\n --param 'package=\"com.example\"' --param start_ts=123 \\\n --result prior_step=/absolute/output/prior-step.json \\\n --output /absolute/output/current-step.json\nThe runtime rejects unresolved placeholders and caps trace-processor stdout and\nstderr at 16 MiB by default. Lower the bound with --max-output-bytes; increase\nit only for a reviewed, explicitly bounded query.
For comparison, first write one side-summary file per independently analyzed\ntrace using assets/comparison-input-schema.json, then run\nscripts/perfetto_compare.py --side baseline=a.json --side candidate=b.json --baseline baseline.
If trace_processor_shell is unavailable, run\nscripts/bootstrap_trace_processor.py or provide a locked executable through\n--trace-processor or PERFETTO_TRACE_PROCESSOR.
Generated references are numerous. Find a SmartPerfetto Skill, SQL step, table,\nor signal without loading the whole catalog:
\nrg -n \"<skill-id|table|signal>\" <skill-root>/references/generated\nLoad the directly linked result and its source provenance. Do not infer step\nsemantics from a filename alone.
\nRequire Python 3.11+, filesystem access, terminal execution, and a compatible\nPerfetto trace_processor_shell. The portable instructions work in Codex,\nClaude Code, OpenCode, and other clients that implement Agent Skills and expose\nthose capabilities. Cloud-only agents without local file or terminal access can\nuse the methodology references but cannot execute trace queries.