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 Traceview: A Graphical Log Viewer for
* information about reading trace files. To start logging trace files, call one
* of the startMethodTracing() methods. To stop tracing, call
* {@link #stopMethodTracing()}.
*/
public final class Debug
{
private static final String TAG = "Debug";
/**
* Flags for startMethodTracing(). These can be ORed together.
*
* TRACE_COUNT_ALLOCS adds the results from startAllocCounting to the
* trace key file.
*/
public static final int TRACE_COUNT_ALLOCS = VMDebug.TRACE_COUNT_ALLOCS;
/**
* Flags for printLoadedClasses(). Default behavior is to only show
* the class name.
*/
public static final int SHOW_FULL_DETAIL = 1;
public static final int SHOW_CLASSLOADER = (1 << 1);
public static final int SHOW_INITIALIZED = (1 << 2);
// set/cleared by waitForDebugger()
private static volatile boolean mWaiting = false;
private Debug() {}
/*
* How long to wait for the debugger to finish sending requests. I've
* seen this hit 800msec on the device while waiting for a response
* to travel over USB and get processed, so we take that and add
* half a second.
*/
private static final int MIN_DEBUGGER_IDLE = 1300; // msec
/* how long to sleep when polling for activity */
private static final int SPIN_DELAY = 200; // msec
/**
* Default trace file path and file
*/
private static final String DEFAULT_TRACE_PATH_PREFIX =
Environment.getLegacyExternalStorageDirectory().getPath() + "/";
private static final String DEFAULT_TRACE_BODY = "dmtrace";
private static final String DEFAULT_TRACE_EXTENSION = ".trace";
private static final String DEFAULT_TRACE_FILE_PATH =
DEFAULT_TRACE_PATH_PREFIX + DEFAULT_TRACE_BODY
+ DEFAULT_TRACE_EXTENSION;
/**
* This class is used to retrieved various statistics about the memory mappings for this
* process. The returns info broken down by dalvik, native, and other. All results are in kB.
*/
public static class MemoryInfo implements Parcelable {
/** The proportional set size for dalvik heap. (Doesn't include other Dalvik overhead.) */
public int dalvikPss;
/** The proportional set size that is swappable for dalvik heap. */
/** @hide We may want to expose this, eventually. */
public int dalvikSwappablePss;
/** The private dirty pages used by dalvik heap. */
public int dalvikPrivateDirty;
/** The shared dirty pages used by dalvik heap. */
public int dalvikSharedDirty;
/** The private clean pages used by dalvik heap. */
/** @hide We may want to expose this, eventually. */
public int dalvikPrivateClean;
/** The shared clean pages used by dalvik heap. */
/** @hide We may want to expose this, eventually. */
public int dalvikSharedClean;
/** The dirty dalvik pages that have been swapped out. */
/** @hide We may want to expose this, eventually. */
public int dalvikSwappedOut;
/** The proportional set size for the native heap. */
public int nativePss;
/** The proportional set size that is swappable for the native heap. */
/** @hide We may want to expose this, eventually. */
public int nativeSwappablePss;
/** The private dirty pages used by the native heap. */
public int nativePrivateDirty;
/** The shared dirty pages used by the native heap. */
public int nativeSharedDirty;
/** The private clean pages used by the native heap. */
/** @hide We may want to expose this, eventually. */
public int nativePrivateClean;
/** The shared clean pages used by the native heap. */
/** @hide We may want to expose this, eventually. */
public int nativeSharedClean;
/** The dirty native pages that have been swapped out. */
/** @hide We may want to expose this, eventually. */
public int nativeSwappedOut;
/** The proportional set size for everything else. */
public int otherPss;
/** The proportional set size that is swappable for everything else. */
/** @hide We may want to expose this, eventually. */
public int otherSwappablePss;
/** The private dirty pages used by everything else. */
public int otherPrivateDirty;
/** The shared dirty pages used by everything else. */
public int otherSharedDirty;
/** The private clean pages used by everything else. */
/** @hide We may want to expose this, eventually. */
public int otherPrivateClean;
/** The shared clean pages used by everything else. */
/** @hide We may want to expose this, eventually. */
public int otherSharedClean;
/** The dirty pages used by anyting else that have been swapped out. */
/** @hide We may want to expose this, eventually. */
public int otherSwappedOut;
/** @hide */
public static final int NUM_OTHER_STATS = 16;
/** @hide */
public static final int NUM_DVK_STATS = 5;
/** @hide */
public static final int NUM_CATEGORIES = 7;
/** @hide */
public static final int offsetPss = 0;
/** @hide */
public static final int offsetSwappablePss = 1;
/** @hide */
public static final int offsetPrivateDirty = 2;
/** @hide */
public static final int offsetSharedDirty = 3;
/** @hide */
public static final int offsetPrivateClean = 4;
/** @hide */
public static final int offsetSharedClean = 5;
/** @hide */
public static final int offsetSwappedOut = 6;
private int[] otherStats = new int[(NUM_OTHER_STATS+NUM_DVK_STATS)*NUM_CATEGORIES];
public MemoryInfo() {
}
/**
* Return total PSS memory usage in kB.
*/
public int getTotalPss() {
return dalvikPss + nativePss + otherPss;
}
/**
* @hide Return total PSS memory usage in kB.
*/
public int getTotalUss() {
return dalvikPrivateClean + dalvikPrivateDirty
+ nativePrivateClean + nativePrivateDirty
+ otherPrivateClean + otherPrivateDirty;
}
/**
* Return total PSS memory usage in kB.
*/
public int getTotalSwappablePss() {
return dalvikSwappablePss + nativeSwappablePss + otherSwappablePss;
}
/**
* Return total private dirty memory usage in kB.
*/
public int getTotalPrivateDirty() {
return dalvikPrivateDirty + nativePrivateDirty + otherPrivateDirty;
}
/**
* Return total shared dirty memory usage in kB.
*/
public int getTotalSharedDirty() {
return dalvikSharedDirty + nativeSharedDirty + otherSharedDirty;
}
/**
* Return total shared clean memory usage in kB.
*/
public int getTotalPrivateClean() {
return dalvikPrivateClean + nativePrivateClean + otherPrivateClean;
}
/**
* Return total shared clean memory usage in kB.
*/
public int getTotalSharedClean() {
return dalvikSharedClean + nativeSharedClean + otherSharedClean;
}
/**
* Return total swapped out memory in kB.
* @hide
*/
public int getTotalSwappedOut() {
return dalvikSwappedOut + nativeSwappedOut + otherSwappedOut;
}
/** @hide */
public int getOtherPss(int which) {
return otherStats[which*NUM_CATEGORIES + offsetPss];
}
/** @hide */
public int getOtherSwappablePss(int which) {
return otherStats[which*NUM_CATEGORIES + offsetSwappablePss];
}
/** @hide */
public int getOtherPrivateDirty(int which) {
return otherStats[which*NUM_CATEGORIES + offsetPrivateDirty];
}
/** @hide */
public int getOtherSharedDirty(int which) {
return otherStats[which*NUM_CATEGORIES + offsetSharedDirty];
}
/** @hide */
public int getOtherPrivateClean(int which) {
return otherStats[which*NUM_CATEGORIES + offsetPrivateClean];
}
/** @hide */
public int getOtherSharedClean(int which) {
return otherStats[which*NUM_CATEGORIES + offsetSharedClean];
}
/** @hide */
public int getOtherSwappedOut(int which) {
return otherStats[which*NUM_CATEGORIES + offsetSwappedOut];
}
/** @hide */
public static String getOtherLabel(int which) {
switch (which) {
case 0: return "Dalvik Other";
case 1: return "Stack";
case 2: return "Cursor";
case 3: return "Ashmem";
case 4: return "Other dev";
case 5: return ".so mmap";
case 6: return ".jar mmap";
case 7: return ".apk mmap";
case 8: return ".ttf mmap";
case 9: return ".dex mmap";
case 10: return "code mmap";
case 11: return "image mmap";
case 12: return "Other mmap";
case 13: return "Graphics";
case 14: return "GL";
case 15: return "Memtrack";
case 16: return ".Heap";
case 17: return ".LOS";
case 18: return ".LinearAlloc";
case 19: return ".GC";
case 20: return ".JITCache";
default: return "????";
}
}
public int describeContents() {
return 0;
}
public void writeToParcel(Parcel dest, int flags) {
dest.writeInt(dalvikPss);
dest.writeInt(dalvikSwappablePss);
dest.writeInt(dalvikPrivateDirty);
dest.writeInt(dalvikSharedDirty);
dest.writeInt(dalvikPrivateClean);
dest.writeInt(dalvikSharedClean);
dest.writeInt(dalvikSwappedOut);
dest.writeInt(nativePss);
dest.writeInt(nativeSwappablePss);
dest.writeInt(nativePrivateDirty);
dest.writeInt(nativeSharedDirty);
dest.writeInt(nativePrivateClean);
dest.writeInt(nativeSharedClean);
dest.writeInt(nativeSwappedOut);
dest.writeInt(otherPss);
dest.writeInt(otherSwappablePss);
dest.writeInt(otherPrivateDirty);
dest.writeInt(otherSharedDirty);
dest.writeInt(otherPrivateClean);
dest.writeInt(otherSharedClean);
dest.writeInt(otherSwappedOut);
dest.writeIntArray(otherStats);
}
public void readFromParcel(Parcel source) {
dalvikPss = source.readInt();
dalvikSwappablePss = source.readInt();
dalvikPrivateDirty = source.readInt();
dalvikSharedDirty = source.readInt();
dalvikPrivateClean = source.readInt();
dalvikSharedClean = source.readInt();
dalvikSwappedOut = source.readInt();
nativePss = source.readInt();
nativeSwappablePss = source.readInt();
nativePrivateDirty = source.readInt();
nativeSharedDirty = source.readInt();
nativePrivateClean = source.readInt();
nativeSharedClean = source.readInt();
nativeSwappedOut = source.readInt();
otherPss = source.readInt();
otherSwappablePss = source.readInt();
otherPrivateDirty = source.readInt();
otherSharedDirty = source.readInt();
otherPrivateClean = source.readInt();
otherSharedClean = source.readInt();
otherSwappedOut = source.readInt();
otherStats = source.createIntArray();
}
public static final Creator
* The main differences between this and {@link #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
* {@link #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.
* 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.
* 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 {@link #startMethodTracingSampling(String, int, int)} or
* "native" tracing in the emulator via {@link #startNativeTracing()}.
* The {@link #startAllocCounting() start} method resets the counts and enables counting.
* The {@link #stopAllocCounting() stop} method disables the counting so that the analysis
* code doesn't cause additional allocations. The various 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.
* NOTE TO APPLICATION DEVELOPERS: false will
* always be false in release builds. This API is typically only useful
* for platform developers.
*
* These properties are only set during platform debugging, and are not
* meant to be used as a general-purpose properties store.
*
* {@hide}
*
* @param cl The class to (possibly) modify
* @param partial If false, sets all static fields, otherwise, only set
* fields with the {@link android.os.Debug.DebugProperty}
* annotation
* @throws IllegalArgumentException if any fields are final or non-static,
* or if the type of the field does not match the type of
* the internal debugging property value.
*/
public static void setFieldsOn(Class cl, boolean partial) {
if (false) {
if (debugProperties != null) {
/* Only look for fields declared directly by the class,
* so we don't mysteriously change static fields in superclasses.
*/
for (Field field : cl.getDeclaredFields()) {
if (!partial || field.getAnnotation(DebugProperty.class) != null) {
final String propertyName = cl.getName() + "." + field.getName();
boolean isStatic = Modifier.isStatic(field.getModifiers());
boolean isFinal = Modifier.isFinal(field.getModifiers());
if (!isStatic || isFinal) {
throw new IllegalArgumentException(propertyName +
" must be static and non-final");
}
modifyFieldIfSet(field, debugProperties, propertyName);
}
}
}
} else {
Log.wtf(TAG,
"setFieldsOn(" + (cl == null ? "null" : cl.getName()) +
") called in non-DEBUG build");
}
}
/**
* Annotation to put on fields you want to set with
* {@link Debug#setFieldsOn(Class, boolean)}.
*
* @hide
*/
@Target({ ElementType.FIELD })
@Retention(RetentionPolicy.RUNTIME)
public @interface DebugProperty {
}
/**
* Get a debugging dump of a system service by name.
*
* Most services require the caller to hold android.permission.DUMP.
*
* @param name of the service to dump
* @param fd to write dump output to (usually an output log file)
* @param args to pass to the service's dump method, may be null
* @return true if the service was dumped successfully, false if
* the service could not be found or had an error while dumping
*/
public static boolean dumpService(String name, FileDescriptor fd, String[] args) {
IBinder service = ServiceManager.getService(name);
if (service == null) {
Log.e(TAG, "Can't find service to dump: " + name);
return false;
}
try {
service.dump(fd, args);
return true;
} catch (RemoteException e) {
Log.e(TAG, "Can't dump service: " + name, e);
return false;
}
}
/**
* Have the stack traces of the given native process dumped to the
* specified file. Will be appended to the file.
* @hide
*/
public static native void dumpNativeBacktraceToFile(int pid, String file);
/**
* Return a String describing the calling method and location at a particular stack depth.
* @param callStack the Thread stack
* @param depth the depth of stack to return information for.
* @return the String describing the caller at that depth.
*/
private static String getCaller(StackTraceElement callStack[], int depth) {
// callStack[4] is the caller of the method that called getCallers()
if (4 + depth >= callStack.length) {
return "
* 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.
*
* get methods return
* the specified value. And the various reset methods reset the specified
* count.
* Debug.InstructionCount icount = new Debug.InstructionCount();
* icount.resetAndStart();
* [... do lots of stuff ...]
* if (icount.collect()) {
* System.out.println("Total instructions executed: "
* + icount.globalTotal());
* System.out.println("Method invocations: "
* + icount.globalMethodInvocations());
* }
*
*/
public static class InstructionCount {
private static final int NUM_INSTR =
OpcodeInfo.MAXIMUM_PACKED_VALUE + 1;
private int[] mCounts;
public InstructionCount() {
mCounts = new int[NUM_INSTR];
}
/**
* Reset counters and ensure counts are running. Counts may
* have already been running.
*
* @return true if counting was started
*/
public boolean resetAndStart() {
try {
VMDebug.startInstructionCounting();
VMDebug.resetInstructionCount();
} catch (UnsupportedOperationException uoe) {
return false;
}
return true;
}
/**
* Collect instruction counts. May or may not stop the
* counting process.
*/
public boolean collect() {
try {
VMDebug.stopInstructionCounting();
VMDebug.getInstructionCount(mCounts);
} catch (UnsupportedOperationException uoe) {
return false;
}
return true;
}
/**
* Return the total number of instructions executed globally (i.e. in
* all threads).
*/
public int globalTotal() {
int count = 0;
for (int i = 0; i < NUM_INSTR; i++) {
count += mCounts[i];
}
return count;
}
/**
* Return the total number of method-invocation instructions
* executed globally.
*/
public int globalMethodInvocations() {
int count = 0;
for (int i = 0; i < NUM_INSTR; i++) {
if (OpcodeInfo.isInvoke(i)) {
count += mCounts[i];
}
}
return count;
}
}
/**
* A Map of typed debug properties.
*/
private static final TypedProperties debugProperties;
/*
* Load the debug properties from the standard files into debugProperties.
*/
static {
if (false) {
final String TAG = "DebugProperties";
final String[] files = { "/system/debug.prop", "/debug.prop", "/data/debug.prop" };
final TypedProperties tp = new TypedProperties();
// Read the properties from each of the files, if present.
for (String file : files) {
Reader r;
try {
r = new FileReader(file);
} catch (FileNotFoundException ex) {
// It's ok if a file is missing.
continue;
}
try {
tp.load(r);
} catch (Exception ex) {
throw new RuntimeException("Problem loading " + file, ex);
} finally {
try {
r.close();
} catch (IOException ex) {
// Ignore this error.
}
}
}
debugProperties = tp.isEmpty() ? null : tp;
} else {
debugProperties = null;
}
}
/**
* Returns true if the type of the field matches the specified class.
* Handles the case where the class is, e.g., java.lang.Boolean, but
* the field is of the primitive "boolean" type. Also handles all of
* the java.lang.Number subclasses.
*/
private static boolean fieldTypeMatches(Field field, Class cl) {
Class fieldClass = field.getType();
if (fieldClass == cl) {
return true;
}
Field primitiveTypeField;
try {
/* All of the classes we care about (Boolean, Integer, etc.)
* have a Class field called "TYPE" that points to the corresponding
* primitive class.
*/
primitiveTypeField = cl.getField("TYPE");
} catch (NoSuchFieldException ex) {
return false;
}
try {
return fieldClass == (Class) primitiveTypeField.get(null);
} catch (IllegalAccessException ex) {
return false;
}
}
/**
* Looks up the property that corresponds to the field, and sets the field's value
* if the types match.
*/
private static void modifyFieldIfSet(final Field field, final TypedProperties properties,
final String propertyName) {
if (field.getType() == java.lang.String.class) {
int stringInfo = properties.getStringInfo(propertyName);
switch (stringInfo) {
case TypedProperties.STRING_SET:
// Handle as usual below.
break;
case TypedProperties.STRING_NULL:
try {
field.set(null, null); // null object for static fields; null string
} catch (IllegalAccessException ex) {
throw new IllegalArgumentException(
"Cannot set field for " + propertyName, ex);
}
return;
case TypedProperties.STRING_NOT_SET:
return;
case TypedProperties.STRING_TYPE_MISMATCH:
throw new IllegalArgumentException(
"Type of " + propertyName + " " +
" does not match field type (" + field.getType() + ")");
default:
throw new IllegalStateException(
"Unexpected getStringInfo(" + propertyName + ") return value " +
stringInfo);
}
}
Object value = properties.get(propertyName);
if (value != null) {
if (!fieldTypeMatches(field, value.getClass())) {
throw new IllegalArgumentException(
"Type of " + propertyName + " (" + value.getClass() + ") " +
" does not match field type (" + field.getType() + ")");
}
try {
field.set(null, value); // null object for static fields
} catch (IllegalAccessException ex) {
throw new IllegalArgumentException(
"Cannot set field for " + propertyName, ex);
}
}
}
/**
* Equivalent to setFieldsOn(cl, false).
*
* @see #setFieldsOn(Class, boolean)
*
* @hide
*/
public static void setFieldsOn(Class cl) {
setFieldsOn(cl, false);
}
/**
* Reflectively sets static fields of a class based on internal debugging
* properties. This method is a no-op if false is
* false.
*
* package com.example;
*
* import android.os.Debug;
*
* public class MyDebugVars {
* public static String s = "a string";
* public static String s2 = "second string";
* public static String ns = null;
* public static boolean b = false;
* public static int i = 5;
* @Debug.DebugProperty
* public static float f = 0.1f;
* @@Debug.DebugProperty
* public static double d = 0.5d;
*
* // This MUST appear AFTER all fields are defined and initialized!
* static {
* // Sets all the fields
* Debug.setFieldsOn(MyDebugVars.class);
*
* // Sets only the fields annotated with @Debug.DebugProperty
* // Debug.setFieldsOn(MyDebugVars.class, true);
* }
* }
*
* setFieldsOn() may override the value of any field in the class based
* on internal properties that are fixed at boot time.
*