[Docs] Move heap profiler docs into repository

components/tracing/docs/heap_profiler.md

Index: components/tracing/docs/heap_profiler.md
diff --git a/components/tracing/docs/heap_profiler.md b/components/tracing/docs/heap_profiler.md
new file mode 100644
index 0000000000000000000000000000000000000000..d5c7fb8306d0679b61107d8700d043010a2a756a
--- /dev/null
+++ b/components/tracing/docs/heap_profiler.md
@@ -0,0 +1,116 @@
+# 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,
+intergrated with the chrome://tracing ecosystem.
+
+[TOC]
+
+## How to Use
+
+ * Start Chrome with the `--enable-heap-profiling` switch. This will make Chrome

[petrcermak, 2016/01/19 10:13:55]

Shouldn't this be an enumeration (1, 2, 3, ...)?

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done.

+   keep track of all allocations.
+
+ * 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.

[petrcermak, 2016/01/19 10:13:55]

maybe say "... in the heap profiler pseudo stack traces."?

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done.

+
+ * 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.
+
+ * 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]
+
+   Note that at the moment only PartitionAlloc is supported. Heap dumps for
+   malloc is currently in the prototype stage.

[petrcermak, 2016/01/19 10:13:54]

s/is/are/ (or s/dumps/dumping/ on the previous line).

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Fixed.

+
+ * Scroll down all the way to _Heap Details_.
+
+ * Pinpoint the memory bug and live happily ever after.
+
+[memory-infra]:    memory_infra.md
+[m-purple]:        https://drive.google.com/uc?id=0Bx14iZPZRgb5RFFGc0xZZEJWVFk
+[cells-heap-dump]: https://drive.google.com/uc?id=0Bx14iZPZRgb5NGlJSFRONTFoWEU
+
+## Heap Details
+
+The heap details view contains a tree that represents the heap. The size of the
+root node corresponds to the selected allocator cell.
+
+*** aside
+The size value in the heap details view will not match the value in the selected
+analysis view cell exactly. There are three reasons for this. First, the heap
+profiler reports the memory that _the program requested_, whereas the allocator
+reports the memory that it _actually allocated_ plus its own bookkeeping
+overhead. Second, allocations that happen early --- before Chrome knows that
+heap profiling is enabled --- are not captured by the heap profiler, but they
+are reported by the allocator. Third, tracing overhead is not discounted by the
+heap profiler.
+***
+
+The heap can be broken down in two ways: by _backtrace_ (marked with an ƒ), and
+by _type_ (marked with a Ⓣ). When tracing is enabled, Chrome records trace
+events, shown in the flame chart in timeline view. At every point in time these

[petrcermak, 2016/01/19 10:13:55]

nit: This makes it sounds like Chrome *only* records the trace events shown in
the flame chart, which is not the case. Not sure how to clarify that without
complicating things though.

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Replaced “shown” with “most of which appear”.

+trace events form a pseudo stack, and a vertical slice through the flame chart
+is like a backtrace. This corresponds to the ƒ nodes in the heap details view.
+Hence enabling more tracing categories will give a more detailed breakdown of
+the heap.
+
+The other way to break down the heap is by object type. At the moment this is
+only supported for PartitionAlloc.

[petrcermak, 2016/01/19 10:13:55]

The second sentence seems irrelevant at the moment since we don't support malloc
yet.

[Ruud van Asseldonk, 2016/01/19 10:44:48]

I know, but the screenshots show the icon for malloc too, so this is to clarify
that people are not doing it wrong when they don’t get dumps for malloc if they
go and try this out.

[petrcermak, 2016/01/19 11:11:30]

Do you mean the heap dump icon? As far as I understand, that's not going to be
shown for malloc.

Anyway, that's not what this sentence refers to. In fact, I think that including
it at the moment might be confusing for the readers because this suggests that
they can somehow get the malloc breakdown without types. I'd re-add it as soon
as malloc support lands.

+
+*** aside
+In official builds, only the most common type names are included due to binary
+size concerns. A development build has full type information.

[petrcermak, 2016/01/19 10:13:54]

nit: I don't like the indefinite article in front of "development build". I'd
say either "Every development build has", "All development builds have", or
simply "Development builds have".

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done.

+***
+
+To keep the trace log small, uninteresting information is omitted from heap
+dumps. The long tail of small nodes is not dumped, but grouped in an `<other>`
+node instead. Note that altough these small nodes are insignificant on their
+own, together they can be responsible for a significant portion of the heap. The
+`<other>` node is large in that case.
+
+## Example
+
+In the trace below, `ParseAuthorStyleSheet` is called at some point.
+
+![ParseAuthorStyleSheet pseudo stack][pseudo-stack]
+
+The pseudo stack of trace events translates in the tree of ƒ nodes below. Of the

[petrcermak, 2016/01/19 10:13:54]

nit: s/translates in/is translated into/

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Changed to “corresponds to”.

+23.5 MiB of memory allocated with PartitionAlloc, 1.9 MiB was allocated inside
+`ParseAuthorStyleSheet`, either directly, or at a deeper level
+(like `CSSParserImpl::parseStyleSheet`).
+
+![Memory Allocated in ParseAuthorStyleSheet][break-down-by-backtrace]
+
+By expanding `ParseAuthorStyleSheet`, we can see which types were allocated
+there. Of the 1.9 MiB, 371 KiB is spent on `ImmutableStylePropertySet`s, and

[petrcermak, 2016/01/19 10:13:55]

nit: s/is/was/ (consistency with "were allocated" in the previous sentence)

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done. You are sharp today :)

+238 KiB is spent on `StringImpl`s.

[petrcermak, 2016/01/19 10:13:54]

ditto

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done.

+
+![ParseAuthorStyleSheet broken down by type][break-down-by-type]
+
+It is also possible to break down by type first, and then by backtrace. Below
+we see that of the 23.5 MiB allocated with PartitionAlloc, 1 MiB is spent on
+`Node`s, and about half of the memory spent on nodes was allocated in
+`HTMLDocumentParser`.
+
+![The PartitionAlloc heap broken down by type first and then by backtrace][type-then-backtrace]
+
+Heap dump diffs are fully supported by trace viewer. Select a heavy memory dump,
+then with the control key select a heavy memory dump earlier in time. Below is a

[petrcermak, 2016/01/19 10:13:54]

people tend to forget things, so it might be worth reminding the reader that
heavy dumps are purple:

"select another heavy memory dump (purple)"

[petrcermak, 2016/01/19 10:13:55]

nit: Since you can also select a dump in the future, I'd say "select another
heavy memory dump".

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Hah, actually I stressed that you have to select the latest-in-time dump first,
because when I tried it looked like memory _decreased_ which didn’t make sense
at all until I found out that it depends on the order in which you select them
...

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done.

[petrcermak, 2016/01/19 11:11:30]

Oh, really? Then it's a bug in the memory UI. It shouldn't matter in which order
you select the memory dumps :-\

+diff of theverge.com before and in the middle of loading ads. We can see that 4
+MiB was allocated when parsing the documents in all those iframes, almost a

[petrcermak, 2016/01/19 10:13:54]

probably s/was/were/

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done.

+megabyte of which was due to JavaScript. (Note that this is memory on the

[petrcermak, 2016/01/19 10:13:54]

nit: s/memory on the/memory allocated by/

[Ruud van Asseldonk, 2016/01/19 10:44:48]

Done.

+PartitionAlloc alone, the total renderer memory increase was around 72 MiB.)
+
+![Diff of The Verge before and after loading ads][diff]
+
+[pseudo-stack]:            https://drive.google.com/uc?id=0Bx14iZPZRgb5M194Y2RqQjhoZkk
+[break-down-by-backtrace]: https://drive.google.com/uc?id=0Bx14iZPZRgb5ZDRQdGNnNDNIazA
+[break-down-by-type]:      https://drive.google.com/uc?id=0Bx14iZPZRgb5THJMYlpyTEN2Q2s
+[type-then-backtrace]:     https://drive.google.com/uc?id=0Bx14iZPZRgb5UGZFX1pDUVpOLUU
+[diff]:                    https://drive.google.com/uc?id=0Bx14iZPZRgb5UzNvMmVOa0RnQWs