ProfilingManager

Kotlin |Java

class ProfilingManager

kotlin.Any
↳	android.os.ProfilingManager

This class allows the caller to: - Request profiling and listen for results. Profiling types supported are: system traces, java heap dumps, heap profiles, and stack traces. - Register triggers for the system to capture profiling on the apps behalf.

The requestProfiling API can be used to begin profiling. Profiling may be ended manually using the CancellationSignal provided in the request, or as a result of a timeout. The timeout may be either the system default or caller defined in the parameter bundle for select types.

The profiling results are delivered to the requesting app's data directory and a pointer to the file will be received using the app provided listeners.

Apps can provide listeners in one or both of two ways: - A request-specific listener included with the request. This will trigger only with a result from the request it was provided with. - A global listener provided by registerForAllProfilingResults. This will be triggered for all results belonging to your app. This listener is the only way to receive results from system triggered profiling instances set up with addProfilingTriggers.

Requests are rate limited and not guaranteed to be filled. Rate limiting can be disabled for local testing of requestProfiling using the shell command device_config put profiling_testing rate_limiter.disabled true

In order to test profiling triggers, enable testing mode for your app with the shell command device_config put profiling_testing system_triggered_profiling.testing_package_name com.your.app which will: - Ensure that a background trace is running. - Allow all triggers for the provided package name to pass the system level rate limiter. This mode will continue until manually stopped with the shell command device_config delete profiling_testing system_triggered_profiling.testing_package_name

Results are redacted and contain specific information about the requesting process only.

Summary

Constants
static Int	`PROFILING_TYPE_HEAP_PROFILE` Profiling type for `requestProfiling` to request a heap profile.
static Int	`PROFILING_TYPE_JAVA_HEAP_DUMP` Profiling type for `requestProfiling` to request a java heap dump.
static Int	`PROFILING_TYPE_STACK_SAMPLING` Profiling type for `requestProfiling` to request a stack sample.
static Int	`PROFILING_TYPE_SYSTEM_TRACE` Profiling type for `requestProfiling` to request a system trace.

Public methods
Unit	`addProfilingTriggers(triggers: MutableList<ProfilingTrigger!>)` Register the provided list of triggers for this process.
Unit	`clearProfilingTriggers()` Remove all triggers for this process.
Unit	`registerForAllProfilingResults(executor: Executor, listener: Consumer<ProfilingResult!>)` Register a listener to be called for all profiling results for this uid.
Unit	`removeProfilingTriggers(triggers: MutableList<Int!>)` Remove the provided list of triggers for this process.
Unit	`requestProfiling(profilingType: Int, parameters: Bundle?, tag: String?, cancellationSignal: CancellationSignal?, executor: Executor?, listener: Consumer<ProfilingResult!>?)` Request system profiling.
Unit	`unregisterForAllProfilingResults(listener: Consumer<ProfilingResult!>?)` Unregister a listener that was to be called for all profiling results.

Constants

PROFILING_TYPE_HEAP_PROFILE

Added in API level 35

static val PROFILING_TYPE_HEAP_PROFILE: Int

Profiling type for requestProfiling to request a heap profile.

Value: 2

PROFILING_TYPE_JAVA_HEAP_DUMP

Added in API level 35

static val PROFILING_TYPE_JAVA_HEAP_DUMP: Int

Profiling type for requestProfiling to request a java heap dump.

Value: 1

PROFILING_TYPE_STACK_SAMPLING

Added in API level 35

static val PROFILING_TYPE_STACK_SAMPLING: Int

Profiling type for requestProfiling to request a stack sample.

Value: 3

PROFILING_TYPE_SYSTEM_TRACE

Added in API level 35

static val PROFILING_TYPE_SYSTEM_TRACE: Int

Profiling type for requestProfiling to request a system trace.

Value: 4

Public methods

addProfilingTriggers

Added in API level Baklava

fun addProfilingTriggers(triggers: MutableList<ProfilingTrigger!>): Unit

Register the provided list of triggers for this process. Profiling triggers are system triggered events that an app can register interest in receiving profiling of. There is no guarantee that these triggers will be filled. Results, if available, will be delivered only to a global listener added using registerForAllProfilingResults. Only one of each trigger type can be added at a time. - If the provided list contains a trigger type that is already registered then the new one will replace the existing one. - If the provided list contains more than one trigger object for a trigger type then only one will be kept.

Parameters
`triggers`	MutableList<ProfilingTrigger!>: This value cannot be `null`.

clearProfilingTriggers

Added in API level Baklava

fun clearProfilingTriggers(): Unit

Remove all triggers for this process.

registerForAllProfilingResults

Added in API level 35

fun registerForAllProfilingResults(
    executor: Executor, 
    listener: Consumer<ProfilingResult!>
): Unit

Register a listener to be called for all profiling results for this uid. Listeners set here will be called in addition to any provided with the request.

Note: If a callback attempt fails (for example, because your app is killed while a trace is in progress) re-delivery may be attempted using a listener added via this method.

Parameters
`executor`	Executor: The executor to call back with. This value cannot be `null`.
`listener`	Consumer<ProfilingResult!>: Listener to be triggered with result. This value cannot be `null`.

removeProfilingTriggers

Added in API level Baklava

fun removeProfilingTriggers(triggers: MutableList<Int!>): Unit

Remove the provided list of triggers for this process.

Parameters
`triggers`	MutableList<Int!>: This value cannot be `null`.

requestProfiling

Added in API level 35

fun requestProfiling(
    profilingType: Int, 
    parameters: Bundle?, 
    tag: String?, 
    cancellationSignal: CancellationSignal?, 
    executor: Executor?, 
    listener: Consumer<ProfilingResult!>?
): Unit

Request system profiling.

Note: use of this API directly is not recommended for most use cases. Consider using the higher level wrappers provided by AndroidX that will construct the request correctly, supporting available options with simplified request parameters

Both a listener and an executor must be set at the time of the request for the request to be considered for fulfillment. Listener/executor pairs can be set in this method, with registerForAllProfilingResults, or both. The listener and executor must be set together, in the same call. If no listener and executor combination is set, the request will be discarded and no callback will be received.

Requests will be rate limited and are not guaranteed to be filled.

There might be a delay before profiling begins. For continuous profiling types (system tracing, stack sampling, and heap profiling), we recommend starting the collection early and stopping it with cancellationSignal immediately after the area of interest to ensure that the section you want profiled is captured. For heap dumps, we recommend testing locally to ensure that the heap dump is collected at the proper time.

Parameters
`profilingType`	Int: Type of profiling to collect. Value is `android.os.ProfilingManager#PROFILING_TYPE_JAVA_HEAP_DUMP`, `android.os.ProfilingManager#PROFILING_TYPE_HEAP_PROFILE`, `android.os.ProfilingManager#PROFILING_TYPE_STACK_SAMPLING`, or `android.os.ProfilingManager#PROFILING_TYPE_SYSTEM_TRACE`
`parameters`	Bundle?: Bundle of request related parameters. If the bundle contains any unrecognized parameters, the request will be fail with `android.os.ProfilingResult#ERROR_FAILED_INVALID_REQUEST`. If the values for the parameters are out of supported range, the closest possible in range value will be chosen. Use of androidx wrappers is recommended over generating this directly. This value may be `null`.
`tag`	String?: Caller defined data to help identify the output. The first 20 alphanumeric characters, plus dashes, will be lowercased and included in the output filename. This value may be `null`.
`cancellationSignal`	CancellationSignal?: for caller requested cancellation. Results will be returned if available. If this is null, the requesting app will not be able to stop the collection. The collection will stop after timing out with either the provided configurations or with system defaults
`executor`	Executor?: The executor to call back with. Will only be used for the listener provided in this method. If this is null, and no global executor and listener combinations are registered at the time of the request, the request will be dropped.
`listener`	Consumer<ProfilingResult!>?: Listener to be triggered with result. Any global listeners registered via `registerForAllProfilingResults` will also be triggered. If this is null, and no global listener and executor combinations are registered at the time of the request, the request will be dropped.

unregisterForAllProfilingResults

Added in API level 35

fun unregisterForAllProfilingResults(listener: Consumer<ProfilingResult!>?): Unit

Unregister a listener that was to be called for all profiling results. If no listener is provided, all listeners for this process that were not submitted with a profiling request will be removed.

Parameters
`listener`	Consumer<ProfilingResult!>?: Listener to unregister and no longer be triggered with the results. Null to remove all global listeners for this uid. This value may be `null`.