Levyra Android Performance

Levyra Android performance workflow

Purpose

This skill is the Android-specific evidence layer for runtime performance. It adapts the strongest parts of Google's official android/skills perfetto-trace-analysis workflow to Levyra without vendoring its large reference corpus or creating a second profiling system.

It does not replace levyra-compose, levyra-player, levyra-ci-workflows, levyra-release-check, levyra-r8-proguard, or the current architecture. Load the affected domain skill as well. Use levyra-r8-proguard instead for shrinker, keep-rule, resource-shrinking, mapping, or APK-size work.

Required context

1. Read root AGENTS.md and app/AGENTS.md.
2. Read docs/ARCHITECTURE.md and the affected domain skill.
3. Inspect the existing baseline-profile/benchmark setup and exact code path.
4. Record package/process, build variant, device/emulator, reproduction path, trace source, and relevant time window before drawing a conclusion.
5. Prefer release-like behavior for performance claims. Debug traces are evidence about debug behavior only.
6. Prefer current official Android/Perfetto documentation when a metric, module, schema, counter, or API is version-sensitive.

Chain of evidence

Keep verified evidence separate from hypotheses throughout the investigation. For a supplied Perfetto trace, maintain a compact analysis note next to the trace when the runtime can safely create one. Record only verified facts such as:

• timestamps and time windows;
• process upid and thread utid identities;
• slice names/durations;
• thread states and scheduling latency;
• frame timeline evidence;
• counters and memory/power values;
• Binder/flow dependencies;
• I/O blocked functions and wakeups;
• query text/result needed to reproduce a finding.

Do not write guesses into the evidence record as if they were facts. If the runtime cannot create a scratchpad, keep the same separation explicitly in the working report.

Investigation protocol

1. Define the symptom

State what is slow or janky, where it occurs, how to reproduce it, and what user behavior is affected. Separate cold/warm/hot startup, first playback, scrolling, track transitions, image-heavy surfaces, background playback, and idle battery behavior instead of treating them as one generic performance problem.

2. Start broad

Use high-level metrics and broad trace inspection before narrow custom SQL. Identify the active Levyra process, the relevant time range, frame misses, long-running/blocked threads, memory pressure, I/O, Binder/IPC, and power/system anomalies that overlap the symptom.

3. Form one hypothesis at a time

Use the prompt, current code path, and observed evidence to choose the next question. State why a query or trace inspection is being run before treating its result as meaningful.

4. Follow dependencies to the cause

Never equate wall-clock duration with CPU work. For every suspicious long slice, check the exact overlapping thread_state interval and distinguish:

• Running: consuming CPU;
• Runnable: ready but waiting for CPU;
• Sleeping: waiting voluntarily;
• uninterruptible/D-state: commonly blocked on I/O/kernel work;
• blocked on lock/Binder/another thread.

If a thread is waiting, follow the dependency. A waiting main thread is not the root cause until the blocker, server, I/O operation, lock owner, scheduler contention, or external process is identified.

5. Search for independent bottlenecks

Do not stop after the first anomaly. Perform one broader system check before concluding so a local Compose issue does not hide an unrelated I/O, scheduler, Binder, graphics-memory, LMKD, or power problem.

6. Fix and remeasure

Change the smallest material cause, then re-run the same reproduction path on an equivalent build/device. Do not declare success from code inspection alone when the original claim was performance.

Perfetto SQL discipline

When using trace_processor, treat SQL correctness as part of the evidence.

• Never guess a table, view, column, or INCLUDE PERFETTO MODULE name. Inspect the installed Perfetto schema/stdlib or current official reference first.
• Prefer existing Perfetto standard-library tables/views/macros over manual timestamp arithmetic when they express the same intent.
• Join threads/processes with utid/upid, not recycled OS tid/pid, unless the specific table contract requires otherwise.
• Handle incomplete intervals where dur = -1 using the trace end rather than summing or bounding them as negative durations.
• For two time ranges, use interval-overlap semantics; do not require one event to start inside the other interval.
• Prefer standard interval helpers or properly partitioned SPAN_JOIN when combining interval sets. Materialize intermediate tables where Perfetto requires it.
• Use = for exact matching. GLOB is case-sensitive and uses * and ?, so substring matching should look like GLOB '*needle*'. LIKE uses % and _ and is ASCII-case-insensitive by default; use it only when those wildcard or case semantics are intended. Verify the installed schema/query behavior before relying on either operator in evidence.
• Use EXTRACT_ARG for structured args rather than parsing display strings.
• Prefix columns with aliases in non-trivial joins so query meaning remains reviewable.
• Keep queries idempotent when they create Perfetto objects. A query used during iterative diagnosis should be safe to rerun.
• If a provided user query is being validated, preserve its analytical intent; do not simplify away an overlap, dependency, percentile, or attribution merely to make SQL execute.

A failed query is not evidence. Fix schema/syntax/logic and rerun it before using its result.

CPU and scheduler analysis

For CPU-bound or scheduling-sensitive paths:

• compare time spent Running versus Runnable for critical threads;
• quantify scheduling latency where useful and inspect high-percentile outliers such as p95/p99 instead of relying on one anecdotal pause;
• if Runnable time is high, inspect competing work and whether other CPUs were idle before blaming the app thread itself;
• correlate key-thread placement with CPU frequency and core behavior before inferring slow-code execution;
• inspect frequency/governor evidence when wall time rises without a matching increase in running CPU time;
• for blocked RenderThread/main/player threads, identify the waker or dependency;
• distinguish userspace work from kernel time when the trace supports it.

Do not "optimize" thread priorities, affinities, dispatchers, or coroutine structure from intuition alone.