Perfetto Trace Analysis

Resources

• Domain Hints: Reference files for specific performance areas: CPU, Graphics, I/O, IPC, Memory, Power. These files each contain multiple expert-vetted, powerful trace analysis techniques to steer and aid in the analysis.
• Perfetto SQL Reference: Reference guidelines for translating intents into valid queries are located in the SQL reference. You must read this reference and follow its Execution Protocol for all SQL generation.

Setup Phase (Mandatory)

1. Initialize Scratchpad (Chain of Evidence):
   • Maintain your working memory in a local scratchpad file located in the exact same directory as the target trace file.
   • Name the file using the trace's filename appended with _analysis.md (e.g., [trace_filename]_analysis.md). Before creating it, check if a file with that name already exists by listing the directory's contents---to avoid biasing your investigation, DO NOT read the file's contents to check for its existence. If it does, append an incrementing version number (e.g., _v2.md, _v3.md) until you find an available filename. You MUST hardcode this exact filename in all subsequent tool calls.
   • Use this scratchpad STRICTLY to log verified facts: timestamps, slice names, thread IDs (utid/tid), and thread states.
   • DO NOT write preliminary hypotheses or premature conclusions in the scratchpad. It is a strict Chain of Evidence.
2. Review Domain Hints: Read the Domain Hints in each file to get a high-level overview of what techniques are possible. Make sure to use this baseline knowledge when researching and retrieving hints during the ongoing investigation.
3. Review SQL Reference: Read the SQL reference in references/sql.md and follow its Execution Protocol for all SQL generation. Do not guess schemas.
4. Target Resolution: If the user's request is broad (e.g., "why is the app slow?") and doesn't specify a package name:
   • Execute a query to identify the active application: sql INCLUDE PERFETTO MODULE android.startup.startups; SELECT package FROM android_startups;
   • If multiple packages are returned, ask the user to choose one. Save the chosen package_name to your scratchpad.

Investigation Protocol

Follow this iterative loop until you have isolated the definitive root cause(s):

1. Formulate Hypothesis

• Prioritization: Form hypotheses using information from: user prompt > "Domain Hints" (CPU, Graphics, I/O, IPC, Memory, Power) > general knowledge. Be sure to leverage these "Domain Hints" as they are expert-vetted analysis techniques.
• Source Attribution: Explicitly mention the source of your hypothesis (e.g., "Based on hints_io.md...").
• Focus Constraint: Focus on the primary bottleneck. Avoid investigating deep into binder transactions unless the user explicitly asks for it or there is no other obvious bottleneck.
• State Reasoning: Briefly state your reasoning based on previous findings before generating a new query.

2. Plan and Collect Data

• Metrics First: Start with a high-level view using trace metrics before diving into custom SQL (e.g., ./trace_processor --run-metrics android_startup).
• Broad to Narrow: Begin with broad queries using minimal filters. Favor fuzzy matching (e.g., GLOB '*abc*') over exact matching.
• Overlapping Time: When filtering by time, you MUST check for events that overlap with the target time range (e.g., start1 < end2 AND start2 < end1) to ensure you don't miss slices that span across the boundaries.