Skip to content

Add Android native CPU and Perfetto profiling under perf #696

New issue
New issue
Closed
Closed
Add Android native CPU and Perfetto profiling under perf#696
Labels
in-progressWork is actively in progress

Description

@thymikee
thymikee
opened on Jun 5, 2026

Parent

#694

What to build

Add Android native profiling collectors under the consolidated perf family. This issue groups Android work because Simpleperf, Perfetto, package/PID resolution, adb command execution, artifact pulling, and profileability hints share the same platform seams.

Prototype CLI shape:

agent-device perf cpu profile start --kind simpleperf --out cpu.perf.data
agent-device perf cpu profile stop --kind simpleperf --out cpu.perf.data
agent-device perf cpu profile report --kind simpleperf --out cpu-report.json
agent-device perf trace start --kind perfetto --out app.perfetto-trace
agent-device perf trace stop --kind perfetto --out app.perfetto-trace

Expected agent experience:

  • Agents first run perf metrics or perf frames to confirm the symptom.
  • Agents escalate to Simpleperf for CPU-bound native slowness.
  • Agents escalate to Perfetto for broader timeline, frame, scheduling, or system trace evidence.
  • Commands return compact summaries and artifact paths, never full trace dumps in model context.

Acceptance criteria

  • Android app sessions can resolve the active package and target process ids needed for profiling.
  • perf cpu profile start|stop|report --kind simpleperf captures a bounded CPU profile artifact and returns a compact top-function or report summary when possible.
  • perf trace start|stop --kind perfetto captures a bounded Perfetto artifact using a conservative app-focused config.
  • Commands fail with actionable hints when Simpleperf, Perfetto, app profileability, package identity, or process state is unavailable.
  • Artifact-producing commands return local or daemon artifact paths plus small JSON metadata.
  • Compose-specific trace guidance is optional and gated by app/runtime support; it is not required for the base Perfetto collector.
  • heapprofd/native allocation tracing is either implemented only if the Perfetto plumbing makes it cheap, or explicitly deferred to the memory diagnostics issue.

Validation

  • Android platform unit tests with mocked adb, Simpleperf, and Perfetto command output.
  • Provider-backed session scenario for command translation and artifact lifecycle.
  • pnpm check:unit
  • pnpm format

Blocked by

Activity

  1. thymikee
    added
    in-progressWork is actively in progress
    on Jun 10, 2026

  2. thymikee commented on Jun 10, 2026

    @thymikee
    thymikee
    on Jun 10, 2026
    MemberAuthor

    Implementation note for #694 rollout workers:

    Please treat agent-friendly, token-efficient output as a core requirement, not a nice-to-have.

    • Defaults should return compact summaries, top offenders, clear unavailable reasons/hints, and stable artifact paths.
    • Perf/profile/trace/memory commands should not dump full-fidelity tool output into CLI/MCP/default JSON.
    • Large profiles, traces, heap dumps, memgraphs, and crash logs should remain artifacts with bounded metadata.
    • Design for progressive lookup: first command gives the useful summary/top offenders; follow-up command/options can drill into a specific artifact, thread, process, time window, symbol, allocation group, etc.
    • JSON should be structured for agents: bounded arrays, top offenders first, predictable keys, and actionable hints.

    During review we should treat unbounded raw output or huge default JSON payloads as actionable feedback.

  3. thymikee commented on Jun 12, 2026

    @thymikee
    thymikee
    on Jun 12, 2026
    MemberAuthor

    Correction: my previous closure-audit comment was mangled by shell interpolation of Markdown backticks. This is the corrected merged-main verification record.

    Closure audit from merged main: I consider this issue closable.

    Verified against origin/main at 48c121d5e after #757 merged:

    • Built merged source with pnpm build.
    • Booted Pixel_9_Pro_XL_API_37 headless emulator; verified Android boot complete and opened com.android.settings in session closure-696.
    • perf metrics --json returned compact startup/fps/memory/cpu evidence with top memory consumers and bounded frame windows.
    • perf frames --json returned compact frame-health evidence.
    • perf trace start --kind perfetto --out /private/tmp/agent-device-closure-696.perfetto-trace --json started for com.android.settings with app PID and artifact path only.
    • perf trace stop --kind perfetto --json produced /private/tmp/agent-device-closure-696.perfetto-trace at 3,089,640 bytes and returned compact summary metadata plus the explicit note to open the Perfetto artifact for timeline root cause.
    • Tried perf cpu profile start --kind simpleperf against both com.android.settings and installed com.justforfun.neoncity; this emulator denied perf_event_open, and the command returned the intended actionable hint to use a debuggable/profileable app or permissive image.
    • Ran focused positive/lifecycle coverage for the Simpleperf/Perfetto paths that the emulator could not fully allow: pnpm exec vitest run src/platforms/android/__tests__/perf.test.ts src/daemon/handlers/__tests__/session-observability.test.ts src/daemon/handlers/__tests__/session-close-shutdown.test.ts src/__tests__/client.test.ts -> 4 files, 73 tests passed.
    • Closed the closure-696 session and shut down the emulator.

    Scope check: this is minimal and useful as a first-pass Android perf triage lane. It returns compact defaults, artifact paths, and unavailable hints; raw Perfetto/Simpleperf artifacts stay on disk for native tools.

  4. thymikee commented on Jun 12, 2026

    @thymikee
    thymikee
    on Jun 12, 2026
    MemberAuthor

    Scheduled the non-blocking follow-up from the closure audit: #785.

    This is maintenance/refactor work only. It should not block closing this issue because Android perf metrics, frames, and Perfetto start/stop were verified on a real emulator. The Simpleperf positive path remains device/app dependent, and the current unavailable response was verified to return an explicit actionable hint.

  5. thymikee commented on Jun 13, 2026

    @thymikee
    thymikee
    on Jun 13, 2026
    MemberAuthor

    Closing after the merged-main closure audit and follow-up split/refactor work.

    Current scope is complete as the Android native perf 80% triage lane:

    • compact defaults for metrics/frames, Simpleperf, and Perfetto paths
    • artifact paths plus bounded metadata instead of raw profile/trace dumps
    • explicit unavailable/actionable hints for profileability/tool/device limitations
    • Perfetto positive path verified on emulator; Simpleperf unavailable path verified with the expected hint
    • maintenance/refactor follow-up refactor(android): split native perf collector into focused modules #785 is already closed

    Anything beyond this, such as deeper Perfetto analysis, heapprofd/native allocation tracing, or native-tool-grade investigation workflows, should stay in follow-up issues and native debuggers rather than expanding this issue.

  6. thymikee
    closed this as completedon Jun 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    in-progressWork is actively in progress

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions