Added in API level 1

Debug

---

Kotlin |Java

class Debug

kotlin.Any
↳	android.os.Debug

Provides various debugging methods for Android applications, including tracing and allocation counts.

Logging Trace Files

Debug can create log files that give details about an application, such as a call stack and start/stop times for any running methods. See Inspect Trace Logs with Traceview for information about reading trace files. To start logging trace files, call one of the startMethodTracing() methods. To stop tracing, call stopMethodTracing().

Summary

Nested classes
	InstructionCount API for gathering and querying instruction counts.
	MemoryInfo This class is used to retrieved various statistics about the memory mappings for this process.

Constants
static Int	SHOW_CLASSLOADER
static Int	SHOW_FULL_DETAIL Flags for printLoadedClasses().
static Int	SHOW_INITIALIZED
static Int	TRACE_COUNT_ALLOCS Flags for startMethodTracing().

Public methods
static Unit	attachJvmtiAgent(library: String, options: String?, classLoader: ClassLoader?) Attach a library as a jvmti agent to the current runtime, with the given classloader determining the library search path.
static Unit	changeDebugPort(port: Int) Change the JDWP port.
static Unit	dumpHprofData(fileName: String!) Dump "hprof" data to the specified file.
static Boolean	dumpService(name: String!, fd: FileDescriptor!, args: Array<String!>!) Get a debugging dump of a system service by name.
static Unit	enableEmulatorTraceOutput() Enable "emulator traces", in which information about the current method is made available to the "emulator -trace" feature.
static Int	getBinderDeathObjectCount() Returns the number of death notification links to Binder objects that exist in the current process.
static Int	getBinderLocalObjectCount() Returns the number of active local Binder objects that exist in the current process.
static Int	getBinderProxyObjectCount() Returns the number of references to remote proxy Binder objects that exist in the current process.
static Int	getBinderReceivedTransactions() Returns the number of received transactions from the binder driver.
static Int	getBinderSentTransactions() Returns the number of sent transactions from this process.
static Int	getGlobalAllocCount() Returns the global count of objects allocated by the runtime between a start and stop.
static Int	getGlobalAllocSize() Returns the global size, in bytes, of objects allocated by the runtime between a start and stop.
static Int	getGlobalClassInitCount() Returns the number of classes successfully initialized (ie those that executed without throwing an exception) between a start and stop.
static Int	getGlobalClassInitTime() Returns the time spent successfully initializing classes between a start and stop.
static Int	getGlobalExternalAllocCount() This method exists for compatibility and always returns 0.
static Int	getGlobalExternalAllocSize() This method exists for compatibility and always returns 0.
static Int	getGlobalExternalFreedCount() This method exists for compatibility and always returns 0.
static Int	getGlobalExternalFreedSize() This method exists for compatibility and has no effect.
static Int	getGlobalFreedCount() Returns the global count of objects freed by the runtime between a start and stop.
static Int	getGlobalFreedSize() Returns the global size, in bytes, of objects freed by the runtime between a start and stop.
static Int	getGlobalGcInvocationCount() Returns the number of non-concurrent GC invocations between a start and stop.
static Int	getLoadedClassCount() Get the number of loaded classes.
static Unit	getMemoryInfo(memoryInfo: Debug.MemoryInfo!) Retrieves information about this processes memory usages.
static Long	getNativeHeapAllocatedSize() Returns the amount of allocated memory in the native heap.
static Long	getNativeHeapFreeSize() Returns the amount of free memory in the native heap.
static Long	getNativeHeapSize() Returns the size of the native heap.
static Long	getPss() Retrieves the PSS memory used by the process as given by the smaps.
static Long	getRss() Retrieves the RSS memory used by the process as given by the status file.
static String!	getRuntimeStat(statName: String!) Returns the value of a particular runtime statistic or null if no such runtime statistic exists.
static MutableMap<String!, String!>!	getRuntimeStats() Returns a map of the names/values of the runtime statistics that getRuntimeStat(java.lang.String) supports.
static Int	getThreadAllocCount() Returns the thread-local count of objects allocated by the runtime between a start and stop.
static Int	getThreadAllocSize() Returns the thread-local size of objects allocated by the runtime between a start and stop.
static Int	getThreadExternalAllocCount() This method exists for compatibility and has no effect.
static Int	getThreadExternalAllocSize() This method exists for compatibility and has no effect.
static Int	getThreadGcInvocationCount() Returns the number of thread-local non-concurrent GC invocations between a start and stop.
static Boolean	isDebuggerConnected() Determine if a debugger is currently attached.
static Unit	printLoadedClasses(flags: Int) Dump a list of all currently loaded class to the log file.
static Unit	resetAllCounts() Clears all the global and thread-local memory allocation counters.
static Unit	resetGlobalAllocCount() Clears the global count of objects allocated.
static Unit	resetGlobalAllocSize() Clears the global size of objects allocated.
static Unit	resetGlobalClassInitCount() Clears the count of classes initialized.
static Unit	resetGlobalClassInitTime() Clears the count of time spent initializing classes.
static Unit	resetGlobalExternalAllocCount() This method exists for compatibility and has no effect.
static Unit	resetGlobalExternalAllocSize() This method exists for compatibility and has no effect.
static Unit	resetGlobalExternalFreedCount() This method exists for compatibility and has no effect.
static Unit	resetGlobalExternalFreedSize() This method exists for compatibility and has no effect.
static Unit	resetGlobalFreedCount() Clears the global count of objects freed.
static Unit	resetGlobalFreedSize() Clears the global size of objects freed.
static Unit	resetGlobalGcInvocationCount() Clears the count of non-concurrent GC invocations.
static Unit	resetThreadAllocCount() Clears the thread-local count of objects allocated.
static Unit	resetThreadAllocSize() Clears the thread-local count of objects allocated.
static Unit	resetThreadExternalAllocCount() This method exists for compatibility and has no effect.
static Unit	resetThreadExternalAllocSize() This method exists for compatibility and has no effect.
static Unit	resetThreadGcInvocationCount() Clears the thread-local count of non-concurrent GC invocations.
static Int	setAllocationLimit(limit: Int) Establish an object allocation limit in the current thread.
static Int	setGlobalAllocationLimit(limit: Int) Establish a global object allocation limit.
static Unit	startAllocCounting() Start counting the number and aggregate size of memory allocations.
static Unit	startMethodTracing() Start method tracing with default log name and buffer size.
static Unit	startMethodTracing(tracePath: String!) Start method tracing, specifying the trace log file path.
static Unit	startMethodTracing(tracePath: String!, bufferSize: Int) Start method tracing, specifying the trace log file name and the buffer size.
static Unit	startMethodTracing(tracePath: String!, bufferSize: Int, flags: Int) Start method tracing, specifying the trace log file name, the buffer size, and flags.
static Unit	startMethodTracingSampling(tracePath: String!, bufferSize: Int, intervalUs: Int) Start sampling-based method tracing, specifying the trace log file name, the buffer size, and the sampling interval.
static Unit	startNativeTracing() Enable qemu tracing.
static Unit	stopAllocCounting() Stop counting the number and aggregate size of memory allocations.
static Unit	stopMethodTracing() Stop method tracing.
static Unit	stopNativeTracing() Stop qemu tracing.
static Long	threadCpuTimeNanos() Get an indication of thread CPU usage.
static Unit	waitForDebugger() Wait until a debugger attaches.
static Boolean	waitingForDebugger() Returns "true" if one or more threads is waiting for a debugger to attach.

Constants

SHOW_CLASSLOADER

Added in API level 1

static val SHOW_CLASSLOADER: Int

Value: 2

SHOW_FULL_DETAIL

Added in API level 1

static val SHOW_FULL_DETAIL: Int

Flags for printLoadedClasses(). Default behavior is to only show the class name.

Value: 1

SHOW_INITIALIZED

Added in API level 1

static val SHOW_INITIALIZED: Int

Value: 4

TRACE_COUNT_ALLOCS

Added in API level 1
Deprecated in API level 23

static val TRACE_COUNT_ALLOCS: Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Flags for startMethodTracing(). These can be ORed together. TRACE_COUNT_ALLOCS adds the results from startAllocCounting to the trace key file.

Value: 1

Public methods

attachJvmtiAgent

Added in API level 28

static fun attachJvmtiAgent(
    library: String, 
    options: String?, 
    classLoader: ClassLoader?
): Unit

Attach a library as a jvmti agent to the current runtime, with the given classloader determining the library search path.

Note: agents may only be attached to debuggable apps. Otherwise, this function will throw a SecurityException.

Parameters
library	String: the library containing the agent. This value cannot be null.
options	String?: the options passed to the agent. This value may be null.
classLoader	ClassLoader?: the classloader determining the library search path. This value may be null.

Exceptions
java.io.IOException	if the agent could not be attached.
java.lang.SecurityException	if the app is not debuggable.

changeDebugPort

Added in API level 1
Deprecated in API level 15

static fun changeDebugPort(port: Int): Unit

Deprecated: no longer needed or useful

Change the JDWP port.

dumpHprofData

Added in API level 3

static fun dumpHprofData(fileName: String!): Unit

Dump "hprof" data to the specified file. This may cause a GC.

Parameters
fileName	String!: Full pathname of output file (e.g. "/sdcard/dump.hprof").

Exceptions
java.lang.UnsupportedOperationException	if the VM was built without HPROF support.
java.io.IOException	if an error occurs while opening or writing files.

dumpService

Added in API level 8

static fun dumpService(
    name: String!, 
    fd: FileDescriptor!, 
    args: Array<String!>!
): Boolean

Get a debugging dump of a system service by name.

Most services require the caller to hold android.permission.DUMP.

Parameters
name	String!: of the service to dump
fd	FileDescriptor!: to write dump output to (usually an output log file)
args	Array<String!>!: to pass to the service's dump method, may be null

Return
Boolean	true if the service was dumped successfully, false if the service could not be found or had an error while dumping

enableEmulatorTraceOutput

Added in API level 1
Deprecated in API level 34

static fun enableEmulatorTraceOutput(): Unit

Deprecated: Please use other tracing method in this class.

Enable "emulator traces", in which information about the current method is made available to the "emulator -trace" feature. There is no corresponding "disable" call -- this is intended for use by the framework when tracing should be turned on and left that way, so that traces captured with F9/F10 will include the necessary data. This puts the VM into "profile" mode, which has performance consequences. To temporarily enable tracing, use startNativeTracing().

getBinderDeathObjectCount

Added in API level 1

static fun getBinderDeathObjectCount(): Int

Returns the number of death notification links to Binder objects that exist in the current process.

getBinderLocalObjectCount

Added in API level 1

static fun getBinderLocalObjectCount(): Int

Returns the number of active local Binder objects that exist in the current process.

getBinderProxyObjectCount

Added in API level 1

static fun getBinderProxyObjectCount(): Int

Returns the number of references to remote proxy Binder objects that exist in the current process.

getBinderReceivedTransactions

Added in API level 1

static fun getBinderReceivedTransactions(): Int

Returns the number of received transactions from the binder driver.

Return
Int	The number of received transactions or -1 if it could not read the stats.

getBinderSentTransactions

Added in API level 1

static fun getBinderSentTransactions(): Int

Returns the number of sent transactions from this process.

Return
Int	The number of sent transactions or -1 if it could not read t.

getGlobalAllocCount

Added in API level 1
Deprecated in API level 23

static fun getGlobalAllocCount(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the global count of objects allocated by the runtime between a start and stop.

getGlobalAllocSize

Added in API level 1
Deprecated in API level 23

static fun getGlobalAllocSize(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the global size, in bytes, of objects allocated by the runtime between a start and stop.

getGlobalClassInitCount

Added in API level 8
Deprecated in API level 23

static fun getGlobalClassInitCount(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the number of classes successfully initialized (ie those that executed without throwing an exception) between a start and stop.

getGlobalClassInitTime

Added in API level 8
Deprecated in API level 23

static fun getGlobalClassInitTime(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the time spent successfully initializing classes between a start and stop.

getGlobalExternalAllocCount

Added in API level 1
Deprecated in API level 15

static fun getGlobalExternalAllocCount(): Int

Deprecated: This method is now obsolete.

This method exists for compatibility and always returns 0.

getGlobalExternalAllocSize

Added in API level 1
Deprecated in API level 15

static fun getGlobalExternalAllocSize(): Int

Deprecated: This method is now obsolete.

This method exists for compatibility and always returns 0.

getGlobalExternalFreedCount

Added in API level 1
Deprecated in API level 15

static fun getGlobalExternalFreedCount(): Int

Deprecated: This method is now obsolete.

This method exists for compatibility and always returns 0.

getGlobalExternalFreedSize

Added in API level 1
Deprecated in API level 15

static fun getGlobalExternalFreedSize(): Int

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

getGlobalFreedCount

Added in API level 1
Deprecated in API level 23

static fun getGlobalFreedCount(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the global count of objects freed by the runtime between a start and stop.

getGlobalFreedSize

Added in API level 1
Deprecated in API level 23

static fun getGlobalFreedSize(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the global size, in bytes, of objects freed by the runtime between a start and stop.

getGlobalGcInvocationCount

Added in API level 1
Deprecated in API level 23

static fun getGlobalGcInvocationCount(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the number of non-concurrent GC invocations between a start and stop.

getLoadedClassCount

Added in API level 1

static fun getLoadedClassCount(): Int

Get the number of loaded classes.

Return
Int	the number of loaded classes.

getMemoryInfo

Added in API level 1

static fun getMemoryInfo(memoryInfo: Debug.MemoryInfo!): Unit

Retrieves information about this processes memory usages. This information is broken down by how much is in use by dalvik, the native heap, and everything else.

Note: this method directly retrieves memory information for the given process from low-level data available to it. It may not be able to retrieve information about some protected allocations, such as graphics. If you want to be sure you can see all information about allocations by the process, use android.app.ActivityManager#getProcessMemoryInfo(int[]) instead.

getNativeHeapAllocatedSize

Added in API level 1

static fun getNativeHeapAllocatedSize(): Long

Returns the amount of allocated memory in the native heap.

Return
Long	The allocated size in bytes.

getNativeHeapFreeSize

Added in API level 1

static fun getNativeHeapFreeSize(): Long

Returns the amount of free memory in the native heap.

Return
Long	The freed size in bytes.

getNativeHeapSize

Added in API level 1

static fun getNativeHeapSize(): Long

Returns the size of the native heap.

Return
Long	The size of the native heap in bytes.

getPss

Added in API level 14

static fun getPss(): Long

Retrieves the PSS memory used by the process as given by the smaps.

getRss

Added in API level 35

static fun getRss(): Long

Retrieves the RSS memory used by the process as given by the status file.

getRuntimeStat

Added in API level 23

static fun getRuntimeStat(statName: String!): String!

Returns the value of a particular runtime statistic or null if no such runtime statistic exists.

The following table lists the runtime statistics that the runtime supports. All statistics are approximate. Individual allocations may not be immediately reflected in the results. Note runtime statistics may be added or removed in a future API level.

Runtime statistic name	Meaning	Example	Supported (API Levels)
art.gc.gc-count	The number of garbage collection runs.	164	23
art.gc.gc-time	The total duration of garbage collection runs in ms.	62364	23
art.gc.bytes-allocated	The total number of bytes that the application allocated.	1463948408	23
art.gc.bytes-freed	The total number of bytes that garbage collection reclaimed.	1313493084	23
art.gc.blocking-gc-count	The number of blocking garbage collection runs.	2	23
art.gc.blocking-gc-time	The total duration of blocking garbage collection runs in ms.	804	23
art.gc.gc-count-rate-histogram	Every 10 seconds, the gc-count-rate is computed as the number of garbage collection runs that have occurred over the last 10 seconds. art.gc.gc-count-rate-histogram is a histogram of the gc-count-rate samples taken since the process began. The histogram can be used to identify instances of high rates of garbage collection runs. For example, a histogram of "0:34503,1:45350,2:11281,3:8088,4:43,5:8" shows that most of the time there are between 0 and 2 garbage collection runs every 10 seconds, but there were 8 distinct 10-second intervals in which 5 garbage collection runs occurred.	0:34503,1:45350,2:11281,3:8088,4:43,5:8	23
art.gc.blocking-gc-count-rate-histogram	Every 10 seconds, the blocking-gc-count-rate is computed as the number of blocking garbage collection runs that have occurred over the last 10 seconds. art.gc.blocking-gc-count-rate-histogram is a histogram of the blocking-gc-count-rate samples taken since the process began. The histogram can be used to identify instances of high rates of blocking garbage collection runs. For example, a histogram of "0:99269,1:1,2:1" shows that most of the time there are zero blocking garbage collection runs every 10 seconds, but there was one 10-second interval in which one blocking garbage collection run occurred, and there was one interval in which two blocking garbage collection runs occurred.	0:99269,1:1,2:1	23

Parameters
statName	String!: the name of the runtime statistic to look up.

Return
String!	the value of the specified runtime statistic or null if the runtime statistic doesn't exist.

getRuntimeStats

Added in API level 23

static fun getRuntimeStats(): MutableMap<String!, String!>!

Returns a map of the names/values of the runtime statistics that getRuntimeStat(java.lang.String) supports.

Return
MutableMap<String!, String!>!	a map of the names/values of the supported runtime statistics.

getThreadAllocCount

Added in API level 1
Deprecated in API level 23

static fun getThreadAllocCount(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the thread-local count of objects allocated by the runtime between a start and stop.

getThreadAllocSize

Added in API level 1
Deprecated in API level 23

static fun getThreadAllocSize(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the thread-local size of objects allocated by the runtime between a start and stop.

Return
Int	The allocated size in bytes.

getThreadExternalAllocCount

Added in API level 1
Deprecated in API level 15

static fun getThreadExternalAllocCount(): Int

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

getThreadExternalAllocSize

Added in API level 1
Deprecated in API level 15

static fun getThreadExternalAllocSize(): Int

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

getThreadGcInvocationCount

Added in API level 1
Deprecated in API level 23

static fun getThreadGcInvocationCount(): Int

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Returns the number of thread-local non-concurrent GC invocations between a start and stop.

isDebuggerConnected

Added in API level 1

static fun isDebuggerConnected(): Boolean

Determine if a debugger is currently attached.

printLoadedClasses

Added in API level 1

static fun printLoadedClasses(flags: Int): Unit

Dump a list of all currently loaded class to the log file.

Parameters
flags	Int: See constants above.

resetAllCounts

Added in API level 1
Deprecated in API level 23

static fun resetAllCounts(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears all the global and thread-local memory allocation counters.

See Also

• #startAllocCounting()

resetGlobalAllocCount

Added in API level 1
Deprecated in API level 23

static fun resetGlobalAllocCount(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the global count of objects allocated.

See Also

• #getGlobalAllocCount()

resetGlobalAllocSize

Added in API level 1
Deprecated in API level 23

static fun resetGlobalAllocSize(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the global size of objects allocated.

See Also

• #getGlobalAllocSize()

resetGlobalClassInitCount

Added in API level 8
Deprecated in API level 23

static fun resetGlobalClassInitCount(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the count of classes initialized.

See Also

• #getGlobalClassInitCount()

resetGlobalClassInitTime

Added in API level 8
Deprecated in API level 23

static fun resetGlobalClassInitTime(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the count of time spent initializing classes.

See Also

• #getGlobalClassInitTime()

resetGlobalExternalAllocCount

Added in API level 1
Deprecated in API level 15

static fun resetGlobalExternalAllocCount(): Unit

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

resetGlobalExternalAllocSize

Added in API level 1
Deprecated in API level 15

static fun resetGlobalExternalAllocSize(): Unit

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

resetGlobalExternalFreedCount

Added in API level 1
Deprecated in API level 15

static fun resetGlobalExternalFreedCount(): Unit

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

resetGlobalExternalFreedSize

Added in API level 1
Deprecated in API level 15

static fun resetGlobalExternalFreedSize(): Unit

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

resetGlobalFreedCount

Added in API level 1
Deprecated in API level 23

static fun resetGlobalFreedCount(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the global count of objects freed.

See Also

• #getGlobalFreedCount()

resetGlobalFreedSize

Added in API level 1
Deprecated in API level 23

static fun resetGlobalFreedSize(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the global size of objects freed.

See Also

• #getGlobalFreedSize()

resetGlobalGcInvocationCount

Added in API level 1
Deprecated in API level 23

static fun resetGlobalGcInvocationCount(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the count of non-concurrent GC invocations.

See Also

• #getGlobalGcInvocationCount()

resetThreadAllocCount

Added in API level 1
Deprecated in API level 23

static fun resetThreadAllocCount(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the thread-local count of objects allocated.

See Also

• #getThreadAllocCount()

resetThreadAllocSize

Added in API level 1
Deprecated in API level 23

static fun resetThreadAllocSize(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the thread-local count of objects allocated.

See Also

• #getThreadAllocSize()

resetThreadExternalAllocCount

Added in API level 1
Deprecated in API level 15

static fun resetThreadExternalAllocCount(): Unit

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

resetThreadExternalAllocSize

Added in API level 1
Deprecated in API level 15

static fun resetThreadExternalAllocSize(): Unit

Deprecated: This method is now obsolete.

This method exists for compatibility and has no effect.

resetThreadGcInvocationCount

Added in API level 1
Deprecated in API level 23

static fun resetThreadGcInvocationCount(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Clears the thread-local count of non-concurrent GC invocations.

See Also

• #getThreadGcInvocationCount()

setAllocationLimit

Added in API level 1
Deprecated in API level 15

static fun setAllocationLimit(limit: Int): Int

Deprecated: This method is now obsolete.

Establish an object allocation limit in the current thread. This feature was never enabled in release builds. The allocation limits feature was removed in Honeycomb. This method exists for compatibility and always returns -1 and has no effect.

setGlobalAllocationLimit

Added in API level 1
Deprecated in API level 15

static fun setGlobalAllocationLimit(limit: Int): Int

Deprecated: This method is now obsolete.

Establish a global object allocation limit. This feature was never enabled in release builds. The allocation limits feature was removed in Honeycomb. This method exists for compatibility and always returns -1 and has no effect.

startAllocCounting

Added in API level 1
Deprecated in API level 18

static fun startAllocCounting(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Start counting the number and aggregate size of memory allocations.

The start method resets the counts and enables counting. The stop method disables the counting so that the analysis code doesn't cause additional allocations. The various get methods return the specified value. And the various reset methods reset the specified count.

Counts are kept for the system as a whole (global) and for each thread. The per-thread counts for threads other than the current thread are not cleared by the "reset" or "start" calls.

startMethodTracing

Added in API level 1

static fun startMethodTracing(): Unit

Start method tracing with default log name and buffer size.

By default, the trace file is called "dmtrace.trace" and it's placed under your package-specific directory on primary shared/external storage, as returned by Context.getExternalFilesDir(String).

See Inspect Trace Logs with Traceview for information about reading trace files.

When method tracing is enabled, the VM will run more slowly than usual, so the timings from the trace files should only be considered in relative terms (e.g. was run #1 faster than run #2). The times for native methods will not change, so don't try to use this to compare the performance of interpreted and native implementations of the same method. As an alternative, consider using sampling-based method tracing via startMethodTracingSampling(java.lang.String,int,int) or "native" tracing in the emulator via startNativeTracing().

startMethodTracing

Added in API level 1

static fun startMethodTracing(tracePath: String!): Unit

Start method tracing, specifying the trace log file path.

When a relative file path is given, the trace file will be placed under your package-specific directory on primary shared/external storage, as returned by Context.getExternalFilesDir(String).

See Inspect Trace Logs with Traceview for information about reading trace files.

When method tracing is enabled, the VM will run more slowly than usual, so the timings from the trace files should only be considered in relative terms (e.g. was run #1 faster than run #2). The times for native methods will not change, so don't try to use this to compare the performance of interpreted and native implementations of the same method. As an alternative, consider using sampling-based method tracing via startMethodTracingSampling(java.lang.String,int,int) or "native" tracing in the emulator via startNativeTracing().

Parameters
tracePath	String!: Path to the trace log file to create. If null, this will default to "dmtrace.trace". If the file already exists, it will be truncated. If the path given does not end in ".trace", it will be appended for you.

startMethodTracing

Added in API level 1

static fun startMethodTracing(
    tracePath: String!, 
    bufferSize: Int
): Unit

Start method tracing, specifying the trace log file name and the buffer size.

When a relative file path is given, the trace file will be placed under your package-specific directory on primary shared/external storage, as returned by Context.getExternalFilesDir(String).

See Inspect Trace Logs with Traceview for information about reading trace files.

When method tracing is enabled, the VM will run more slowly than usual, so the timings from the trace files should only be considered in relative terms (e.g. was run #1 faster than run #2). The times for native methods will not change, so don't try to use this to compare the performance of interpreted and native implementations of the same method. As an alternative, consider using sampling-based method tracing via startMethodTracingSampling(java.lang.String,int,int) or "native" tracing in the emulator via startNativeTracing().

Parameters
tracePath	String!: Path to the trace log file to create. If null, this will default to "dmtrace.trace". If the file already exists, it will be truncated. If the path given does not end in ".trace", it will be appended for you.
bufferSize	Int: The maximum amount of trace data we gather. If not given, it defaults to 8MB.

startMethodTracing

Added in API level 1

static fun startMethodTracing(
    tracePath: String!, 
    bufferSize: Int, 
    flags: Int
): Unit

Start method tracing, specifying the trace log file name, the buffer size, and flags.

When a relative file path is given, the trace file will be placed under your package-specific directory on primary shared/external storage, as returned by Context.getExternalFilesDir(String).

See Inspect Trace Logs with Traceview for information about reading trace files.

When method tracing is enabled, the VM will run more slowly than usual, so the timings from the trace files should only be considered in relative terms (e.g. was run #1 faster than run #2). The times for native methods will not change, so don't try to use this to compare the performance of interpreted and native implementations of the same method. As an alternative, consider using sampling-based method tracing via startMethodTracingSampling(java.lang.String,int,int) or "native" tracing in the emulator via startNativeTracing().

Parameters
tracePath	String!: Path to the trace log file to create. If null, this will default to "dmtrace.trace". If the file already exists, it will be truncated. If the path given does not end in ".trace", it will be appended for you.
bufferSize	Int: The maximum amount of trace data we gather. If not given, it defaults to 8MB.
flags	Int: Flags to control method tracing. The only one that is currently defined is TRACE_COUNT_ALLOCS.

startMethodTracingSampling

Added in API level 21

static fun startMethodTracingSampling(
    tracePath: String!, 
    bufferSize: Int, 
    intervalUs: Int
): Unit

Start sampling-based method tracing, specifying the trace log file name, the buffer size, and the sampling interval.

When a relative file path is given, the trace file will be placed under your package-specific directory on primary shared/external storage, as returned by Context.getExternalFilesDir(String).

See Inspect Trace Logs with Traceview for information about reading trace files.

Parameters
tracePath	String!: Path to the trace log file to create. If null, this will default to "dmtrace.trace". If the file already exists, it will be truncated. If the path given does not end in ".trace", it will be appended for you.
bufferSize	Int: The maximum amount of trace data we gather. If not given, it defaults to 8MB.
intervalUs	Int: The amount of time between each sample in microseconds.

startNativeTracing

Added in API level 1

static fun startNativeTracing(): Unit

Enable qemu tracing. For this to work requires running everything inside the qemu emulator; otherwise, this method will have no effect. The trace file is specified on the command line when the emulator is started. For example, the following command line
emulator -trace foo
will start running the emulator and create a trace file named "foo". This method simply enables writing the trace records to the trace file.

The main differences between this and startMethodTracing() are that tracing in the qemu emulator traces every cpu instruction of every process, including kernel code, so we have more complete information, including all context switches. We can also get more detailed information such as cache misses. The sequence of calls is determined by post-processing the instruction trace. The qemu tracing is also done without modifying the application or perturbing the timing of calls because no instrumentation is added to the application being traced.

One limitation of using this method compared to using startMethodTracing() on the real device is that the emulator does not model all of the real hardware effects such as memory and bus contention. The emulator also has a simple cache model and cannot capture all the complexities of a real cache.

stopAllocCounting

Added in API level 1
Deprecated in API level 18

static fun stopAllocCounting(): Unit

Deprecated: Accurate counting is a burden on the runtime and may be removed.

Stop counting the number and aggregate size of memory allocations.

stopMethodTracing

Added in API level 1

static fun stopMethodTracing(): Unit

Stop method tracing.

stopNativeTracing

Added in API level 1

static fun stopNativeTracing(): Unit

Stop qemu tracing. See startNativeTracing() to start tracing.

Tracing can be started and stopped as many times as desired. When the qemu emulator itself is stopped then the buffered trace records are flushed and written to the trace file. In fact, it is not necessary to call this method at all; simply killing qemu is sufficient. But starting and stopping a trace is useful for examining a specific region of code.

threadCpuTimeNanos

Added in API level 1

static fun threadCpuTimeNanos(): Long

Get an indication of thread CPU usage. The value returned indicates the amount of time that the current thread has spent executing code or waiting for certain types of I/O. The time is expressed in nanoseconds, and is only meaningful when compared to the result from an earlier call. Note that nanosecond resolution does not imply nanosecond accuracy. On system which don't support this operation, the call returns -1.

waitForDebugger

Added in API level 1

static fun waitForDebugger(): Unit

Wait until a debugger attaches. As soon as the debugger attaches, this returns, so you will need to place a breakpoint after the waitForDebugger() call if you want to start tracing immediately.

waitingForDebugger

Added in API level 1

static fun waitingForDebugger(): Boolean

Returns "true" if one or more threads is waiting for a debugger to attach.