reis-mobile 0.3.5 → 0.4.0

package/skills/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/hints_io.md

@@ -0,0 +1,46 @@
+---
+subsystem: io
+description: >
+  Expert hints for I/O and storage bottlenecks, uninterruptible sleep, and
+  page cache.
+keywords:
+  - i/o
+  - storage
+  - disk
+  - uninterruptible sleep
+  - d state
+  - page fault
+  - dm-verity
+  - file
+  - syscall
+---
+
+# I/O & Storage Expert Hints
+
+- When debugging a long, uninterruptible sleep state related to I/O: Check for
+  overlapping slices with "verity" in their name (dm-verity).
+- When a thread is stuck in an uninterruptible sleep with no `blocked_function`,
+  look for other threads that might be holding the memory lock (for example,
+  "jit-thread-pool", memory mapping ops).
+- When analyzing a long uninterruptible sleep, check the `blocked_function` in
+  the thread state details (from `sched_blocked_reason` ftrace event).
+- A lot of time spent in `do_page_fault` during app startup is a strong
+  indicator of I/O contention.
+- For file integrity mechanisms like DM-Verity, search for events like
+  `dm_verity_fec_prefetch`.
+- To find the specific kernel dependency of a stalled app thread, locate the
+  thread in state 'D', then look for kworker or kernel threads that become
+  runnable immediately after.
+- For app stalls caused by I/O, analyze the scheduling latency of the relevant
+  kworker threads handling the request.
+- To find inefficient file I/O, query the syscall table for a high frequency
+  of small, sequential `read()` or `pread()` syscalls on a single fd.
+- If a thread spends significant time in 'Uninterruptible Sleep', check if
+  `blocked_function` is `page_cache_readahead`. Correlate waking timestamps
+  with `filemap_add_to_page_cache` ftrace events.
+- Aggregate counts of `filemap_add_to_page_cache` grouping by `inode` to find
+  the specific file causing I/O pressure.
+- Inspect `nr_sector` in `block_rq_issue` ftrace events to understand file
+  read-ahead size.
+- If an I/O issue disappears on subsequent launches, it is a 'cold start'
+  problem (populating page cache).

package/skills/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/hints_ipc.md

@@ -0,0 +1,41 @@
+---
+subsystem: ipc
+description: >
+  Expert hints for IPC, binder transactions, and cross-process dependencies.
+keywords:
+  - ipc
+  - binder
+  - transaction
+  - cross-process
+  - bottleneck
+  - service
+  - system_server
+---
+
+# IPC & Binder Expert Hints
+
+- Look for multiple outbound binder transactions from the same process
+  (`system_server`) that carry similar data to different destinations in a
+  short time frame. This "binder storm" indicates a lack of multiplexing.
+- To trace data across processes, correlate slices using flow events by
+  linking a slice's ID to `flow.source_slice_id` or `flow.dest_slice_id`.
+- To detect binder spam, query the `binder_transaction` table and group by
+  thread ID (`tid`), `service_name`, and `method_name` to find high numbers of
+  identical calls.
+- When high binder concurrency is found, identify the bottleneck server
+  process by grouping transactions by `server_upid`.
+- To analyze latency of a slow binder transaction, calculate time spent
+  outside the server by subtracting `server_dur` from total `dur` in the
+  `binder_transaction` table.
+- When a thread is suspected of binder spam, correlate its `tid` with the
+  `cpu_slice` table to check for high CPU consumption.
+- To find code responsible for binder spam, get the `utid` of the problematic
+  thread and use it to query `stack_profile_callsite`.
+- To find callers of a problematic function, filter `stack_profile_callsite`
+  for frames mapping to it, then trace upwards using `parent_id`.
+- A long-running slice on one thread causally linked to a slice on another
+  thread (for example, binder from `system_server` to SystemUI) indicates a
+  scheduling dependency bottleneck.
+- To find asynchronous operations that might cause UI jank, look for a binder
+  transaction from a controlling process that returns quickly, followed by a
+  long-running slice in the receiving process.

package/skills/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/hints_memory.md

@@ -0,0 +1,55 @@
+---
+subsystem: memory
+description: >
+  Expert hints for memory pressure, Low Memory Killer (LMK), and allocations.
+keywords:
+  - memory
+  - lmk
+  - lmkd
+  - oom
+  - rss
+  - swap
+  - kswapd
+  - thrashing
+  - pressure
+  - allocation
+---
+
+# Memory & LMK Expert Hints
+
+- To investigate low memory kills, look for the `lmk_kill_occurred` ftrace
+  event; a high count indicates severe memory pressure.
+- When you see a burst of `lmk_kill_occurred` events, query for processes with
+  high CPU `wall_duration` in the `sched_slice` table during the same time
+  window. Runaway processes consuming CPU exacerbate memory pressure.
+- To understand a process's memory impact, inspect its `anon_rss` (Anonymous
+  Resident Set Size) from memory counters like `mem.info`.
+- Check system-wide memory stats for a high or rapidly increasing `swap_used`
+  value.
+- To confirm memory thrashing, look for high CPU usage by the `kswapd` kernel
+  thread.
+- To find the direct trigger for LMKD, look for `memory_pressure` trace events
+  from Pressure Stall Information (PSI).
+- To detect 'lost' memory for processes using hardware accelerators (like a
+  TPU), query the `counter` table for `RssFile` values. If it drops
+  significantly while hardware is active, check for `kswapd0` scheduling
+  slices.
+- When analyzing memory shared with hardware, query `dma_heap_stat` and
+  `dmabuf_total_size` counters (or `ion_total_size` for older devices) for a
+  more accurate picture than RSS.
+- Be aware that `RssFile` can over-report memory if the same physical page is
+  mapped multiple times.
+- When investigating OOMs, establish a baseline by querying process memory
+  counters (for example, `mem.rss`) and compare the median and 95th percentile
+  against its history.
+- If bitmaps are a major memory consumer, check for outliers in bitmap count by
+  querying `android.graphics.Bitmap` instances across traces.
+- To find what is holding onto an object (like a bitmap), trace its retainer
+  path back to a GC root by querying `heap_graph_reference`. Pay close
+  attention to custom application classes.
+- Query the `android_bitmaps` table to check the width and height properties of
+  bitmaps.
+- Check for the presence of software bitmaps, which consume memory on both the
+  app heap and in graphics memory.
+- When analyzing bitmaps, look for duplicates by checking for multiple
+  `android.graphics.Bitmap` objects with identical properties.

package/skills/android-profiler/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/hints_power.md

@@ -0,0 +1,33 @@
+---
+subsystem: power
+description: >
+  Expert hints for battery drain, power rails, network traffic, and wake locks.
+keywords:
+  - power
+  - battery
+  - wake lock
+  - suspend
+  - network
+  - modem
+  - bluetooth
+  - drain
+---
+
+# Power & Network Expert Hints
+
+- When investigating overall battery drain, start by querying `power_rails`
+  track and summing energy consumed (`power_ma * duration`) for each rail.
+- To check if a device is sleeping correctly during screen-off periods, query
+  the `suspend_state` track; a lack of time in "suspended" state indicates a
+  wakefulness problem.
+- To find the root cause of the device failing to suspend, query the
+  `kernel_wakelock` track and aggregate total duration for each wake lock.
+- If a top kernel wake lock name contains "bt_" or "bcm" (for example,
+  `bt_host_wake`), cross-reference its timing with events in the
+  `bluetooth_scan_results` track.
+- If the modem rail in `power_rails` shows high consumption, query the
+  `network_packets` table and aggregate traffic volume by UID to identify app.
+- When analyzing network traffic from a shared UID, use the `socket_tag`
+  associated with network packets for granular attribution.
+- Convert impact into a common energy unit like milliwatt-hours (mWh) to
+  compare the severity of different issues.

package/skills/android-profiler/analysis/workflows/perfetto-trace-analysis/references/per_candidate_analysis.md

@@ -0,0 +1,172 @@
+# Candidate Investigation Protocol
+
+This is the execution protocol for a deep-dive subagent during trace analysis.
+
+## Context
+
+Execute the protocol below using the candidate details (Trace Paths, Symptom
+Window, UTID, UPID, System Vitals) provided in your initial prompt.
+
+## Investigation Protocol
+
+**High-Level Algorithm:**
+
+1. Prerequisites (Step 1)
+2. Calculate time distribution and identify state buckets (Step 2)
+3. Domain and System hints discovery and selection (Step 3)
+4. Run exhaustive investigation for each significant state bucket sequentially
+   (Steps 4 and 5), starting with the largest bucket. Output total time
+   explained so far after investigating each.
+5. Output the result (Step 6)
+
+### Step 1: Prerequisites
+
+- Follow `$SKILL_ROOT/references/perfetto/sql.md` for session-based query execution.
+- Read
+  `$SKILL_ROOT/analysis/workflows/perfetto-trace-analysis/references/guiding_principles.md`
+  to identify best practices, ensure data-driven analysis, and avoid pitfalls.
+
+### Step 2: Calculate the time distribution
+
+1. **Establish a baseline if possible:** For example, if investigating a jank
+   candidate, find a _non-janky_ instance of the **same** operation first to
+   establish expected behavior and rule out red herrings. _If no healthy
+   instance exists in the trace, note this as a `[GAP]` and proceed with the
+   next steps_.
+2. **Calculate time spent in each state:** Sum the time spent in `Running`,
+   `R`, `S` and `D` states. Investigate all substantial buckets. Also look for
+   composite bottlenecks (for example, "40% CPU-starved + 35% IO-blocked").
+3. **Run checks to rule out red herrings:** For example:
+   - A thread in `S` state could be normal behavior -> investigate only if
+     the sleep actually overlaps with a pending obligation (for example, a
+     pending binder reply).
+   - A thread in `Running/Runnable`: When a thread spends high duration in
+     `Running/Runnable`, inspect CPU frequency, throttling counters, and core
+     migrations before attributing latency to code inefficiency, because
+     hardware throttling inflates wall time without increasing instruction
+     overhead:
+     - Verify first that an identified code path is actually doing
+       disproportionate work.
+     - Query the trace to find what the thread was doing during this window.
+       Query the `slice` table for the longest duration slices during this
+       window.
+     - Beyond blocking slices, query and identify repetitive micro-operations
+       or gaps that collectively exhaust the budget to prevent tunnel vision.
+     - Perform a system-wide check to identify if there was CPU throttling or
+       core migrations around the symptom window (see Principle 7).
+4. **Drill down:** For every significant bucket revealed from the time
+   distribution analysis during the symptom window, identify what the thread
+   was doing at the transition point. Investigate every significant bucket (for
+   example, >= 20% of the time window) to avoid missing real bottlenecks or
+   composite issues.
+> **Action:** Tag missing data as `[GAP]`. Do not guess.
+
+### Step 3: Domain and Hints Discovery
+
+Even if you find a major bottleneck, continue searching for other bottlenecks
+using expert-vetted domain and system hints and techniques. Follow these steps
+in order:
+
+- **Domain discovery:** Use your file search tools (for example, `grep_search`)
+  to scan frontmatter (`domain:`, `description:`, `keywords:`) in
+  `$SKILL_ROOT/analysis/workflows/perfetto-trace-analysis/references/hints/domains/`
+  (if it exists) and identify matching domain hint files based on collective
+  investigation state (victim, intermediate processes).
+- **Subsystem hints:** Use your file search tools to scan frontmatter
+  (`subsystem:`, `description:`, `keywords:`) in
+  `$SKILL_ROOT/analysis/workflows/perfetto-trace-analysis/references/hints/subsystems/`
+  for relevant tracks (for example, keywords for sleep states, memory, IPC).
+- **Hint Selection and Application:** Apply all the matched subsystem and
+  domain hint files during the Step 4 investigation, and list them under
+  `Applied Hints` in your Step 6 output.
+
+### Step 4: Exhaustive Investigation (Do Not Give Up Early)
+
+- **Follow the dependency chain:**
+  - If the victim thread was waiting or blocked by another thread, follow the
+    chain to the leaf. Find out what it is waiting _for_. Cross process
+    boundaries if necessary. Do not conclude without following the entire
+    blocker chain (See Principle 4 in `guiding_principles.md`).
+  - **Dynamic hint injection:** If your dependency chain leads to a new
+    subsystem or process you haven't researched yet, do a single search in
+    `$SKILL_ROOT/analysis/workflows/perfetto-trace-analysis/references/hints/`
+    for relevant hints before proceeding. Do not fall into infinite loops.
+  - Every state bucket investigation should end in one of three states:
+    **Terminal root cause**, **Blocked by another thread**, or
+    **Partial suspect**.
+
+    > A finding is a "terminal root cause" if:
+    >
+    > - You can trace it down to a physical bottleneck (thermal throttle, GPU,
+    >   storage). **Require Specificity:** Do not conclude with generic labels.
+    >   Specify the _what_ clearly.
+    > - A specific function or code path is identified as doing disproportionate
+    >   work relative to its purpose (for example, synchronous disk IO on main
+    >   thread, unnecessary object allocation triggering GC).
+    > - A scheduling policy or resource limit is identified as artificially
+    >   constraining the thread (for example, background CPU cap, foreground
+    >   service restriction).
+    > - The bottleneck is identified in a different process/service that the
+    >   investigated process cannot control (for example, `system_server` lock
+    >   contention, `SurfaceFlinger` throttling).
+
+- **Systemic sweep before concluding:** Discovering an application-layer
+  bottleneck (software root cause) does not terminate the investigation of a
+  state bucket. Before concluding any state bucket as a terminal root cause,
+  check relevant system hints for that state (`CPU`, `IO`, `Memory`, `IPC`)
+  and verify whether platform-level confounds - such as CPU scaling, memory
+  pressure, thermal throttling, or I/O saturation - simultaneously degraded
+  performance **around the symptom window.** Report discovered systemic
+  confounds as **co-root causes** or duration modifiers (see Principle 7 in
+  `guiding_principles.md`).
+
+**Why:** Software execution duration is not an absolute constant; it is
+modulated by platform state (frequency scaling, thermals, memory reclamation).
+Always check system-wide confounds before reporting an inefficient code path as
+the sole root cause - to avoid concluding inflated software duration as the
+sole root cause while missing the underlying kernel or hardware anomaly that
+magnified it. Back findings with empirical proof (`[SQL]`) or mark as `[GAP]`
+if inconclusive.
+
+### Step 5: Contextualize the Workload
+
+Once the mechanical bottleneck is identified in Step 4, query the trace to
+identify the high-level user feature, UI operation, or exact workload that
+triggered it. Explain the _why_, not just the _what_. This workload context
+ensures that we can provide actionable next steps for the user instead of
+leaving them confused.
+
+### Step 6: Output
+
+Output the following investigation result:
+
+```markdown
+# Investigation Result
+
+Candidate:
+Symptom Window: [Start TS] and [End TS]
+Symptom Duration: [Duration]
+Budget (Expected Duration): [If applicable]
+Applied Hints: [List of matched subsystem and domain hint files used]
+
+## Primary Finding
+
+- **Classification:** [Hardware | Software/Code | System Exhaustion | Scheduling Policy | External Dependency]
+- **Details and Reasoning:** `___`
+- **Explained Duration:** `___`
+- **Evidence SQL or backing data:** `___`
+- **Dependency chain:** [Root to Leaf Dependency Chain]
+- **Root cause conclusion:** `___`
+
+## Other Findings
+
+- **Status:** [Partial Suspect | Low Confidence Suspicion | Terminal Root Cause]
+- _(same fields)_
+
+## Verification Checklist
+
+- All claims tagged (`[SQL]`/`[GAP]`/`[INFERRED]`): [yes/no]
+- Total explained time accounts for most of the symptom window: [yes/no]
+- Unexplored state buckets: [none/list with reason why]
+- Workload contextualized (for example, specific slices/layers involved): [yes/no]
+```

package/skills/android-profiler/analysis/workflows/perfetto-trace-analysis/references/triage.md

@@ -0,0 +1,94 @@
+# System-Wide Triage
+
+Follow these steps in order:
+
+1. **Verify data integrity:** Query `stats` for CPU and data loss indicators.
+   If found, warn the user that findings may be incomplete and proceed with
+   `[GAP]` awareness.
+
+2. **Run metrics:** Systemic issues (like thermal throttling, LMKs, binder
+   contention) affect all threads.
+
+   > **Prerequisite:** Verify that `trace_processor` is available in your
+   > environment before executing commands (see
+   > `$SKILL_ROOT/references/perfetto/setup.md`).
+
+   Run the following query based on the user's intent to understand the
+   high-level picture:
+
+   ```sh
+   trace_processor [trace_file] --run-metrics [comma_separated_metrics]
+   ```
+
+3. **Define target and symptom window:** Find the specific issue's start
+   (`ts`), duration (`dur`) and end timestamp (`ts + dur`). Verify the trace
+   actually covers the full window.
+
+   > After identifying the specific instance to investigate and the symptom
+   > window (for example, janky frame at `ts = 5.1s`), check whether the first
+   > blocking event was caused by a stall that _started before_ the symptom
+   > window. Expanding the window upstream is essential because stalls (for
+   > example, in binder servers, memory reclamation or kernel locks) often
+   > originate hundreds of milliseconds before the user-visible frame drop or
+   > latency spike occurs.
+   >
+   > - Find the victim's first non-Running state transition within the symptom
+   >   window.
+   > - Follow the waker chain for that transition. Check waker timestamps -
+   >   if the blocking event began significantly before the symptom window,
+   >   expand the investigation window upstream to include that origin.
+   > - If it cascades down to an origin in another process (for example, a
+   >   binder server that stalled `500ms` before the jank), **note** the
+   >   expanded window and include the upstream stall as a co-candidate to
+   >   investigate further.
+
+4. **Output** the triage summary using the format defined below.
+
+## Quick reference for triaging
+
+Key available metrics for `--run-metrics`:
+`android_startup`, `android_cpu`, `android_mem`, `android_lmk`,
+`android_binder`, `android_surfaceflinger`, `android_gpu`
+
+Quick lookup table based on symptom:
+
+| Symptom/Issue    | What to check                         | Useful Perfetto tables                          |
+| :--------------- | :------------------------------------ | :---------------------------------------------- |
+| App startup      | Main thread                           | `android.startup.startups` (`android_startups`) |
+| App jank         | Main, render threads                  | `actual_frame_timeline_slice`                   |
+| System jank      | SurfaceFlinger                        | `actual_frame_timeline_slice`                   |
+| App/system crash | `Process crashed` or `tombstoned`     | `slice`                                         |
+| ANR              | Main thread, `system_server` watchdog | `thread_state`, `slice`                         |
+| Frame issues     | `DrawFrame` or `doFrame` slices       | `slice`                                         |
+
+## Final Output Format
+
+Output the triage summary in the following format:
+
+```markdown
+## Trace Metadata
+
+- **Device Model:** `[String, e.g., Pixel 7 Pro]`
+- **Android Build:** `[String, e.g., TQ2A.230505.002]`
+
+## System Vitals Summary
+
+- **Status:** `[Nominal | Degraded | Critical]`
+- **Flags Raised:** _(Only list systemic issues that are actually detected)_
+  - **Metric:** `[String, e.g., thermal_throttling, lmkd, binder_contention]`
+  - **Description:** `[e.g., 'Thermal throttling during symptom window']`
+
+## Candidate
+
+- **Issue Classification:** `[String, e.g., Startup, Jank, ANR_Input, Crash]`
+- **Package Name:** `[String]`
+- **Process Name:** `[String]`
+- **Thread Name:** `[String]`
+- **UPID:** `[Integer]`
+- **Target UTID:** `[Integer]` _(The primary thread)_
+- **Render Thread UTID:** `[Integer or null]` _(If issue is jank)_
+- **Start TS:** `[Integer Timestamp]`
+- **End TS:** `[Integer Timestamp]`
+- **Duration (ms):** `[Float]`
+- **Severity Note:** `[String, e.g., '150ms missed frame - worst instance']`
+```

package/skills/android-profiler/recording/recording_orchestrator.md

@@ -0,0 +1,36 @@
+# Recording Orchestrator
+
+Use the guidelines below to orchestrate between recording workflows after
+disambiguating the user intent (for example, recording a system trace or a
+heap dump). The guidelines below ensure pre-flight checks are always performed
+and domain-specific profiling flags are applied accurately.
+
+## Workflow Selection
+
+At this point, you should have an answer to the following question: "User
+intends to record a _____". For example, "User intends to record a system
+trace".
+
+## Handling Composite Requests
+
+If the user's request involves multiple distinct recording goals (for example,
+setting up a specialized environment AND recording a generic trace), do not
+execute them simultaneously.
+
+1. Break down the request and propose a sequential execution plan to the user.
+2. Ask the user for confirmation to start the first step.
+3. Do not proceed to the next workflow until the current one is completed.
+
+## Workflow Discovery and Routing
+
+This skill supports multiple specialized recording workflows. To determine the
+right workflows to use:
+
+1. Use your file search tools (for example, `grep_search`) to recursively scan
+   the `$SKILL_ROOT/recording/workflows/` directory for workflow entrypoints
+   (markdown files defining a top-level `name:` key in their frontmatter,
+   ignoring internal `references/` subdirectories).
+2. Compare the user's request and intent against the `name:`, `description:`,
+   and `keywords:` fields to identify matching workflows. If multiple are
+   found, present them as options to the user and proceed with the
+   user's selection.

package/skills/android-profiler/recording/workflows/perfetto-trace-recording/perfetto_trace_recording.md

@@ -0,0 +1,148 @@
+---
+name: perfetto-trace-recording
+description: >
+  Records Java/native heap dumps, system traces, or custom configs via
+  Perfetto helper scripts on Android.
+keywords:
+  - perfetto
+  - record
+  - system trace
+  - heap dump
+  - memory leak
+  - custom config
+---
+
+# Recording Perfetto Traces on Android (Helper Scripts)
+
+> [!IMPORTANT] **Scope:** This guide is **strictly for recording traces on
+> Android devices**. For other platforms (Linux, macOS, or Chrome), refer to
+> the platform documentation on [perfetto.dev/docs](https://perfetto.dev/docs/).
+
+Rather than running raw `adb` commands, use the official Perfetto helper
+scripts. They automatically handle pushing configurations, starting tracing
+daemons, pulling the trace file, and optionally opening it in the browser.
+
+Ensure **Developer options** and **USB debugging** are enabled, and your
+device is connected via USB before starting.
+
+---
+
+## 0. Download the Helper Scripts
+
+Download the helper scripts from the official Perfetto repository:
+
+```bash
+TOOLS_URL="https://raw.githubusercontent.com/google/perfetto/main/tools"
+
+# Java Heap Dump (ART)
+curl -O "$TOOLS_URL/java_heap_dump" && chmod +x java_heap_dump
+
+# Native Heap Profiling (heapprofd)
+curl -O "$TOOLS_URL/heap_profile" && chmod +x heap_profile
+
+# CPU Stack Sampling (traced_perf)
+curl -O "$TOOLS_URL/cpu_profile" && chmod +x cpu_profile
+
+# General Tracing (Ftrace, ATrace, custom configs)
+curl -O "$TOOLS_URL/record_android_trace" && chmod +x record_android_trace
+```
+
+---
+
+## 1. Memory Tracing
+
+Use these tools to analyze memory leaks, object retention, C/C++ allocations,
+or system-wide memory counters.
+
+### A. Java Heap Dump (ART)
+
+Capture a snapshot of all Java objects in a process to investigate memory
+leaks. Reference docs:
+<https://perfetto.dev/docs/data-sources/java-heap-profiler>.
+
+```bash
+# Trigger a Java heap dump for a specific app
+./java_heap_dump -n YOUR_APP_PACKAGE_NAME -o ./heap_dump.perfetto-trace
+```
+
+### B. Native C/C++ Heap Profiling (heapprofd)
+
+Track C/C++ memory allocations (malloc/free) to find native leaks. Reference
+docs: <https://perfetto.dev/docs/data-sources/native-heap-profiler>.
+
+```bash
+# Profile native allocations for a specific app
+./heap_profile -n YOUR_APP_PACKAGE_NAME
+
+# Profile with custom sampling interval (default is 4096 bytes)
+./heap_profile -n YOUR_APP_PACKAGE_NAME -i 2048
+```
+
+### C. System-wide Memory Counters
+
+Track RSS, Swap, and process stats over time. Reference docs:
+<https://perfetto.dev/docs/data-sources/memory-counters-sys-stats>.
+
+**Note:** To record memory counters, you must use a custom config via
+`record_android_trace` (see Section 4).
+
+---
+
+## 2. Stack Sampling / Callstack Profiling (traced_perf)
+
+Identify CPU hotspots in C/C++ or Rust code by periodically sampling
+callstacks. Reference docs:
+<https://perfetto.dev/docs/data-sources/cpu-profiler>.
+
+```bash
+# Profile CPU usage by sampling callstacks at 100Hz (default) for 10 seconds
+./cpu_profile -n YOUR_APP_PACKAGE_NAME -d 10000
+
+# Profile at a custom frequency (e.g., 200Hz)
+./cpu_profile -n YOUR_APP_PACKAGE_NAME -f 200
+```
+
+---
+
+## 3. System Tracing (CPU, Scheduling, & ATrace)
+
+Investigate jank, slow transitions, CPU scheduling, and system calls.
+Reference docs: <https://perfetto.dev/docs/data-sources/ftrace>.
+
+You can specify duration, buffer size, and categories directly on the command
+line:
+
+```bash
+# Record scheduling, frequency, and window manager events for 5 seconds
+./record_android_trace -t 5s -b 32mb sched gfx wm -a YOUR_APP_PACKAGE_NAME
+```
+
+Common categories: `sched` (CPU scheduling), `freq` (CPU frequency), `gfx`
+(Graphics), `am` (Activity Manager), `wm` (Window Manager), `view` (View
+System).
+
+---
+
+## 4. Custom Configs (Mix & Match Data Sources)
+
+If you need a custom mixture of data sources (e.g., combining Java heap dumps
+with ftrace), or control that command-line flags do not offer (ring buffers,
+long traces, per-counter polling), synthesize a config:
+
+1. **Read the config reference:**
+   `$SKILL_ROOT/recording/workflows/perfetto-trace-recording/references/trace_config_reference.md`
+   explains config structure and data sources, pointing to exemplar configs in
+   `$SKILL_ROOT/recording/workflows/perfetto-trace-recording/references/example-configs/`
+   that you can start from and merge. For other sources, consult the
+   official guide at <https://perfetto.dev/docs/data-sources/>.
+2. **Save the Config:** Write the synthesized text configuration to a local
+   file (e.g., `config.pftxt`).
+3. **Execute the Trace:** Run the trace using the general recorder script
+   `record_android_trace` (specialized scripts do not accept custom configs):
+
+```bash
+./record_android_trace -c config.pftxt -o ./my_trace.perfetto-trace
+```
+
+If the config has a typo, this fails fast with a parse error naming the bad
+field - fix the config and retry.

package/skills/android-profiler/recording/workflows/perfetto-trace-recording/references/example-configs/app_jank.pftxt

@@ -0,0 +1,43 @@
+# App jank / slow UI: framework + app atrace events, frame deadlines from
+# SurfaceFlinger, and the scheduling context underneath.
+# Replace com.example.myapp with the app's package name.
+buffers {
+  size_kb: 65536
+  fill_policy: RING_BUFFER
+}
+duration_ms: 10000
+
+data_sources {
+  config {
+    name: "linux.ftrace"
+    ftrace_config {
+      ftrace_events: "sched/sched_switch"
+      ftrace_events: "sched/sched_wakeup"
+      ftrace_events: "sched/sched_waking"
+      ftrace_events: "power/cpu_frequency"
+      ftrace_events: "power/cpu_idle"
+      atrace_categories: "gfx"
+      atrace_categories: "view"
+      atrace_categories: "wm"
+      atrace_categories: "am"
+      atrace_categories: "input"
+      atrace_apps: "com.example.myapp"
+    }
+  }
+}
+
+# Per-frame expected vs actual timelines (actual jank classification).
+data_sources {
+  config {
+    name: "android.surfaceflinger.frametimeline"
+  }
+}
+
+data_sources {
+  config {
+    name: "linux.process_stats"
+    process_stats_config {
+      scan_all_processes_on_start: true
+    }
+  }
+}