Overview

The ProfilingManager API lets you collect real-user performance profiles, such as system traces and Java heap dumps, from production devices running Android 15 (API level 35) and higher. It supports two collection mechanisms: app-driven profiles where your app controls the profile collection from start to stop (Android 15 and higher) and trigger-based profiles where the system handles the capture in response to events that you register interest in on Android 16 (API level 36) and higher.

This guide covers the following topics:

• Capture profiles: How to start and stop app-driven profile recordings and how to register for trigger-based profile recordings.
• Retrieve and upload profiles: How to retrieve profiles locally with adb or upload them in the background with WorkManager.
• Analyze profiles: How to visualize profiles in the Perfetto UI, query profiles with PerfettoSQL, analyze traces in bulk, and analyze profiles with AI.
• Debugging case studies: How to apply ProfilingManager end-to-end to debug an ANR and debug an OOM crash.
• Rate limiting and collection behavior: How to understand rate limiting and collection behavior in production.
• Local debugging: How to use debug commands for local profiling.

Key Point: This guide is for developers who want to set up a way to collect end-user performance profiles.

Supported profile types

ProfilingManager supports collecting several types of profiles so you can target specific performance concerns in your app. You can configure requests directly using platform APIs or using the AndroidX Core builders:

• System traces: Captured using PROFILING_TYPE_SYSTEM_TRACE or SystemTraceRequestBuilder.
  • Useful for diagnosing jank, analyzing latency, and general performance debugging.
• Java heap dumps: Captured using PROFILING_TYPE_JAVA_HEAP_DUMP or JavaHeapDumpRequestBuilder.
  • Captures a snapshot of your app's Java heap object graph and sizes for memory leak detection and memory optimization.
• Heap profiles: Captured using PROFILING_TYPE_HEAP_PROFILE or HeapProfileRequestBuilder.
  • Tracks native (or optionally Java) memory allocations over time to help optimize memory usage.
• Stack sampling: Captured using PROFILING_TYPE_STACK_SAMPLING or StackSamplingRequestBuilder.
  • Samples thread call stacks to help you understand code execution and analyze CPU usage.

Integrate ProfilingManager with an AI agent

You can use an AI coding agent to integrate ProfilingManager into your app. For example, run the following prompt in your AI coding agent to set up Application Not Responding (ANR) trigger collection, replacing </path/to/codebase> with the path to your app:

Read https://developer.android.com/topic/performance/tracing/profiling-manager/trigger-based-capture
and https://developer.android.com/topic/performance/tracing/profiling-manager/upload-worker
and integrate ProfilingManager ANR trigger collection (TRIGGER_TYPE_ANR) into my
app at </path/to/codebase>, including registering the result listener after app
startup completes and scheduling a WorkManager upload job when a profile is
received.

You can adapt this prompt to set up other system triggers (such as TRIGGER_TYPE_OOM), or configure app-driven profile captures using the app-driven profiling guide. After integrating, test your setup locally using the debug commands for local profiling, and analyze collected profiles with an AI agent.