FileDocCategorySizeDatePackage
PerformanceCollector.javaAPI DocAndroid 5.1 API23704Thu Mar 12 22:22:10 GMT 2015android.os

PerformanceCollector

public class PerformanceCollector extends Object
Collects performance data between two function calls in Bundle objects and outputs the results using writer of type {@link PerformanceResultsWriter}.

{@link #beginSnapshot(String)} and {@link #endSnapshot()} functions collect memory usage information and measure runtime between calls to begin and end. These functions logically wrap around an entire test, and should be called with name of test as the label, e.g. EmailPerformanceTest.

{@link #startTiming(String)} and {@link #stopTiming(String)} functions measure runtime between calls to start and stop. These functions logically wrap around a single test case or a small block of code, and should be called with the name of test case as the label, e.g. testSimpleSendMailSequence.

{@link #addIteration(String)} inserts intermediate measurement point which can be labeled with a String, e.g. Launch email app, compose, send, etc.

Snapshot and timing functions do not interfere with each other, and thus can be called in any order. The intended structure is to wrap begin/endSnapshot around calls to start/stopTiming, for example:

beginSnapshot("EmailPerformanceTest"); startTiming("testSimpleSendSequence"); addIteration("Launch email app"); addIteration("Compose"); stopTiming("Send"); startTiming("testComplexSendSequence"); stopTiming(""); startTiming("testAddLabel"); stopTiming(""); endSnapshot();

Structure of results output is up to implementor of {@link PerformanceResultsWriter }. {@hide} Pending approval for public API.

Fields Summary
public static final String
METRIC_KEY_ITERATIONS
In a results Bundle, this key references a List of iteration Bundles.
public static final String
METRIC_KEY_LABEL
In an iteration Bundle, this key describes the iteration.
public static final String
METRIC_KEY_CPU_TIME
In a results Bundle, this key reports the cpu time of the code block under measurement.
public static final String
METRIC_KEY_EXECUTION_TIME
In a results Bundle, this key reports the execution time of the code block under measurement.
public static final String
METRIC_KEY_PRE_RECEIVED_TRANSACTIONS
In a snapshot Bundle, this key reports the number of received transactions from the binder driver before collection started.
public static final String
METRIC_KEY_PRE_SENT_TRANSACTIONS
In a snapshot Bundle, this key reports the number of transactions sent by the running program before collection started.
public static final String
METRIC_KEY_RECEIVED_TRANSACTIONS
In a snapshot Bundle, this key reports the number of received transactions from the binder driver.
public static final String
METRIC_KEY_SENT_TRANSACTIONS
In a snapshot Bundle, this key reports the number of transactions sent by the running program.
public static final String
METRIC_KEY_GC_INVOCATION_COUNT
In a snapshot Bundle, this key reports the number of garbage collection invocations.
public static final String
METRIC_KEY_JAVA_ALLOCATED
In a snapshot Bundle, this key reports the amount of allocated memory used by the running program.
public static final String
METRIC_KEY_JAVA_FREE
In a snapshot Bundle, this key reports the amount of free memory available to the running program.
public static final String
METRIC_KEY_JAVA_PRIVATE_DIRTY
In a snapshot Bundle, this key reports the number of private dirty pages used by dalvik.
public static final String
METRIC_KEY_JAVA_PSS
In a snapshot Bundle, this key reports the proportional set size for dalvik.
public static final String
METRIC_KEY_JAVA_SHARED_DIRTY
In a snapshot Bundle, this key reports the number of shared dirty pages used by dalvik.
public static final String
METRIC_KEY_JAVA_SIZE
In a snapshot Bundle, this key reports the total amount of memory available to the running program.
public static final String
METRIC_KEY_NATIVE_ALLOCATED
In a snapshot Bundle, this key reports the amount of allocated memory in the native heap.
public static final String
METRIC_KEY_NATIVE_FREE
In a snapshot Bundle, this key reports the amount of free memory in the native heap.
public static final String
METRIC_KEY_NATIVE_PRIVATE_DIRTY
In a snapshot Bundle, this key reports the number of private dirty pages used by the native heap.
public static final String
METRIC_KEY_NATIVE_PSS
In a snapshot Bundle, this key reports the proportional set size for the native heap.
public static final String
METRIC_KEY_NATIVE_SHARED_DIRTY
In a snapshot Bundle, this key reports the number of shared dirty pages used by the native heap.
public static final String
METRIC_KEY_NATIVE_SIZE
In a snapshot Bundle, this key reports the size of the native heap.
public static final String
METRIC_KEY_GLOBAL_ALLOC_COUNT
In a snapshot Bundle, this key reports the number of objects allocated globally.
public static final String
METRIC_KEY_GLOBAL_ALLOC_SIZE
In a snapshot Bundle, this key reports the size of all objects allocated globally.
public static final String
METRIC_KEY_GLOBAL_FREED_COUNT
In a snapshot Bundle, this key reports the number of objects freed globally.
public static final String
METRIC_KEY_GLOBAL_FREED_SIZE
In a snapshot Bundle, this key reports the size of all objects freed globally.
public static final String
METRIC_KEY_OTHER_PRIVATE_DIRTY
In a snapshot Bundle, this key reports the number of private dirty pages used by everything else.
public static final String
METRIC_KEY_OTHER_PSS
In a snapshot Bundle, this key reports the proportional set size for everything else.
public static final String
METRIC_KEY_OTHER_SHARED_DIRTY
In a snapshot Bundle, this key reports the number of shared dirty pages used by everything else.
private PerformanceResultsWriter
mPerfWriter
private Bundle
mPerfSnapshot
private Bundle
mPerfMeasurement
private long
mSnapshotCpuTime
private long
mSnapshotExecTime
private long
mCpuTime
private long
mExecTime
Constructors Summary
public PerformanceCollector()
public PerformanceCollector(PerformanceResultsWriter writer)

        setPerformanceResultsWriter(writer);
Methods Summary
public BundleaddIteration(java.lang.String label)
Add a measured segment, and start measuring the next segment. Returns collected data in a Bundle object.

param
label description of code block between startTiming and addIteration, and between two calls to addIteration, used to label output
return
Runtime metrics stored as key/value pairs. Values are of type long, and keys include:
  • {@link #METRIC_KEY_LABEL label}
  • {@link #METRIC_KEY_CPU_TIME cpu_time}
  • {@link #METRIC_KEY_EXECUTION_TIME execution_time} 

        mCpuTime = Process.getElapsedCpuTime() - mCpuTime;
        mExecTime = SystemClock.uptimeMillis() - mExecTime;

        Bundle iteration = new Bundle();
        iteration.putString(METRIC_KEY_LABEL, label);
        iteration.putLong(METRIC_KEY_EXECUTION_TIME, mExecTime);
        iteration.putLong(METRIC_KEY_CPU_TIME, mCpuTime);
        mPerfMeasurement.getParcelableArrayList(METRIC_KEY_ITERATIONS).add(iteration);

        mExecTime = SystemClock.uptimeMillis();
        mCpuTime = Process.getElapsedCpuTime();
        return iteration;
public voidaddMeasurement(java.lang.String label, float value)
Add a float type measurement to the collector.

param
label short description of the metric that was measured
param
value float value of the measurement

        if (mPerfWriter != null)
            mPerfWriter.writeMeasurement(label, value);
public voidaddMeasurement(java.lang.String label, java.lang.String value)
Add a string field to the collector.

param
label short description of the metric that was measured
param
value string summary of the measurement

        if (mPerfWriter != null)
            mPerfWriter.writeMeasurement(label, value);
public voidaddMeasurement(java.lang.String label, long value)
Add an integer type measurement to the collector.

param
label short description of the metric that was measured
param
value long value of the measurement

        if (mPerfWriter != null)
            mPerfWriter.writeMeasurement(label, value);
public voidbeginSnapshot(java.lang.String label)
Begin collection of memory usage information.

param
label description of code block between beginSnapshot and endSnapshot, used to label output

        if (mPerfWriter != null)
            mPerfWriter.writeBeginSnapshot(label);
        startPerformanceSnapshot();
private voidendPerformanceSnapshot()

        // Stop the timing. This must be done first before any other counting is
        // stopped.
        mSnapshotCpuTime = Process.getElapsedCpuTime() - mSnapshotCpuTime;
        mSnapshotExecTime = SystemClock.uptimeMillis() - mSnapshotExecTime;

        stopAllocCounting();

        long nativeMax = Debug.getNativeHeapSize() / 1024;
        long nativeAllocated = Debug.getNativeHeapAllocatedSize() / 1024;
        long nativeFree = Debug.getNativeHeapFreeSize() / 1024;

        Debug.MemoryInfo memInfo = new Debug.MemoryInfo();
        Debug.getMemoryInfo(memInfo);

        Runtime runtime = Runtime.getRuntime();

        long dalvikMax = runtime.totalMemory() / 1024;
        long dalvikFree = runtime.freeMemory() / 1024;
        long dalvikAllocated = dalvikMax - dalvikFree;

        // Add final binder counts
        Bundle binderCounts = getBinderCounts();
        for (String key : binderCounts.keySet()) {
            mPerfSnapshot.putLong(key, binderCounts.getLong(key));
        }

        // Add alloc counts
        Bundle allocCounts = getAllocCounts();
        for (String key : allocCounts.keySet()) {
            mPerfSnapshot.putLong(key, allocCounts.getLong(key));
        }

        mPerfSnapshot.putLong(METRIC_KEY_EXECUTION_TIME, mSnapshotExecTime);
        mPerfSnapshot.putLong(METRIC_KEY_CPU_TIME, mSnapshotCpuTime);

        mPerfSnapshot.putLong(METRIC_KEY_NATIVE_SIZE, nativeMax);
        mPerfSnapshot.putLong(METRIC_KEY_NATIVE_ALLOCATED, nativeAllocated);
        mPerfSnapshot.putLong(METRIC_KEY_NATIVE_FREE, nativeFree);
        mPerfSnapshot.putLong(METRIC_KEY_NATIVE_PSS, memInfo.nativePss);
        mPerfSnapshot.putLong(METRIC_KEY_NATIVE_PRIVATE_DIRTY, memInfo.nativePrivateDirty);
        mPerfSnapshot.putLong(METRIC_KEY_NATIVE_SHARED_DIRTY, memInfo.nativeSharedDirty);

        mPerfSnapshot.putLong(METRIC_KEY_JAVA_SIZE, dalvikMax);
        mPerfSnapshot.putLong(METRIC_KEY_JAVA_ALLOCATED, dalvikAllocated);
        mPerfSnapshot.putLong(METRIC_KEY_JAVA_FREE, dalvikFree);
        mPerfSnapshot.putLong(METRIC_KEY_JAVA_PSS, memInfo.dalvikPss);
        mPerfSnapshot.putLong(METRIC_KEY_JAVA_PRIVATE_DIRTY, memInfo.dalvikPrivateDirty);
        mPerfSnapshot.putLong(METRIC_KEY_JAVA_SHARED_DIRTY, memInfo.dalvikSharedDirty);

        mPerfSnapshot.putLong(METRIC_KEY_OTHER_PSS, memInfo.otherPss);
        mPerfSnapshot.putLong(METRIC_KEY_OTHER_PRIVATE_DIRTY, memInfo.otherPrivateDirty);
        mPerfSnapshot.putLong(METRIC_KEY_OTHER_SHARED_DIRTY, memInfo.otherSharedDirty);
public BundleendSnapshot()
End collection of memory usage information. Returns collected data in a Bundle object.

return
Memory and runtime metrics stored as key/value pairs. Values are of type long, and keys include:
  • {@link #METRIC_KEY_CPU_TIME cpu_time}
  • {@link #METRIC_KEY_EXECUTION_TIME execution_time}
  • {@link #METRIC_KEY_PRE_RECEIVED_TRANSACTIONS pre_received_transactions}
  • {@link #METRIC_KEY_PRE_SENT_TRANSACTIONS pre_sent_transactions}
  • {@link #METRIC_KEY_RECEIVED_TRANSACTIONS received_transactions}
  • {@link #METRIC_KEY_SENT_TRANSACTIONS sent_transactions}
  • {@link #METRIC_KEY_GC_INVOCATION_COUNT gc_invocation_count}
  • {@link #METRIC_KEY_JAVA_ALLOCATED java_allocated}
  • {@link #METRIC_KEY_JAVA_FREE java_free}
  • {@link #METRIC_KEY_JAVA_PRIVATE_DIRTY java_private_dirty}
  • {@link #METRIC_KEY_JAVA_PSS java_pss}
  • {@link #METRIC_KEY_JAVA_SHARED_DIRTY java_shared_dirty}
  • {@link #METRIC_KEY_JAVA_SIZE java_size}
  • {@link #METRIC_KEY_NATIVE_ALLOCATED native_allocated}
  • {@link #METRIC_KEY_NATIVE_FREE native_free}
  • {@link #METRIC_KEY_NATIVE_PRIVATE_DIRTY native_private_dirty}
  • {@link #METRIC_KEY_NATIVE_PSS native_pss}
  • {@link #METRIC_KEY_NATIVE_SHARED_DIRTY native_shared_dirty}
  • {@link #METRIC_KEY_NATIVE_SIZE native_size}
  • {@link #METRIC_KEY_GLOBAL_ALLOC_COUNT global_alloc_count}
  • {@link #METRIC_KEY_GLOBAL_ALLOC_SIZE global_alloc_size}
  • {@link #METRIC_KEY_GLOBAL_FREED_COUNT global_freed_count}
  • {@link #METRIC_KEY_GLOBAL_FREED_SIZE global_freed_size}
  • {@link #METRIC_KEY_OTHER_PRIVATE_DIRTY other_private_dirty}
  • {@link #METRIC_KEY_OTHER_PSS other_pss}
  • {@link #METRIC_KEY_OTHER_SHARED_DIRTY other_shared_dirty} 

        endPerformanceSnapshot();
        if (mPerfWriter != null)
            mPerfWriter.writeEndSnapshot(mPerfSnapshot);
        return mPerfSnapshot;
private static BundlegetAllocCounts()

        Bundle results = new Bundle();
        results.putLong(METRIC_KEY_GLOBAL_ALLOC_COUNT, Debug.getGlobalAllocCount());
        results.putLong(METRIC_KEY_GLOBAL_ALLOC_SIZE, Debug.getGlobalAllocSize());
        results.putLong(METRIC_KEY_GLOBAL_FREED_COUNT, Debug.getGlobalFreedCount());
        results.putLong(METRIC_KEY_GLOBAL_FREED_SIZE, Debug.getGlobalFreedSize());
        results.putLong(METRIC_KEY_GC_INVOCATION_COUNT, Debug.getGlobalGcInvocationCount());
        return results;
private static BundlegetBinderCounts()

        Bundle results = new Bundle();
        results.putLong(METRIC_KEY_SENT_TRANSACTIONS, Debug.getBinderSentTransactions());
        results.putLong(METRIC_KEY_RECEIVED_TRANSACTIONS, Debug.getBinderReceivedTransactions());
        return results;
public voidsetPerformanceResultsWriter(android.os.PerformanceCollector$PerformanceResultsWriter writer)

        mPerfWriter = writer;
private static voidstartAllocCounting()

        // Before we start trigger a GC and reset the debug counts. Run the
        // finalizers and another GC before starting and stopping the alloc
        // counts. This will free up any objects that were just sitting around
        // waiting for their finalizers to be run.
        Runtime.getRuntime().gc();
        Runtime.getRuntime().runFinalization();
        Runtime.getRuntime().gc();

        Debug.resetAllCounts();

        // start the counts
        Debug.startAllocCounting();
private voidstartPerformanceSnapshot()

        // Create new snapshot
        mPerfSnapshot = new Bundle();

        // Add initial binder counts
        Bundle binderCounts = getBinderCounts();
        for (String key : binderCounts.keySet()) {
            mPerfSnapshot.putLong("pre_" + key, binderCounts.getLong(key));
        }

        // Force a GC and zero out the performance counters. Do this
        // before reading initial CPU/wall-clock times so we don't include
        // the cost of this setup in our final metrics.
        startAllocCounting();

        // Record CPU time up to this point, and start timing. Note: this
        // must happen at the end of this method, otherwise the timing will
        // include noise.
        mSnapshotExecTime = SystemClock.uptimeMillis();
        mSnapshotCpuTime = Process.getElapsedCpuTime();
public voidstartTiming(java.lang.String label)
Start measurement of user and cpu time.

param
label description of code block between startTiming and stopTiming, used to label output

        if (mPerfWriter != null)
            mPerfWriter.writeStartTiming(label);
        mPerfMeasurement = new Bundle();
        mPerfMeasurement.putParcelableArrayList(
                METRIC_KEY_ITERATIONS, new ArrayList<Parcelable>());
        mExecTime = SystemClock.uptimeMillis();
        mCpuTime = Process.getElapsedCpuTime();
private static voidstopAllocCounting()

        Runtime.getRuntime().gc();
        Runtime.getRuntime().runFinalization();
        Runtime.getRuntime().gc();
        Debug.stopAllocCounting();
public BundlestopTiming(java.lang.String label)
Stop measurement of user and cpu time.

param
label description of code block between addIteration or startTiming and stopTiming, used to label output
return
Runtime metrics stored in a bundle, including all iterations between calls to startTiming and stopTiming. List of iterations is keyed by {@link #METRIC_KEY_ITERATIONS iterations}.

        addIteration(label);
        if (mPerfWriter != null)
            mPerfWriter.writeStopTiming(mPerfMeasurement);
        return mPerfMeasurement;