docs/heap-profiling.html - platform/dalvik - Gitiles

 <html>
 <head>
     <title>Dalvik Heap Profiling</title>
 </head>

 <body>
 <h1>Dalvik Heap Profiling</h1>

 <p>
 The Dalvik virtual machine can produce a complete dump of the contents
 of the virtual heap.  This is very useful for debugging memory usage
 and looking for memory leaks.  Getting at the information can be tricky,
 but has become easier in recent releases.
 </p><p>
 In what follows, the version number refers to the software release
 running on the phone.  To take advantage of the DDMS integration, you will
 also need a sufficiently recent version of DDMS.


 <h2>Getting the data</h2>
 <p>
 The first step is to cause the VM to dump its status, and then pull the hprof
 data off.  The exact manner for doing so has changed over time.
 </p><p>
 There is a <code>runhat</code> shell function, added by
 <code>build/envsetup.sh</code>, that partially automates these steps.  The
 function changes in each release to accommodate newer behavior, so you have
 to be careful that you don't use the wrong version.
 </p><p>

 <h3>Early releases (1.0/1.1)</h3>
 <p>
 You can only generate heap data on the emulator or a device with root
 access, because of the way the dump is initiated and where the output
 files go.
 </p><p>
 Get a command shell on the device:
 <blockquote><pre>
 $ adb shell
 </pre></blockquote>
 </p><p>
 You can verify that you're running as root with the <code>id</code> command.
 The response should look like <code>uid=0(root) gid=0(root)</code>.  If not,
 type <code>su</code> and try again.  If <code>su</code> fails, you're out
 of luck.

 </p><p>
 Next, ensure the target directory exists:
 <blockquote><pre>
 # mkdir /data/misc
 # chmod 777 /data/misc
 </pre></blockquote>

 </p><p>
 Use <code>ps</code> or DDMS to determine the process ID of your application,
 then send a <code>SIGUSR1</code> to the target process:

 <blockquote><pre>
 # kill -10 &lt;pid&gt;
 </pre></blockquote>

 </p><p>
 The signal causes a GC, followed by the heap dump (to be completely
 accurate, they actually happen concurrently, but the results in the heap
 dump reflect the post-GC state).  This can take a couple of seconds,
 so you have to watch for the GC log message to know when it's complete.
 </p><p>
 Next:

 <blockquote><pre>
 # ls /data/misc/heap-dump*
 # exit
 </pre></blockquote>

 </p><p>
 Use <code>ls</code> to check the file names, then <code>exit</code> to quit
 the device command shell.

 </p><p>
 You should see two output files, named
 <code>/data/misc/heap-dump-BLAH-BLAH.hprof</code> and
 <code>.hprof-head</code>, where BLAH is a runtime-generated value
 that ensures the filename is unique.  Pull them off of the device and
 remove the device-side copy:

 <blockquote><pre>
 $ adb pull /data/misc/heap-dump-BLAH-BLAH.hprof tail.hprof
 $ adb pull /data/misc/heap-dump-BLAH-BLAH.hprof-head head.hprof
 $ adb shell rm /data/misc/heap-dump-BLAH-BLAH.hprof /data/misc/heap-dump-BLAH-BLAH.hprof-head
 </pre></blockquote>

 </p><p>
 Merge them together and remove the intermediates:

 <blockquote><pre>
 $ cat head.hprof tail.hprof &gt; dump.hprof
 $ rm head.hprof tail.hprof
 </pre></blockquote>

 </p><p>
 You now have the hprof dump in <code>dump.hprof</code>.
 </p><p>


 <h3>Android 1.5 ("Cupcake")</h3>
 <p>
 Some steps were taken to make this simpler.  Notably, the two output
 files are now combined for you, and a new API call was added that allows
 a program to write the dump at will to a specific file.  If you're not
 using the API call, you still need to be on an emulator or running as root.
 (For some builds, you can use <code>adb root</code> to restart the adb
 daemon as root.)
 </p><p>
 The basic procedure is the same as for 1.0/1.1, but only one file will
 appear in <code>/data/misc</code> (no <code>-head</code>), and upon
 completion you will see a log message that says "hprof: heap dump completed".
 It looks like this in the log:

 <blockquote><pre>
 I/dalvikvm(  289): threadid=7: reacting to signal 10
 I/dalvikvm(  289): SIGUSR1 forcing GC and HPROF dump
 I/dalvikvm(  289): hprof: dumping VM heap to "/data/misc/heap-dump-tm1240861355-pid289.hprof-hptemp".
 I/dalvikvm(  289): hprof: dumping heap strings to "/data/misc/heap-dump-tm1240861355-pid289.hprof".
 I/dalvikvm(  289): hprof: heap dump completed, temp file removed
 </pre></blockquote>

 </p><p>
 Summary: as above, use <code>mkdir</code> and <code>chmod</code>
 to ensure the directory exists and is writable by your application.
 Send the <code>SIGUSR1</code> or use the API call to initiate a dump.
 Use <code>adb pull &lt;dump-file&gt;</code> and <code>adb shell rm
 &lt;dump-file&gt;</code> to retrieve the file and remove it from the
 device.  The concatenation step is not needed.

 </p><p>
 The new API is in the <code>android.os.Debug</code> class:
 <blockquote><pre>
 public static void dumpHprofData(String fileName) throws IOException
 </pre></blockquote>
 When called, the VM will go through the same series of steps (GC and
 generate a .hprof file), but the output will be written to a file of
 your choice, e.g. <code>/sdcard/myapp.hprof</code>.  Because you're
 initiating the action from within the app, and can write the file to
 removable storage or the app's private data area, you can do this on a
 device without root access.


 <h3>Android 1.6 ("Donut")</h3>
 <p>
 No real change to the way profiling works.
 However, 1.6 introduced the <code>WRITE_EXTERNAL_STORAGE</code>
 permission, which is required to write data to the SD card.  If you're
 accustomed to writing profile data to <code>/sdcard</code>, you will
 need to enable the permission in your application's manifest.
 </p>


 <h3>Android 2.0 ("Eclair")</h3>
 <p>
 In 2.0, features were added that allow DDMS to request a heap dump on
 demand, and automatically pull the result across.  Select your application
 and click the "dump HPROF file" button in the top left.  This always
 writes files to the SD card, so
 you must have a card inserted and the permission enabled in your application.
 </p>


 <h3>Android 2.2 ("Froyo")</h3>
 <p>
 DDMS heap dump requests are now streamed directly out of the VM, removing
 the external storage requirement.
 </p>

 <h3>Android 2.3 ("Gingerbread")</h3>
 <p>
 The <code>kill -10</code> (<code>SIGUSR1</code>) method of generating heap
 dumps has been removed from the VM.
 </p>

 <h3>Android 3.0 ("Honeycomb")</h3>
 <p>
 A new command-line tool has been added:
 </p>
 <blockquote><pre>am dumpheap &lt;pid&gt; &lt;output-file-name&gt;</pre></blockquote>
 <p>
 Unlike the <code>SIGUSR1</code> approach, this does not require a rooted
 phone.  It's only necessary for the application to be debuggable (by setting
 <code>android:debuggable="true"</code> in the <code>&lt;application&gt;</code>
 element of the app manifest).  The output file is opened by "am", which
 means you can write the data to a file on <code>/sdcard</code> without
 needing the <code>WRITE_EXTERNAL_STORAGE</code> permission in your app.
 <p>
 The <code>runhat</code> shell function has been updated to use this.
 </p>

 <h2>Examining the data</h2>
 <p>
 The data file format was augmented slightly from the common hprof format,
 and due to licensing restrictions the modified <code>hat</code> tool cannot
 be distributed.  A conversion tool, <code>hprof-conv</code>, can be used
 to strip the Android-specific portions from the output.  This tool was
 first included in 1.5, but will work with older versions of Android.
 </p><p>
 The converted output should work with any hprof data analyzer, including
 <code>jhat</code>, which is available for free in the Sun JDK, and
 Eclipse MAT.

 <!-- say something about how to track down common problems, interesting
      things to look for, ...? -->

 </p><p>
 <address>Copyright &copy; 2009 The Android Open Source Project</address>

 </body>
 </html>
	<html>
	<head>
	<title>Dalvik Heap Profiling</title>
	</head>

	<body>
	<h1>Dalvik Heap Profiling</h1>

	<p>
	The Dalvik virtual machine can produce a complete dump of the contents
	of the virtual heap. This is very useful for debugging memory usage
	and looking for memory leaks. Getting at the information can be tricky,
	but has become easier in recent releases.
	</p><p>
	In what follows, the version number refers to the software release
	running on the phone. To take advantage of the DDMS integration, you will
	also need a sufficiently recent version of DDMS.


	<h2>Getting the data</h2>
	<p>
	The first step is to cause the VM to dump its status, and then pull the hprof
	data off. The exact manner for doing so has changed over time.
	</p><p>
	There is a <code>runhat</code> shell function, added by
	<code>build/envsetup.sh</code>, that partially automates these steps. The
	function changes in each release to accommodate newer behavior, so you have
	to be careful that you don't use the wrong version.
	</p><p>

	<h3>Early releases (1.0/1.1)</h3>
	<p>
	You can only generate heap data on the emulator or a device with root
	access, because of the way the dump is initiated and where the output
	files go.
	</p><p>
	Get a command shell on the device:
	<blockquote><pre>
	$ adb shell
	</pre></blockquote>
	</p><p>
	You can verify that you're running as root with the <code>id</code> command.
	The response should look like <code>uid=0(root) gid=0(root)</code>. If not,
	type <code>su</code> and try again. If <code>su</code> fails, you're out
	of luck.

	</p><p>
	Next, ensure the target directory exists:
	<blockquote><pre>
	# mkdir /data/misc
	# chmod 777 /data/misc
	</pre></blockquote>

	</p><p>
	Use <code>ps</code> or DDMS to determine the process ID of your application,
	then send a <code>SIGUSR1</code> to the target process:

	<blockquote><pre>
	# kill -10 <pid>
	</pre></blockquote>

	</p><p>
	The signal causes a GC, followed by the heap dump (to be completely
	accurate, they actually happen concurrently, but the results in the heap
	dump reflect the post-GC state). This can take a couple of seconds,
	so you have to watch for the GC log message to know when it's complete.
	</p><p>
	Next:

	<blockquote><pre>
	# ls /data/misc/heap-dump*
	# exit
	</pre></blockquote>

	</p><p>
	Use <code>ls</code> to check the file names, then <code>exit</code> to quit
	the device command shell.

	</p><p>
	You should see two output files, named
	<code>/data/misc/heap-dump-BLAH-BLAH.hprof</code> and
	<code>.hprof-head</code>, where BLAH is a runtime-generated value
	that ensures the filename is unique. Pull them off of the device and
	remove the device-side copy:

	<blockquote><pre>
	$ adb pull /data/misc/heap-dump-BLAH-BLAH.hprof tail.hprof
	$ adb pull /data/misc/heap-dump-BLAH-BLAH.hprof-head head.hprof
	$ adb shell rm /data/misc/heap-dump-BLAH-BLAH.hprof /data/misc/heap-dump-BLAH-BLAH.hprof-head
	</pre></blockquote>

	</p><p>
	Merge them together and remove the intermediates:

	<blockquote><pre>
	$ cat head.hprof tail.hprof > dump.hprof
	$ rm head.hprof tail.hprof
	</pre></blockquote>

	</p><p>
	You now have the hprof dump in <code>dump.hprof</code>.
	</p><p>


	<h3>Android 1.5 ("Cupcake")</h3>
	<p>
	Some steps were taken to make this simpler. Notably, the two output
	files are now combined for you, and a new API call was added that allows
	a program to write the dump at will to a specific file. If you're not
	using the API call, you still need to be on an emulator or running as root.
	(For some builds, you can use <code>adb root</code> to restart the adb
	daemon as root.)
	</p><p>
	The basic procedure is the same as for 1.0/1.1, but only one file will
	appear in <code>/data/misc</code> (no <code>-head</code>), and upon
	completion you will see a log message that says "hprof: heap dump completed".
	It looks like this in the log:

	<blockquote><pre>
	I/dalvikvm( 289): threadid=7: reacting to signal 10
	I/dalvikvm( 289): SIGUSR1 forcing GC and HPROF dump
	I/dalvikvm( 289): hprof: dumping VM heap to "/data/misc/heap-dump-tm1240861355-pid289.hprof-hptemp".
	I/dalvikvm( 289): hprof: dumping heap strings to "/data/misc/heap-dump-tm1240861355-pid289.hprof".
	I/dalvikvm( 289): hprof: heap dump completed, temp file removed
	</pre></blockquote>

	</p><p>
	Summary: as above, use <code>mkdir</code> and <code>chmod</code>
	to ensure the directory exists and is writable by your application.
	Send the <code>SIGUSR1</code> or use the API call to initiate a dump.
	Use <code>adb pull <dump-file></code> and <code>adb shell rm
	<dump-file></code> to retrieve the file and remove it from the
	device. The concatenation step is not needed.

	</p><p>
	The new API is in the <code>android.os.Debug</code> class:
	<blockquote><pre>
	public static void dumpHprofData(String fileName) throws IOException
	</pre></blockquote>
	When called, the VM will go through the same series of steps (GC and
	generate a .hprof file), but the output will be written to a file of
	your choice, e.g. <code>/sdcard/myapp.hprof</code>. Because you're
	initiating the action from within the app, and can write the file to
	removable storage or the app's private data area, you can do this on a
	device without root access.


	<h3>Android 1.6 ("Donut")</h3>
	<p>
	No real change to the way profiling works.
	However, 1.6 introduced the <code>WRITE_EXTERNAL_STORAGE</code>
	permission, which is required to write data to the SD card. If you're
	accustomed to writing profile data to <code>/sdcard</code>, you will
	need to enable the permission in your application's manifest.
	</p>


	<h3>Android 2.0 ("Eclair")</h3>
	<p>
	In 2.0, features were added that allow DDMS to request a heap dump on
	demand, and automatically pull the result across. Select your application
	and click the "dump HPROF file" button in the top left. This always
	writes files to the SD card, so
	you must have a card inserted and the permission enabled in your application.
	</p>


	<h3>Android 2.2 ("Froyo")</h3>
	<p>
	DDMS heap dump requests are now streamed directly out of the VM, removing
	the external storage requirement.
	</p>

	<h3>Android 2.3 ("Gingerbread")</h3>
	<p>
	The <code>kill -10</code> (<code>SIGUSR1</code>) method of generating heap
	dumps has been removed from the VM.
	</p>

	<h3>Android 3.0 ("Honeycomb")</h3>
	<p>
	A new command-line tool has been added:
	</p>
	<blockquote><pre>am dumpheap <pid> <output-file-name></pre></blockquote>
	<p>
	Unlike the <code>SIGUSR1</code> approach, this does not require a rooted
	phone. It's only necessary for the application to be debuggable (by setting
	<code>android:debuggable="true"</code> in the <code><application></code>
	element of the app manifest). The output file is opened by "am", which
	means you can write the data to a file on <code>/sdcard</code> without
	needing the <code>WRITE_EXTERNAL_STORAGE</code> permission in your app.
	<p>
	The <code>runhat</code> shell function has been updated to use this.
	</p>

	<h2>Examining the data</h2>
	<p>
	The data file format was augmented slightly from the common hprof format,
	and due to licensing restrictions the modified <code>hat</code> tool cannot
	be distributed. A conversion tool, <code>hprof-conv</code>, can be used
	to strip the Android-specific portions from the output. This tool was
	first included in 1.5, but will work with older versions of Android.
	</p><p>
	The converted output should work with any hprof data analyzer, including
	<code>jhat</code>, which is available for free in the Sun JDK, and
	Eclipse MAT.

	<!-- say something about how to track down common problems, interesting
	things to look for, ...? -->

	</p><p>
	<address>Copyright © 2009 The Android Open Source Project</address>

	</body>
	</html>