1This directory contains android activities and host-side tests relating to libcore memory metrics.
2
3Directory structure
4===================
5
6apps
7  - Android activities. See instructions below for use.
8
9host
10  - Host-side test code (which installs & runs activites). See instructions below for use.
11
12Running LibcoreHeapMetricsTest
13==============================
14
15You can manually run this as follows:
16
17  make tradefed-all libcore-memory-metrics-tests LibcoreHeapDumper ahat
18  tradefed.sh run commandAndExit template/local_min --template:map test=libcore-memory-metrics-tests
19
20This installs and runs the LibcoreHeapDumpActivity on the device, pulls the heaps back to the host,
21analyses them, and derives metrics. You can see the metrics in the tradefed output.
22
23Manually running HeapDumpInstrumentation
24========================================
25
26This instrumentation dumps a heap, performs some configurable action (see the code for details), and
27then dumps another heap. You can run it manually as follows:
28
29  make LibcoreHeapDumper
30  adb install -g -r ${ANDROID_PRODUCT_OUT}/testcases/LibcoreHeapDumper/arm64/LibcoreHeapDumper.apk
31
32  DEVICE_EXTERNAL_STORAGE=$(adb shell 'echo -n ${EXTERNAL_STORAGE}')
33  # Pick a suitable name here:
34  RELATIVE_DIR=dumps
35  adb shell mkdir ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}
36  # It's okay if this does nothing:
37  adb shell rm -r ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}/*
38  # Pick the action you want here:
39  DUMPER_ACTION=NOOP
40  adb shell am instrument -w -e dumpdir ${RELATIVE_DIR} -e action ${DUMPER_ACTION} libcore.heapdumper/.HeapDumpInstrumentation
41  adb shell ls ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}
42  # That normally shows before.hprof and after.hprof files. If it shows an error file, adb shell cat
43  # it to see what happened. If it doesn't show anything, adb logcat to see what happened.
44
45  LOCAL_DIR=/tmp
46  mkdir -p ${LOCAL_DIR}/${RELATIVE_DIR}
47  # It's okay if this does nothing:
48  rm -r ${LOCAL_DIR}/${RELATIVE_DIR}/*
49  adb pull ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR} ${LOCAL_DIR}
50  ls ${LOCAL_DIR}/${RELATIVE_DIR}
51
52  make ahat
53  # To examine the first heap dump:
54  ahat ${LOCAL_DIR}/${RELATIVE_DIR}/before.hprof
55  # Visit the localhost URL shown; ctrl-C to exit
56  # To diff the second heap dump against the first:
57  ahat ${LOCAL_DIR}/${RELATIVE_DIR}/after.hprof --baseline ${LOCAL_DIR}/${RELATIVE_DIR}/before.hprof
58
59  # To clean up:
60  rm -r ${LOCAL_DIR}/${RELATIVE_DIR}
61  adb shell rm -r ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}
62  adb uninstall libcore.heapdumper
63
64Manually running PssInstrumentation
65===================================
66
67This instrumentation measures the PSS in kB, performs some configurable action (see the code for
68details), and then measures the PSS again. You can run it manually as follows:
69
70  make LibcoreHeapDumper
71  adb install -g -r ${ANDROID_PRODUCT_OUT}/data/app/LibcoreHeapDumper/LibcoreHeapDumper.apk
72
73  DEVICE_EXTERNAL_STORAGE=$(adb shell 'echo -n ${EXTERNAL_STORAGE}')
74  # Pick a suitable name here:
75  RELATIVE_DIR=pss
76  adb shell mkdir ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}
77  # It's okay if this does nothing:
78  adb shell rm -r ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}/*
79  # Pick the action you want here:
80  DUMPER_ACTION=NOOP
81  adb shell am instrument -w -e dumpdir ${RELATIVE_DIR} -e action ${DUMPER_ACTION} libcore.heapdumper/.PssInstrumentation
82  adb shell ls ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}
83  # That normally shows before.pss.txt and after.pss.txt files. If it shows an error file, adb shell
84  # cat it to see what happened. If it doesn't show anything, adb logcat to see what happened.
85
86  # To see the PSS measurements in kB:
87  adb shell cat ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}/before.pss.txt
88  adb shell cat ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}/after.pss.txt
89
90  # To clean up:
91  adb shell rm -r ${DEVICE_EXTERNAL_STORAGE}/${RELATIVE_DIR}
92  adb uninstall libcore.heapdumper
93