perfetto-sql

Translate natural-language trace analysis intents into Perfetto SQL queries and execute them.

1|Updated Mar 17, 2026
One-click install
npx skills add https://github.com/premex-ab/claude-marketplace --skill perfetto-sql
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: perfetto-sql
Source: https://github.com/premex-ab/claude-marketplace/tree/main/plugins/android-perfetto-sql/skills/perfetto-sql
Command: npx skills add https://github.com/premex-ab/claude-marketplace --skill perfetto-sql

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It translates natural-language performance data requests into syntactically valid Perfetto SQL, then executes those queries against a local Android Perfetto trace to produce the exact metrics you need.

Core Features & Use Cases

  • Natural-language to Perfetto SQL: Converts intents like “CPU frequency around a timestamp” or “total time spent in slices matching a pattern” into correct SQL.
  • Trace_processor execution: Runs the generated SQL via the official Perfetto trace_processor wrapper and returns results in CSV.
  • Safety and correctness guardrails: Enforces idempotent object creation, correct module/schema usage from perfetto-stdlib.md, safe SPAN_JOIN patterns, and correct handling of incomplete durations (dur = -1).

Quick Start

Ask the skill: "Extract all slice durations for threads whose name matches RenderThread from the attached trace file and return the total time in milliseconds."

Frequently Asked Questions about perfetto-sql

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I query Android Perfetto traces to extract thread slice durations?

Query Android Perfetto traces by translating natural-language intents into valid SQL and executing them via trace_processor. This extracts slice and thread performance data, such as total time spent in a specific thread, returning results in CSV format.

What is SPAN_JOIN in Perfetto SQL and when do I need it for trace analysis?

SPAN_JOIN in Perfetto SQL is a mechanism to combine interval data from different tables based on overlapping time ranges. You need it for trace analysis when calculating overlaps between slices or aggregating metrics across concurrent thread executions.

Can I use natural language to investigate CPU frequency changes in an Android trace?

Yes, you can use natural language to investigate CPU frequency changes. The system converts your intent into Perfetto SQL, queries the trace file via trace_processor, and returns the exact CPU frequency or startup-request metrics requested.

How do I handle incomplete slice durations when analyzing Perfetto trace data?

To handle incomplete slice durations in Perfetto trace data, your SQL queries must account for the specific edge case where dur = -1. Correct query construction ensures these incomplete intervals do not skew your performance aggregations.

Does Perfetto SQL require strict schema validation from the standard library?

Yes, Perfetto SQL requires strict standard library schema and module validation to ensure correctness. This enforces safe idempotent object creation and correct module usage, preventing errors during trace_processor execution.