From f6d03e527c2baf6cec779d89cac454debd9195df Mon Sep 17 00:00:00 2001 From: Rich Slogar Date: Tue, 7 Jul 2015 11:40:47 -0700 Subject: docs: studio 1.3 hprof viewer Change-Id: I075a5f8a2ac835c31ea3cc1f50f8e013e1997501 --- docs/html/images/tools/studio-dump-heap-icon.png | Bin 0 -> 399 bytes docs/html/images/tools/studio-garbage-collect.png | Bin 0 -> 376 bytes docs/html/images/tools/studio-hprof-viewer.png | Bin 0 -> 268167 bytes docs/html/tools/debugging/debugging-memory.jd | 106 ++++++++++++++------- docs/html/tools/help/hprof-conv.jd | 6 ++ docs/html/tools/performance/comparison.jd | 3 +- docs/html/tools/performance/heap-viewer/index.jd | 35 ++++--- .../html/tools/performance/memory-monitor/index.jd | 35 ++----- docs/html/tools/studio/index.jd | 19 ++++ 9 files changed, 121 insertions(+), 83 deletions(-) create mode 100644 docs/html/images/tools/studio-dump-heap-icon.png create mode 100644 docs/html/images/tools/studio-garbage-collect.png create mode 100644 docs/html/images/tools/studio-hprof-viewer.png diff --git a/docs/html/images/tools/studio-dump-heap-icon.png b/docs/html/images/tools/studio-dump-heap-icon.png new file mode 100644 index 000000000000..0e4985cbe606 Binary files /dev/null and b/docs/html/images/tools/studio-dump-heap-icon.png differ diff --git a/docs/html/images/tools/studio-garbage-collect.png b/docs/html/images/tools/studio-garbage-collect.png new file mode 100644 index 000000000000..05bb9ca37a46 Binary files /dev/null and b/docs/html/images/tools/studio-garbage-collect.png differ diff --git a/docs/html/images/tools/studio-hprof-viewer.png b/docs/html/images/tools/studio-hprof-viewer.png new file mode 100644 index 000000000000..226f3b0b4c71 Binary files /dev/null and b/docs/html/images/tools/studio-hprof-viewer.png differ diff --git a/docs/html/tools/debugging/debugging-memory.jd b/docs/html/tools/debugging/debugging-memory.jd index 5893ad1d528a..fc9520abe7f4 100644 --- a/docs/html/tools/debugging/debugging-memory.jd +++ b/docs/html/tools/debugging/debugging-memory.jd @@ -24,22 +24,22 @@ page.tags=memory,OutOfMemoryError

Because Android is designed for mobile devices, you should always be careful about how much -random-access memory (RAM) your application uses. Although Dalvik and ART perform -routine garbage collection (GC), this doesn’t mean you can ignore when and where your application allocates and +random-access memory (RAM) your app uses. Although Dalvik and ART perform +routine garbage collection (GC), this doesn’t mean you can ignore when and where your app allocates and releases memory. In order to provide a stable user experience that allows the system to quickly -switch between apps, it is important that your application does not needlessly consume memory when the user +switch between apps, it is important that your app does not needlessly consume memory when the user is not interacting with it.

Even if you follow all the best practices for Managing Your App Memory during development (which you should), you still might leak objects or introduce other memory bugs. The -only way to be certain your application is using as little memory as possible is to analyze your app’s +only way to be certain your app is using as little memory as possible is to analyze your app’s memory usage with tools. This guide shows you how to do that.

Interpreting Log Messages

-

The simplest place to begin investigating your application’s memory usage is the runtime log messages. +

The simplest place to begin investigating your app’s memory usage is the runtime log messages. Sometimes when a GC occurs, a message is printed to logcat. The logcat output is also available in the Device Monitor or directly in IDEs such as Eclipse and Android Studio.

@@ -68,8 +68,8 @@ include:
A concurrent GC that frees up memory as your heap begins to fill up.
GC_FOR_MALLOC
-
A GC caused because your application attempted to allocate memory when your heap was -already full, so the system had to stop your application and reclaim memory.
+
A GC caused because your app attempted to allocate memory when your heap was +already full, so the system had to stop your app and reclaim memory.
GC_HPROF_DUMP_HEAP
A GC that occurs when you request to create an HPROF file to analyze your heap.
@@ -107,9 +107,9 @@ a memory leak.

ART Log Messages

-

Unlike Dalvik, ART doesn't log messqages for GCs that were not explicity requested. GCs are only +

Unlike Dalvik, ART doesn't log messqages for GCs that were not explicitly requested. GCs are only printed when they are they are deemed slow. More precisely, if the GC pause exceeds than 5ms or -the GC duration exceeds 100ms. If the application is not in a pause perceptible process state, +the GC duration exceeds 100ms. If the app is not in a pause perceptible process state, then none of its GCs are deemed slow. Explicit GCs are always logged.

ART includes the following information in its garbage collection log messages:

@@ -131,15 +131,15 @@ What triggered the GC and what kind of collection it is. Reasons that may appear include:
Concurrent
-
A concurrent GC which does not suspend application threads. This GC runs in a background thread +
A concurrent GC which does not suspend app threads. This GC runs in a background thread and does not prevent allocations.
Alloc
-
The GC was initiated because your application attempted to allocate memory when your heap +
The GC was initiated because your app attempted to allocate memory when your heap was already full. In this case, the garbage collection occurred in the allocating thread.
Explicit -
The garbage collection was explicitly requested by an application, for instance, by +
The garbage collection was explicitly requested by an app, for instance, by calling {@link java.lang.System#gc()} or {@link java.lang.Runtime#gc()}. As with Dalvik, in ART it is recommended that you trust the GC and avoid requesting explicit GCs if possible. Explicit GCs are discouraged since they block the allocating thread and unnecessarily was CPU cycles. Explicit GCs @@ -153,13 +153,13 @@ RenderScript allocation objects.
The collection was caused by a heap transition; this is caused by switching the GC at run time. Collector transitions consist of copying all the objects from a free-list backed space to a bump pointer space (or visa versa). Currently collector transitions only occur when an -application changes process states from a pause perceptible state to a non pause perceptible state +app changes process states from a pause perceptible state to a non pause perceptible state (or visa versa) on low RAM devices.
HomogeneousSpaceCompact
Homogeneous space compaction is free-list space to free-list space compaction which usually -occurs when an application is moved to a pause imperceptible process state. The main reasons for doing +occurs when an app is moved to a pause imperceptible process state. The main reasons for doing this are reducing RAM usage and defragmenting the heap.
@@ -230,13 +230,39 @@ The moving GCs have a long pause which lasts for the majority of the GC duration {@code 25MB/38MB} value in the above example). If this value continues to increase and doesn't ever seem to get smaller, you could have a memory leak. Alternatively, if you are seeing GC which are for the reason "Alloc", then you are already operating near your heap capacity and can expect -OOM exceptios in the near future.

+OOM exceptions in the near future.

Viewing Heap Updates

-

To get a little information about what kind of memory your application is using and when, you can view -real-time updates to your app's heap in the Device Monitor:

+

To get a little information about what kind of memory your app is using and when, you +can view real-time updates to your app's heap in Android Studio's +HPROF viewer or in the Device Monitor:

+

Memory Monitor in Android Studio

+

Use Android Studio to view your app's memory use:

+ + +

Device Monitor

  1. Open the Device Monitor.

    From your <sdk>/tools/ directory, launch the monitor tool.

    @@ -254,8 +280,9 @@ GC. To see the first update, click the Cause GC button.

    showing the [1] Update Heap and [2] Cause GC buttons. The Heap tab on the right shows the heap results.

    -

    Continue interacting with your application to watch your heap allocation update with each garbage -collection. This can help you identify which actions in your application are likely causing too much + +

    Continue interacting with your app to watch your heap allocation update with each garbage +collection. This can help you identify which actions in your app are likely causing too much allocation and where you should try to reduce allocations and release resources.

    @@ -266,9 +293,9 @@ resources.

    As you start narrowing down memory issues, you should also use the Allocation Tracker to get a better understanding of where your memory-hogging objects are allocated. The Allocation Tracker can be useful not only for looking at specific uses of memory, but also to analyze critical -code paths in an application such as scrolling.

    +code paths in an app such as scrolling.

    -

    For example, tracking allocations when flinging a list in your application allows you to see all the +

    For example, tracking allocations when flinging a list in your app allows you to see all the allocations that need to be done for that behavior, what thread they are on, and where they came from. This is extremely valuable for tightening up these paths to reduce the work they need and improve the overall smoothness of the UI.

    @@ -281,7 +308,7 @@ improve the overall smoothness of the UI.

  2. In the DDMS window, select your app's process in the left-side panel.
  3. In the right-side panel, select the Allocation Tracker tab.
  4. Click Start Tracking.
    5. -
  5. Interact with your application to execute the code paths you want to analyze.
    6. +
  6. Interact with your app to execute the code paths you want to analyze.
  7. Click Get Allocations every time you want to update the list of allocations.
@@ -293,7 +320,7 @@ thread, in which class, in which file and at which line.

Figure 2. The Device Monitor tool, -showing recent application allocations and stack traces in the Allocation Tracker.

+showing recent app allocations and stack traces in the Allocation Tracker.

Note: You will always see some allocations from {@code @@ -458,7 +485,7 @@ with all the others.

.so mmap and .dex mmap
-
The RAM being used for mmapped .so (native) and .dex (Dalvik or ART) +
The RAM being used for mapped .so (native) and .dex (Dalvik or ART) code. The Pss Total number includes platform code shared across apps; the Private Clean is your app’s own code. Generally, the actual mapped size will be much larger—the RAM here is only what currently needs to be in RAM for code that has been executed by @@ -544,7 +571,7 @@ window, so this can help you identify memory leaks involving dialogs or other wi
AppContexts and Activities
-
The number of application {@link android.content.Context} and {@link android.app.Activity} objects that +
The number of app {@link android.content.Context} and {@link android.app.Activity} objects that currently live in your process. This can be useful to quickly identify leaked {@link android.app.Activity} objects that can’t be garbage collected due to static references on them, which is common. These objects often have a lot of other allocations associated with them and so @@ -553,7 +580,7 @@ are a good way to track large memory leaks.

Note: A {@link android.view.View} or {@link android.graphics.drawable.Drawable} object also holds a reference to the {@link android.app.Activity} that it's from, so holding a {@link android.view.View} or {@link -android.graphics.drawable.Drawable} object can also lead to your application leaking an {@link +android.graphics.drawable.Drawable} object can also lead to your app leaking an {@link android.app.Activity}.

@@ -573,7 +600,12 @@ android.app.Activity}.

HPROF. Your app's heap dump provides information about the overall state of your app's heap so you can track down problems you might have identified while viewing heap updates.

-

To retrieve your heap dump:

+ +

To retrieve your heap dump from within Android Studio, use the +Memory Monitor and +HPROF viewer. + +

You can also still perform these procedures in the Android monitor:

  1. Open the Device Monitor.

    From your <sdk>/tools/ directory, launch the monitor tool.

    @@ -589,13 +621,13 @@ then click Save.
    2. showing the [1] Dump HPROF file button.

    If you need to be more precise about when the dump is created, you can also create a heap dump -at the critical point in your application code by calling {@link android.os.Debug#dumpHprofData +at the critical point in your app code by calling {@link android.os.Debug#dumpHprofData dumpHprofData()}.

    The heap dump is provided in a format that's similar to, but not identical to one from the Java HPROF tool. The major difference in an Android heap dump is due to the fact that there are a large number of allocations in the Zygote process. But because the Zygote allocations are shared across -all application processes, they don’t matter very much to your own heap analysis.

    +all app processes, they don’t matter very much to your own heap analysis.

    To analyze your heap dump, you can use a standard tool like jhat or the Eclipse Memory Analyzer Tool (MAT). However, first @@ -609,7 +641,7 @@ hprof-conv heap-original.hprof heap-converted.hprof

    Note: If you're using the version of DDMS that's integrated into -Eclipse, you do not need to perform the HPROF converstion—it performs the conversion by +Eclipse, you do not need to perform the HPROF conversion—DDMS performs the conversion by default.

    You can now load the converted file in MAT or another heap analysis tool that understands @@ -660,7 +692,7 @@ showing what your largest objects are. Below this chart, are links to couple of

    Note: Most apps will show an instance of {@link android.content.res.Resources} near the top with a good chunk of heap, but this is - usually expected when your application uses lots of resources from your {@code res/} directory.

    + usually expected when your app uses lots of resources from your {@code res/} directory.

    @@ -699,19 +731,19 @@ to inspect the changes in memory allocation. To compare two heap dumps using MAT

    Triggering Memory Leaks

    -

    While using the tools described above, you should aggressively stress your application code and try -forcing memory leaks. One way to provoke memory leaks in your application is to let it +

    While using the tools described above, you should aggressively stress your app code and try +forcing memory leaks. One way to provoke memory leaks in your app is to let it run for a while before inspecting the heap. Leaks will trickle up to the top of the allocations in -the heap. However, the smaller the leak, the longer you need to run the application in order to see it.

    +the heap. However, the smaller the leak, the longer you need to run the app in order to see it.

    You can also trigger a memory leak in one of the following ways:

    1. Rotate the device from portrait to landscape and back again multiple times while in different -activity states. Rotating the device can often cause an application to leak an {@link android.app.Activity}, +activity states. Rotating the device can often cause an app to leak an {@link android.app.Activity}, {@link android.content.Context}, or {@link android.view.View} object because the system -recreates the {@link android.app.Activity} and if your application holds a reference +recreates the {@link android.app.Activity} and if your app holds a reference to one of those objects somewhere else, the system can't garbage collect it.
      2. -
    2. Switch between your application and another application while in different activity states (navigate to +
    3. Switch between your app and another app while in different activity states (navigate to the Home screen, then return to your app).
    diff --git a/docs/html/tools/help/hprof-conv.jd b/docs/html/tools/help/hprof-conv.jd index 982f3379e468..89d6a68ec1c6 100644 --- a/docs/html/tools/help/hprof-conv.jd +++ b/docs/html/tools/help/hprof-conv.jd @@ -18,3 +18,9 @@ to specify stdin or stdout.

    You can use "-z" to filter out zygote allocations shared by all applications.

    + +

    Note: Android Studio provides integrated access to this conversion +process. To convert a heap dump to standard HPROF format in Android Studio, right-click a heap +snapshot in the Captures view and select Export to standard .hprof.

    + + diff --git a/docs/html/tools/performance/comparison.jd b/docs/html/tools/performance/comparison.jd index cf4b7120047e..06407173fffa 100644 --- a/docs/html/tools/performance/comparison.jd +++ b/docs/html/tools/performance/comparison.jd @@ -86,7 +86,7 @@ page.article=true

    Heap Viewer

    -

    @@ -94,6 +94,7 @@ page.article=true

    +
    • Shows snapshots of a number of objects allocated by type.
      • diff --git a/docs/html/tools/performance/heap-viewer/index.jd b/docs/html/tools/performance/heap-viewer/index.jd index 9ca0c47c003c..bfcbe1fb830d 100644 --- a/docs/html/tools/performance/heap-viewer/index.jd +++ b/docs/html/tools/performance/heap-viewer/index.jd @@ -75,18 +75,23 @@ page.article=true alt="" width="400px" />

      - Figure 1. Starting Android Device Monitor. + Figure 1. Starting Memory Monitor.

    • Connect your mobile device to your computer.
      • -
    • Open your application in Android Studio, build the source, and run it on your device.
      • +
    • Open your application in Android Studio, build the source, and run it on your device or + emulator.
      • -
    • Start the Android Device Monitor from Android Studio: Tools -> Android -> Android - Device Monitor. +
    • Start the Android Device Monitor from Android Studio: Tools -> Android + -> Android Device Monitor. -
+

You can also start the Memory Monitor + in Android Studio: Click the Android tab in the lower-left corner of the application + window. The CPU and Memory Monitor views appear.

+ +
  • @@ -102,13 +107,7 @@ page.article=true

    -
  • Make sure your device and application are showing in the Devices tab.
    • - -
  • Click the DDMS button, because the Heap Viewer is one of the DDMS tools.
    • - -
  • Click the Heap tab, which is where your data will appear.
    • - -
  • In the Devices tab, select the app you want to monitor.
    • +
  • In the device and application drop-downs, select the app you want to monitor.
    • @@ -126,7 +125,9 @@ page.article=true

    -
  • To start monitoring, click the Update Heap button, which looks like a green can.
    • +
  • To save a heap dump, click the Dump Java Heap icon. The heap snapshot file + with the filename Snapshot-yyyy.mm.dd-hh.mm.ss.hprof appears in the + Captures tab.
    • @@ -147,7 +148,7 @@ page.article=true
  • Note the Heap updates will happen after every GC for this client. message.
    • -
  • Press the Cause CG button to +
  • Click the Initiate CG icon to trigger a garbage collection event.
    • @@ -166,12 +167,10 @@ page.article=true

    -
  • Click a data type to see detailed information on its current allocations on the - heap.
    • +
  • Double-click the heap snapshot file to open the heap viewer and see detailed information + about the current allocations on the heap.
    • -

    Note: To visualize allocation changes over time, combine - several snapshots of the bar graph into an animated gif or video.

    diff --git a/docs/html/tools/performance/memory-monitor/index.jd b/docs/html/tools/performance/memory-monitor/index.jd index 756ca1400725..a083a14b05fa 100644 --- a/docs/html/tools/performance/memory-monitor/index.jd +++ b/docs/html/tools/performance/memory-monitor/index.jd @@ -82,37 +82,18 @@ page.article=true

    -
  • Connect your mobile device to your computer.
    • +
  • If you're using a mobile device, connect it to your computer.
  • Open your application in Android Studio, build the source, - and run it on your device.
    • - -
  • In Android Studio, choose Tools > Android > Memory Monitor.
    • + and run it on your device or emulator. +
  • In Android Studio, choose Tools > Android > Memory Monitor. You + can also click the Android tab in the lower-left corner of the application + window to launch the Android runtime window. The CPU and Memory Monitor views appear.
    • + -
  • -
    -
      - -
      - -

      - Figure 2. Choosing the device and Activity to monitor. -

      -
      - -
    1. This opens the Memory Monitor pane.
      2. - -
    2. Choose your device from the drop-down menu at the top left of the pane.
      3. - -
    3. Choose your Activity from the drop-down menu at the top right of the pane.
      4. - -
    -
  • @@ -123,7 +104,7 @@ page.article=true alt="" width="400px" />

    - Figure 3. Allocated and free memory in Memory Monitor. + Figure 1. Allocated and free memory in Memory Monitor.

    @@ -156,7 +137,7 @@ page.article=true alt="" width="400px" />

    - Figure 4. Forcing a GC (Garbage Collection) event. + Figure 2. Forcing a GC (Garbage Collection) event.

    diff --git a/docs/html/tools/studio/index.jd b/docs/html/tools/studio/index.jd index 5041b8380761..ee69d857f2b4 100644 --- a/docs/html/tools/studio/index.jd +++ b/docs/html/tools/studio/index.jd @@ -206,6 +206,25 @@ runtime window to launch the Android runtime window. Click the Memory

    Figure 4. Monitor memory and CPU usage.

    +

    Heap dump

    +

    When you're monitoring memory usage in Android Studio you can, at the same time, initiate +garbage collection and dump the Java heap to a heap snapshot in an Android-specific HPROF binary +format file. The HPROF viewer displays classes, instances of each class, and a reference tree to +help you track memory usage and find memory leaks.

    + + +

    Figure 5. HPROF viewer with heap dump.

    + +

    To create a snapshot of the Android app heap memory, click the +Dump Java Heap icon () +in the Memory Monitor. Android Studio creates the heap snapshot file with the filename +Snapshot-yyyy.mm.dd-hh.mm.ss.hprof +in the Captures tab. Double-click the heap snapshot file to open the HPROF viewer.

    + +

    To convert a heap dump to standard HPROF format in Android Studio, right-click a heap +snapshot in the Captures view and select Export to standard .hprof.

    + +

    Data file access

    The Android SDK tools, such as Systrace, -- cgit v1.2.3-59-g8ed1b