Skip to content

GitLab

T
tangled
Commit f98fd8c2 authored by erikchen's avatar erikchen Committed by Commit Bot
Browse files
Options

Update documentation for heap profiler. 

Change-Id: I2bdc32e10a3afc6b1a499bd0218eac95e2f848c0
Reviewed-on: https://chromium-review.googlesource.com/897123Reviewed-by: default avatarDmitry Skiba <dskiba@chromium.org>
Reviewed-by: default avatarMaria Khomenko <mariakhomenko@chromium.org>
Commit-Queue: Erik Chen <erikchen@chromium.org>
Cr-Commit-Position: refs/heads/master@{#533786}
parent ea4b7409
Hide whitespace changes
Inline Side-by-side
Showing with 49 additions and 82 deletions
docs/memory-infra/heap_profiler.md
View file @ f98fd8c2
# Heap Profiling with MemoryInfra
As of Chrome 48, MemoryInfra supports heap profiling. The core principle is
a solution that JustWorks™ on all platforms without patching or rebuilding,
integrated with the chrome://tracing ecosystem.
As of Chrome 48, MemoryInfra supports heap profiling. Chrome will track all live
allocations (calls to new or malloc without a subsequent call to delete or free)
along with sufficient metadata to identify the code that made the allocation.
[TOC]
## How to Use
## How to obtain a heap dump (M66+, Linux, macOS, Windows)
1. Start Chrome with the `--enable-heap-profiling` switch. This will make
Chrome keep track of all allocations.
1. Navigate to chrome://flags and search for `memlog`.
2. Grab a [MemoryInfra][memory-infra] trace. For best results, start tracing
first, and _then_ open a new tab that you want to trace. Furthermore,
enabling more categories (besides memory-infra) will yield more detailed
information in the heap profiler backtraces.
2. Choose the process types you want to profile with the `memlog` flag. The
most common setting is `Only Browser`.
3. When the trace has been collected, select a heavy memory dump indicated by
a purple ![M][m-purple] dot. Heap dumps are only included in heavy memory
dumps.
3. By default, small, infrequent allocations are omitted. If you want to see a
full heap dump, enable `memlog-keep-small-allocations`.
4. In the analysis view, cells marked with a triple bar icon (☰) contain heap
dumps. Select such a cell.
![Cells containing a heap dump][cells-heap-dump]
5. Scroll down all the way to _Heap Details_.
6. Pinpoint the memory bug and live happily ever after.
[memory-infra]: README.md
[m-purple]: https://storage.googleapis.com/chromium-docs.appspot.com/d7bdf4d16204c293688be2e5a0bcb2bf463dbbc3
[cells-heap-dump]: https://storage.googleapis.com/chromium-docs.appspot.com/a24d80d6a08da088e2e9c8b2b64daa215be4dacb
### Native stack traces
By default heap profiling collects pseudo allocation traces, which are based
on trace events. I.e. frames in allocation traces correspond to trace events
that were active at the time of allocations, and are not real function names.
It's also possible to use heap profiling with native, symbolized stack traces.
4. By default, stack traces use native stack traces, which does not contain any
thread information. To include the thread at time of allocation, set
`memlog-stack-mode` to `native with thread names`.
#### Native stack traces (Chrome - macOS/Windows)
5. Restart Chrome.
1. Using any officially distributed build of Chrome, navigate to chrome://flags,
and set "enable-heap-profiling" to Enabled (native mode).
6. Grab a [MemoryInfra][memory-infra] trace.
2. Use the [TraceOnTap][extension-link] extension to grab a trace.
7. Save the trace.
3. Run the following script to symbolize the trace.
8. Run the command `./third_party/catapult/tracing/bin/symbolize_trace
<path_to_trace>` to symbolize the trace. If you haven't yet done so, this
will require you to authenticate with google cloud storage to obtain access
to symbol files.
third_party/catapult/tracing/bin/symbolize_trace <trace file>
9. Turn off heap profiling in chrome://flags. Restart Chrome.
4. Load the trace file in `chrome://tracing`. Locate a purple ![M][m-purple]
dot, and continue from step *3* from the instructions above. Native stack
traces will be shown in the _Heap Details_ pane.
10. Load the (now symbolized) trace in chrome://tracing.
[extension-link]: https://cs.chromium.org/chromium/src/third_party/catapult/experimental/trace_on_tap/?q=traceontap+package:%5Echromium$&dr=CSs
## How to obtain a heap dump (M66+, Android)
#### Native stack traces (Chromium - all OSes)
To obtain native heap dumps, you will need a custom build of Chrome with the GN
arguments `enable_profiling = true`, `arm_use_thumb = false` and
`symbol_level=1`. All other steps are the same.
On Linux / Android, you need to build Chromium with special flags to use native
heap profiling. On macOS / Windows, it's also possible to use native heap
profiling with Chromium.
Alternatively, if you want to use an Official build of Chrome, navigate to
chrome://flags and set `memlog-stack-mode` to `pseudo`. This will provide
less-detailed stacks. The stacks also don't require symbolization.
1. Build with the following GN flags:
## How to obtain a heap dump (M65 and older)
macOS / Windows
For the most part, the setting `enable-heap-profiling` in `chrome://flags` has a
similar effect to the various `memlog` flags.
symbol_level = 1
Linux
## How to manually browse a heap dump
enable_profiling = true
symbol_level = 1
1. Select a heavy memory dump indicated by a purple ![M][m-purple] dot.
Android
arm_use_thumb = false
enable_profiling = true
symbol_level = 1
2. Start Chrome with `--enable-heap-profiling=native` switch (notice
`=native` part).
On Android use the command line tool before starting the app:
build/android/adb_chrome_public_command_line --enable-heap-profiling=native
(run the tool with an empty argument `''` to clear the command line)
2. In the analysis view, cells marked with a triple bar icon (☰) contain heap
dumps. Select such a cell.
3. Grab a [MemoryInfra][memory-infra] trace. You don't need any other
categories besides `memory-infra`.
![Cells containing a heap dump][cells-heap-dump]
4. Save the grabbed trace file. This step is needed because freshly
taken trace file contains raw addresses (which look like `pc:dcf5dbf8`)
instead of function names, and needs to be symbolized.
3. Scroll down all the way to _Heap Details_.
4. Symbolize the trace file. During symbolization addresses are resolved to
the corresponding function names and trace file is rewritten (but a backup
is saved with `.BACKUP` extension).
4. Pinpoint the memory bug and live happily ever after.
Linux
[memory-infra]: README.md
[m-purple]: https://storage.googleapis.com/chromium-docs.appspot.com/d7bdf4d16204c293688be2e5a0bcb2bf463dbbc3
[cells-heap-dump]: https://storage.googleapis.com/chromium-docs.appspot.com/a24d80d6a08da088e2e9c8b2b64daa215be4dacb
third_party/catapult/tracing/bin/symbolize_trace <trace file>
## How to automatically extract large allocations from a heap dump
Android
1. Run `python ./third_party/catapult/experimental/tracing/bin/diff_heap_profiler.py
<path_to_trace>`
third_party/catapult/tracing/bin/symbolize_trace --output-directory out/Release <trace file>
2. This produces a directory `output`, which contains a JSON file.
(note `--output-directory` and make sure it's right for your setup)
3. Load the contents of the JSON file in any JSON viewer, e.g.
[jsonviewer](http://jsonviewer.stack.hu/).
5. Load the trace file in `chrome://tracing`. Locate a purple ![M][m-purple]
dot, and continue from step *3* from the instructions above. Native stack
traces will be shown in the _Heap Details_ pane.
4. The JSON files shows allocations segmented by stacktrace, sorted by largest
first.
## Heap Details
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment