android-auto-trace

name	android-auto-trace
description	Capture and analyze Android Perfetto traces via adb. Automatically grabs trace files from connected devices and analyzes process CPU usage and named slice durations. Use when the user wants to capture an Android trace, diagnose high CPU usage, analyze CPU usage of a process, or find the total execution time of named trace slices.

Android Auto Trace

Overview

Automates Android Perfetto trace capture and analysis via adb.

Quick Start

1. Capture trace: Run the capture script
2. Analyze: Run the analyze script with target process or slice name

Capture Trace

Basic Capture

python scripts/capture_trace.py --duration 10

If no --output is specified, the trace will be saved to a temporary directory with a timestamp (e.g., /tmp/trace_20260518_143022.perfetto-trace).

With Custom Output Path

python scripts/capture_trace.py --duration 10 --output mytrace.perfetto-trace

With Custom Atrace Categories

Only use --categories when you need additional atrace categories beyond the default config. The default config already includes standard tracing categories.

python scripts/capture_trace.py --duration 10 --categories dalvikviktime my_custom_tag

With Custom Config

python scripts/capture_trace.py --duration 10 --config configs/my_custom_config.txt

Environment Checks:

• The script automatically checks if adb is installed and in PATH
• Verifies that a device is connected (USB or via adb connect)
• Validates the output directory exists and is writable
• Displays the device serial number before capturing

Analyze Trace

All time metrics reported are CPU time — actual time the thread was scheduled on CPU, computed via precise intersection with thread_state. CPU percentages for processes must use total system CPU time (SUM(dur) FROM thread_state WHERE state = 'Running') as the denominator to match Perfetto UI.

Process CPU + Thread Breakdown

Shows total process CPU time, per-thread breakdown, and top 10 named slices by CPU time.

Implementation requirements:

• Use thread_state table with state = 'Running' filter for all CPU time calculations. Do not use sched_slice — it produces different totals than Perfetto UI.
• Process CPU percentage denominator: SUM(dur) FROM thread_state WHERE state = 'Running' (total system CPU time), not trace duration.
• Slice CPU time: compute via intersection of slice duration with overlapping thread_state = 'Running' intervals.
• Slice aggregation: group by slice.name, use LIMIT 10 (show fewer only if <10 distinct names exist).
• Present results in a clean, readable format (tables or lists) — raw CSV is acceptable for script output but should be formatted for the user.

python scripts/analyze_trace.py mytrace.perfetto-trace --process "com.example.app"

Output:

• Process summary: total CPU time (ms), trace duration (ms), CPU percentage (relative to total system CPU time)
• Per-thread breakdown: each thread's CPU time (ms) and percentage within the process
• Top 10 slices by CPU time: aggregate CPU of the hottest named slices (count, total CPU, avg CPU)
  • Use LIMIT 10; if fewer than 10 distinct slice names exist, show all
  • Important: slice times can overlap (nested calls), so the sum of top slices may exceed total process CPU

Slice CPU Summary + Top 10 Instances

Shows aggregate CPU stats for all slices matching a name, plus the top 10 individual instances by CPU time:

python scripts/analyze_trace.py mytrace.perfetto-trace --slice "Choreographer#doFrame"

Output:

• Summary: total count, total CPU time (ms), average CPU time (ms), CPU percentage of trace
• Top 10 instances: timestamp, process name, thread name, CPU time (ms)

Agent Workflow

When the user asks to capture and analyze a trace:

1. Determine the user's intent:
   • If asking about process CPU ("app X is using too much CPU") → use --process
   • If asking about specific function/slice ("how much CPU does Y use?") → use --slice
2. If no trace file exists, run capture_trace.py to capture one
   • Pre-flight check: Verify SELinux status. If getenforce returns Enforcing, recommend running adb shell setenforce 0 first
   • If the user mentions custom app instrumentation, missing trace events, or needs additional atrace categories, add --categories <tag1> <tag2> ... to the capture command
   • If the user needs a fully custom tracing config, use --config <path> instead of the default
3. Run analyze_trace.py with the appropriate flag
4. Summarize results clearly

Notes

• Default capture duration is 10 seconds; increase for rare events
• Output location: If not specified, traces are saved to the system temp directory with a timestamp
• Environment validation: The script checks adb availability, device connection, and output directory before capturing
• Categories: Only specify --categories when you need additional atrace tags beyond the default config
• Slice names support % wildcard (SQL LIKE pattern)
• trace_processor is auto-downloaded on first run to ~/.lingma/tools/
• Custom atrace categories are injected into the ftrace_config section
• Config files support {duration_ms} placeholder for dynamic duration
• Slice times can overlap due to nested calls; the sum of top slice CPU may exceed total process CPU
• For detailed SQL reference, see reference.md

Troubleshooting

Perfetto Cannot Start or Hangs

Symptom: perfetto command fails to start, hangs indefinitely, or returns errors about traced/traced_probes

Root Cause: Stale perfetto or simpleperf processes from previous capture sessions blocking new instances

Solution: Kill all running tracing processes before capturing:

adb shell pkill -9 simpleperf
adb shell pkill -9 perfetto
adb shell pkill -9 traced
adb shell pkill -9 traced_probes
# Wait a moment for processes to fully terminate
sleep 2
# Now run the capture script
python scripts/capture_trace.py --duration 10

When to Use: Apply this fix when:

• Perfetto command hangs or doesn't respond
• Previous trace capture was interrupted or failed
• Device shows errors about traced service being unavailable
• Multiple capture attempts fail without clear error messages

Permission Denied When Capturing Trace

Symptom: perfetto fails with "Permission denied" error or trace file is not created at /data/misc/perfetto-traces/trace

Root Cause: SELinux policy on some devices blocks perfetto from writing to the trace directory

Solution: Temporarily disable SELinux enforcement before capturing:

adb root
adb shell setenforce 0
# Now run the capture script
python scripts/capture_trace.py --duration 10

Important Notes:

• setenforce 0 requires root access (adb root)
• This change is temporary and will reset after device reboot
• Remember to re-enable SELinux after capturing: adb shell setenforce 1
• Not all devices support adb root (production devices may be locked)

When to Use: Apply this fix when:

• Trace capture fails with permission errors
• Config file push succeeds but perfetto cannot write output
• Device shows "Permission denied" in perfetto error messages