English | Site Directory

Android - An Open Handset Alliance Project

android.os
public final class

android.os.Debug

java.lang.Object
android.os.Debug

Provides various debugging functions 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 Running the Traceview Debugging Program for information about reading trace files. To start logging trace files, call one of the startMethodTracing() methods.To stop tracing, call stopMethodTracing().

Nested Classes
Debug.InstructionCount API for gathering and querying instruction counts. 

Summary

Constants

      Value  
int  SHOW_CLASSLOADER    0x00000002 
int  SHOW_FULL_DETAIL  Flags for printLoadedClasses().  0x00000001 
int  SHOW_INITIALIZED    0x00000004 
int  TRACE_COUNT_ALLOCS  Flags for startMethodTracing().  0x00000001 

Public Methods

      static  void  changeDebugPort(int port)
Change the JDWP port -- this is a temporary measure.
      static  void  enableEmulatorTraceOutput()
Enable "emulator traces", in which information about the current method is made available to the "emulator -trace" feature.
      static  void  enableTopAllocCounts(int depth)
Enable object allocation count logging and reporting.
      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  void  getDirtyPages(int[] pages)
Determines the number of dirty belonging to the java and native heap segments of this process.
      static  int  getGlobalAllocCount()
      static  int  getGlobalAllocSize()
      static  int  getGlobalFreedCount()
      static  int  getGlobalFreedSize()
      static  int  getGlobalGcInvocationCount()
      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  int  getThreadAllocCount()
      static  int  getThreadAllocSize()
      static  int  getThreadGcInvocationCount()
      static  boolean  isDebuggerConnected()
Determine if a debugger is currently attached.
      static  void  printLoadedClasses(int flags)
Dump a list of loaded class to the log file.
      static  void  resetAllCounts()
      static  void  resetGlobalAllocCount()
      static  void  resetGlobalAllocSize()
      static  void  resetGlobalFreedCount()
      static  void  resetGlobalFreedSize()
      static  void  resetGlobalGcInvocationCount()
      static  void  resetThreadAllocCount()
      static  void  resetThreadAllocSize()
      static  void  resetThreadGcInvocationCount()
      static  void  startAllocCounting()
Count the number and aggregate size of memory allocations between two points.
      static  void  startMethodTracing(String traceName)
Start method tracing, specifying the trace log file name, which is the base name for the trace files.
      static  void  startMethodTracing(String traceName, int bufferSize)
Start method tracing, specifying the trace name, which is the base name for the trace files, and the buffer size.
      static  void  startMethodTracing()
Start method tracing with default log name and buffer size.
      static  void  startMethodTracing(String traceName, int bufferSize, int flags)
Start method tracing, specifying the trace name, which is the base name for the trace files, and the buffer size.
      static  void  startNativeTracing()
Enable qemu tracing.
      static  void  stopAllocCounting()
      static  void  stopMethodTracing()
Stop method tracing.
      static  void  stopNativeTracing()
Stop qemu tracing.
      static  void  waitForDebugger()
Wait until a debugger attaches.
      static  boolean  waitingForDebugger()
Returns "true" if one or more threads is waiting for a debugger to attach.
Methods inherited from class java.lang.Object

Details

Constants

public static final int SHOW_CLASSLOADER

Constant Value: 2 (0x00000002)

public static final int SHOW_FULL_DETAIL

Flags for printLoadedClasses(). Default behavior is to only show the class name.
Constant Value: 1 (0x00000001)

public static final int SHOW_INITIALIZED

Constant Value: 4 (0x00000004)

public static final int TRACE_COUNT_ALLOCS

Flags for startMethodTracing(). These can be ORed together. TRACE_COUNT_ALLOCS adds the results from startAllocCounting to the trace key file.
Constant Value: 1 (0x00000001)

Public Methods

public static void changeDebugPort(int port)

Change the JDWP port -- this is a temporary measure. If a debugger is currently attached the change may not happen until after the debugger disconnects.

public static void enableEmulatorTraceOutput()

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().

public static void enableTopAllocCounts(int depth)

Enable object allocation count logging and reporting. Call with a depth of zero to disable. This produces "top N" lists on every GC.

public static int getBinderReceivedTransactions()

Returns the number of received transactions from the binder driver.

Returns

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

public static int getBinderSentTransactions()

Returns the number of sent transactions from this process.

Returns

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

public static void getDirtyPages(int[] pages)

Determines the number of dirty belonging to the java and native heap segments of this process. pages[0] returns the number of native shared pages, pages[1] returns the number of java shared pages, pages[2] returns the number of native private pages, and pages[3] returns the number of java private pages.

public static int getGlobalAllocCount()

public static int getGlobalAllocSize()

public static int getGlobalFreedCount()

public static int getGlobalFreedSize()

public static int getGlobalGcInvocationCount()

public static long getNativeHeapAllocatedSize()

Returns the amount of allocated memory in the native heap.

Returns

  • The allocated size in bytes.

public static long getNativeHeapFreeSize()

Returns the amount of free memory in the native heap.

Returns

  • The freed size in bytes.

public static long getNativeHeapSize()

Returns the size of the native heap.

Returns

  • The size of the native heap in bytes.

public static int getThreadAllocCount()

public static int getThreadAllocSize()

public static int getThreadGcInvocationCount()

public static boolean isDebuggerConnected()

Determine if a debugger is currently attached.

public static void printLoadedClasses(int flags)

Dump a list of loaded class to the log file.

public static void resetAllCounts()

public static void resetGlobalAllocCount()

public static void resetGlobalAllocSize()

public static void resetGlobalFreedCount()

public static void resetGlobalFreedSize()

public static void resetGlobalGcInvocationCount()

public static void resetThreadAllocCount()

public static void resetThreadAllocSize()

public static void resetThreadGcInvocationCount()

public static void startAllocCounting()

Count the number and aggregate size of memory allocations between two points. The "start" function resets the counts and enables counting. The "stop" function disables the counting so that the analysis code doesn't cause additional allocations. The "get" function returns the specified value. Counts are kept for the system as a whole and for each thread.

public static void startMethodTracing(String traceName)

Start method tracing, specifying the trace log file name, which is the base name for the trace files. The trace files will be put under "/tmp" unlessan absolute path is given for the trace name. See Running the Traceview Debugging Program for information about reading trace files.

Parameters

traceName Base name for the two trace log files to create. If an absolute path is used, such as "/tmp/foo/bar" then the trace files will be created as "/tmp/foo/bar.data" and "/tmp/foo/bar.key". Otherwise, if a relative path is used, such as "mytrace" then the files will be created under "/tmp/" as "/tmp/mytrace.data" and "/tmp/mytrace.key". If no name argument is given, this value defaults to "/tmp/dmtrace".

public static void startMethodTracing(String traceName, int bufferSize)

Start method tracing, specifying the trace name, which is the base name for the trace files, and the buffer size. The trace files will be put under "/tmp" unless an absolute path is given for the trace name. See Running the Traceview Debugging Program for information about reading trace files.

Parameters

traceName Base name for the two trace log files to create. If an absolute path is used, such as "/tmp/foo/bar" then the trace files will be created as "/tmp/foo/bar.data" and "/tmp/foo/bar.key". Otherwise, if a relative path is used, such as "mytrace" then the files will be created under "/tmp/" as "/tmp/mytrace.data" and "/tmp/mytrace.key". If no name argument is given, this value defaults to "/tmp/dmtrace".
bufferSize The maximum size of both files combined. If not given, it defaults to 8MB.

public static void startMethodTracing()

Start method tracing with default log name and buffer size. See Running the Traceview Debugging Program for information about reading these files. Call stopMethodTracing() to stop tracing.

public static void startMethodTracing(String traceName, int bufferSize, int flags)

Start method tracing, specifying the trace name, which is the base name for the trace files, and the buffer size. The trace files will be put under "/tmp" unless an absolute path is given for the trace name. See Running the Traceview Debugging Program for information about reading trace files.

Parameters

traceName Base name for the two trace log files to create. If an absolute path is used, such as "/tmp/foo/bar" then the trace files will be created as "/tmp/foo/bar.data" and "/tmp/foo/bar.key". Otherwise, if a relative path is used, such as "mytrace" then the files will be created under "/tmp/" as "/tmp/mytrace.data" and "/tmp/mytrace.key". If no name argument is given, this value defaults to "/tmp/dmtrace".
bufferSize The maximum size of both files combined. If not given, it defaults to 8MB.

public static void startNativeTracing()

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 disadvantage is that the qemu emulator is slower than the real device. Also the names of the java methods are known only by the java vm and not by the emulator (but this can be fixed).

public static void stopAllocCounting()

public static void stopMethodTracing()

Stop method tracing.

public static void stopNativeTracing()

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.

public static void waitForDebugger()

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.

public static boolean waitingForDebugger()

Returns "true" if one or more threads is waiting for a debugger to attach.
Build m5-rc15g - 14 May 2008 12:50