From ffe164964fbdf5b1a7245309b2887d45b96eabf0 Mon Sep 17 00:00:00 2001
From: erikchen <erikchen@chromium.org>
Date: Thu, 22 Jun 2017 17:43:27 -0700
Subject: [PATCH] Update documentation of memory-infra to describe updates to
 heap profiling.

Native heap profiling can now be run on official builds by setting a
chrome://flag.

BUG=

Review-Url: https://codereview.chromium.org/2949353004
Cr-Commit-Position: refs/heads/master@{#481747}
---
 docs/memory-infra/heap_profiler.md | 35 ++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/docs/memory-infra/heap_profiler.md b/docs/memory-infra/heap_profiler.md
index 0910b641bf2ab9..7601867aab0730 100644
--- a/docs/memory-infra/heap_profiler.md
+++ b/docs/memory-infra/heap_profiler.md
@@ -38,20 +38,47 @@ integrated with the chrome://tracing ecosystem.
 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.
-However, you can build a special Linux / Android build that will collect
-real C/C++ stack traces.
+It's also possible to use heap profiling with native, symbolized stack traces.
+
+#### Native stack traces (Chrome - macOS/Windows)
+
+1. Using any officially distributed build of Chrome, navigate to chrome://flags,
+   and set "enable-heap-profiling" to Enabled (native mode).
+
+2. Use the [TraceOnTap][extension-link] extension to grab a trace.
+
+3. Run the following script to symbolize the trace.
+
+        third_party/catapult/tracing/bin/symbolize_trace <trace file>
+
+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.
+
+[extension-link]: https://cs.chromium.org/chromium/src/third_party/catapult/experimental/trace_on_tap/?q=traceontap+package:%5Echromium$&dr=CSs
+
+#### Native stack traces (Chromium - all OSes)
+
+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.
 
  1. Build with the following GN flags:
 
-	Linux
+	macOS / Windows
 
-        enable_profiling = true
+        symbol_level = 1
+
+  Linux
 
+        enable_profiling = true
+        symbol_level = 1
 
 	Android
 
         arm_use_thumb = false
         enable_profiling = true
+        symbol_level = 1
 
  2. Start Chrome with `--enable-heap-profiling=native` switch (notice
  	`=native` part).