skills/android__skills
1
0
Fork 0
mirror of https://github.com/android/skills.git synced 2026-09-14 20:07:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

Restore lost changes to trace analysis and sql skills (#41)

Browse Source 
Applied diffs to enhance Domain Hints usage and add critical guardrails for trace_processor location.
This commit is contained in:
Yasser Dbeis
2026-05-15 10:58:13 -07:00
committed by GitHub
parent 7cc87324fb
commit a1df0d7a70
3 changed files with 20 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
profilers/perfetto-sql/SKILL.md
+7 -8
View File
@@ -89,14 +89,13 @@ You must follow these steps sequentially, mirroring a multi-agent pipeline:
### Step 0: Tool Setup ### Step 0: Tool Setup
**Fetch the Wrapper:** If you don't have `trace_processor` in your current **Fetch the Wrapper:** You must use the top level of the current project workspace (`./trace_processor`).
working directory or in your path, download it directly from the Perfetto index:
`curl -LO https://get.perfetto.dev/trace_processor && chmod +x > **CRITICAL GUARDRAIL:** NEVER use filesystem search tools (`find`, `find_by_name`, `grep`, `dir /s`, `Get-ChildItem`) across the home directory or workspace to locate `trace_processor` — unconstrained searches across entire workspaces will stop responding or time out.
./trace_processor`
> **Important:** The file served at this URL is a `~10KB` Python wrapper script. Perform a direct file check at the top level of your workspace (e.g., `ls trace_processor`). If missing, download `https://get.perfetto.dev/trace_processor` directly into the root workspace (`curl -LO`), make it executable on macOS/Linux (`chmod +x`), and ensure `trace_processor` is added to `.gitignore`. Execute queries directly via `./trace_processor` (on Windows, explicitly invoke `python trace_processor`).
> Don't assume the download failed because it is human-readable text. This is
> the intended behavior. This script handles lazy-loading the real binary into > **Important:** The file served at this URL is a `~10KB` Python wrapper script. Don't assume the download failed because it is human-readable text. This is the intended behavior. This script handles lazy-loading the precompiled binary automatically on its first run. Use it directly.
> `~/.local/share/perfetto/` on its first run. Use it directly.
### Step 1: Dissection and Schema Research ### Step 1: Dissection and Schema Research
profilers/perfetto-trace-analysis/SKILL.md
+6 -5
View File
@@ -20,7 +20,7 @@ metadata:
## Resources ## Resources
- **Domain Hints:** Reference files for specific performance areas: [`CPU`](references/hints_cpu.md), [`Graphics`](references/hints_graphics.md), [`I/O`](references/hints_io.md), [`IPC`](references/hints_ipc.md), [`Memory`](references/hints_memory.md), [`Power`](references/hints_power.md). - **Domain Hints:** Reference files for specific performance areas: [`CPU`](references/hints_cpu.md), [`Graphics`](references/hints_graphics.md), [`I/O`](references/hints_io.md), [`IPC`](references/hints_ipc.md), [`Memory`](references/hints_memory.md), [`Power`](references/hints_power.md). 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](references/sql.md). You must read this reference and follow its Execution Protocol for all SQL generation. - **Perfetto SQL Reference:** Reference guidelines for translating intents into valid queries are located in [the SQL reference](references/sql.md). You must read this reference and follow its Execution Protocol for all SQL generation.
## Setup Phase (Mandatory) ## Setup Phase (Mandatory)
@@ -30,8 +30,9 @@ metadata:
- 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. - 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. - 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. - DO NOT write preliminary hypotheses or premature conclusions in the scratchpad. It is a strict Chain of Evidence.
2. **Review SQL Reference:** Read the SQL reference in [`references/sql.md`](references/sql.md) and follow its Execution Protocol for all SQL generation. Do not guess schemas. 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. **Target Resolution:** If the user's request is broad (e.g., "why is the app slow?") and doesn't specify a package name: 3. **Review SQL Reference:** Read the SQL reference in [`references/sql.md`](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 - Execute a query to identify the active application: `sql INCLUDE
PERFETTO MODULE android.startup.startups; SELECT package FROM PERFETTO MODULE android.startup.startups; SELECT package FROM
android_startups;` android_startups;`
@@ -43,7 +44,7 @@ Follow this iterative loop until you have isolated the definitive root cause(s):
### 1. Formulate Hypothesis ### 1. Formulate Hypothesis
- **Prioritization:** Form hypotheses using information from: user prompt \> built-in hints ([`references/hints_*.md`](references/hints_cpu.md)) \> general knowledge. - **Prioritization:** Form hypotheses using information from: user prompt \> "Domain Hints" ([`CPU`](references/hints_cpu.md), [`Graphics`](references/hints_graphics.md), [`I/O`](references/hints_io.md), [`IPC`](references/hints_ipc.md), [`Memory`](references/hints_memory.md), [`Power`](references/hints_power.md)) \> 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..."). - **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. - **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. - **State Reasoning:** Briefly state your reasoning based on previous findings *before* generating a new query.
@@ -63,7 +64,7 @@ Follow this iterative loop until you have isolated the definitive root cause(s):
### 4. Exhaustive Investigation (Do Not Give Up Early) ### 4. Exhaustive Investigation (Do Not Give Up Early)
- **Multiple Bottlenecks:** Complex performance issues rarely have a single cause. Do NOT stop your investigation after finding the first anomaly. Even if you find a major bottleneck (e.g., emulator graphics lag), you MUST continue searching for other independent system-wide issues (e.g., lock contention, I/O stalls). - **Multiple Bottlenecks:** Complex performance issues rarely have a single cause. Do NOT stop your investigation after finding the first anomaly. Even if you find a major bottleneck (e.g., emulator graphics lag), you MUST continue searching for other independent system-wide issues (e.g., lock contention, I/O stalls). To find other bottlenecks, search through the content of the "Domain Hints" files ([`CPU`](references/hints_cpu.md), [`Graphics`](references/hints_graphics.md), [`I/O`](references/hints_io.md), [`IPC`](references/hints_ipc.md), [`Memory`](references/hints_memory.md), [`Power`](references/hints_power.md)) to retrieve and leverage expert-vetted, powerful trace analysis techniques. Investigate each relevant hint with depth.
- **Global Verification:** Periodically perform a system-wide query for the longest running slices (`ORDER BY slice.dur DESC`) and most frequent D-states to ensure your local investigation hasn't missed a massive, unrelated system stall. - **Global Verification:** Periodically perform a system-wide query for the longest running slices (`ORDER BY slice.dur DESC`) and most frequent D-states to ensure your local investigation hasn't missed a massive, unrelated system stall.
- **Persist Through Dead Ends:** If a hypothesis is disproven or a query returns empty, do not conclude. Pivot your focus, broaden your search constraints (fuzzy matching, wider time windows), and continue the mission. - **Persist Through Dead Ends:** If a hypothesis is disproven or a query returns empty, do not conclude. Pivot your focus, broaden your search constraints (fuzzy matching, wider time windows), and continue the mission.
profilers/perfetto-trace-analysis/references/sql.md
+7 -8
View File
@@ -69,14 +69,13 @@ You must follow these steps sequentially, mirroring a multi-agent pipeline:
### Step 0: Tool Setup ### Step 0: Tool Setup
**Fetch the Wrapper:** If you don't have `trace_processor` in your current **Fetch the Wrapper:** You must use the top level of the current project workspace (`./trace_processor`).
working directory or in your path, download it directly from the Perfetto index:
`curl -LO https://get.perfetto.dev/trace_processor && chmod +x > **CRITICAL GUARDRAIL:** NEVER use filesystem search tools (`find`, `find_by_name`, `grep`, `dir /s`, `Get-ChildItem`) across the home directory or workspace to locate `trace_processor` — unconstrained searches across entire workspaces will stop responding or time out.
./trace_processor`
> **Important:** The file served at this URL is a `~10KB` Python wrapper script. Perform a direct file check at the top level of your workspace (e.g., `ls trace_processor`). If missing, download `https://get.perfetto.dev/trace_processor` directly into the root workspace (`curl -LO`), make it executable on macOS/Linux (`chmod +x`), and ensure `trace_processor` is added to `.gitignore`. Execute queries directly via `./trace_processor` (on Windows, explicitly invoke `python trace_processor`).
> Don't assume the download failed because it is human-readable text. This is
> the intended behavior. This script handles lazy-loading the real binary into > **Important:** The file served at this URL is a `~10KB` Python wrapper script. Don't assume the download failed because it is human-readable text. This is the intended behavior. This script handles lazy-loading the precompiled binary automatically on its first run. Use it directly.
> `~/.local/share/perfetto/` on its first run. Use it directly.
### Step 1: Dissection and Schema Research ### Step 1: Dissection and Schema Research