File 0182-tools-Update-instrument-documentation.patch of Package erlang
From 98ddc68e28a403469d106bb4b9337bb795bffef1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20H=C3=B6gberg?= <john@erlang.org>
Date: Mon, 14 Feb 2022 16:09:09 +0100
Subject: [PATCH] tools: Update `instrument` documentation
---
lib/tools/doc/src/instrument.xml | 48 ++++++++++++++++++++++----------
1 file changed, 33 insertions(+), 15 deletions(-)
diff --git a/lib/tools/doc/src/instrument.xml b/lib/tools/doc/src/instrument.xml
index 4305bad599..b1b2a8339e 100644
--- a/lib/tools/doc/src/instrument.xml
+++ b/lib/tools/doc/src/instrument.xml
@@ -36,11 +36,12 @@
<modulesummary>Analysis and Utility Functions for Instrumentation</modulesummary>
<description>
<p>The module <c>instrument</c> contains support for studying the resource
- usage in an Erlang runtime system. Currently, only the allocation of memory can
- be studied.</p>
+ usage in an Erlang runtime system. Currently, only the allocation of
+ memory can be studied.</p>
<note>
- <p>Note that this whole module is experimental, and the representations
- used as well as the functionality is likely to change in the future.</p>
+ <p>Since this module inspects internal details of the runtime system it
+ may differ greatly from one version to another. We make no compatibility
+ guarantees in this module.</p>
</note>
</description>
<datatypes>
@@ -52,6 +53,13 @@
<p>The upper bound of the first interval is provided by the function
that returned the histogram, and the last interval has no upper
bound.</p>
+ <p>For example, the histogram below has 40 (<c>message</c>) blocks
+ between 256-512 bytes in size, 78 blocks between 512-1024 bytes,2
+ blocks between 1-2KB, and 2 blocks between 2-4KB.</p>
+ <code type="none"><![CDATA[
+> instrument:allocations(#{ histogram_start => 128, histogram_width => 15 }).
+{ok, {128, 0, #{ message => {0,40,78,2,2,0,0,0,0,0,0,0,0,0,0}, ... } }}
+ ]]></code>
</desc>
</datatype>
<datatype>
@@ -62,7 +70,10 @@
<p><c><anno>Origin</anno></c> is generally which NIF or driver that
allocated the blocks, or 'system' if it could not be determined.</p>
<p><c><anno>Type</anno></c> is the allocation category that the blocks
- belong to, e.g. <c>db_term</c>, <c>message</c> or <c>binary</c>.</p>
+ belong to, e.g. <c>db_term</c>, <c>message</c> or <c>binary</c>. The
+ categories correspond to those in
+ <url href="https://github.com/erlang/otp/blob/master/erts/emulator/beam/erl_alloc.types">
+ erl_alloc.types</url>.</p>
<p>If one or more carriers could not be scanned in full without harming
the responsiveness of the system, <c><anno>UnscannedSize</anno></c>
is the number of bytes that had to be skipped.</p>
@@ -78,7 +89,10 @@
<p><c><anno>TotalSize</anno></c> is the total size of the carrier,
including its header.</p>
<p><c><anno>Allocations</anno></c> is a summary of the allocated blocks
- in the carrier.</p>
+ in the carrier. Note that carriers may contain multiple different
+ block types when carrier pools are shared between different allocator
+ types (see the <seecref marker="erts:erts_alloc#M_cp"><c>erts_alloc</c>
+ </seecref> documentation for more details).</p>
<p><c><anno>FreeBlocks</anno></c> is a histogram of the free block
sizes in the carrier.</p>
<p>If the carrier could not be scanned in full without harming the
@@ -115,11 +129,13 @@
<taglist>
<tag><c>allocator_types</c></tag>
<item>
- <p>The allocator types that will be searched. Note that blocks can
- move freely between allocator types, so restricting the search to
- certain allocators may return unexpected types (e.g. process
- heaps when searching binary_alloc), or hide blocks that were
- migrated out.</p>
+ <p>The allocator types that will be searched.</p>
+ <p>Specifying a specific allocator type may lead to strange results
+ when carrier migration between different allocator types has been
+ enabled: you may see unexpected types (e.g. process heaps when
+ searching binary_alloc), or fewer blocks than expected if the
+ carriers the blocks are on have been migrated out to an allocator
+ of a different type.</p>
<p>Defaults to all <c>alloc_util</c> allocators.</p>
</item>
<tag><c>scheduler_ids</c></tag>
@@ -217,10 +233,12 @@
<code type="none"><![CDATA[
> instrument:carriers(#{ histogram_start => 512, histogram_width => 8 }).
{ok,{512,
- [{ll_alloc,1048576,0,1048344,71,false,{0,0,0,0,0,0,0,0}},
- {binary_alloc,1048576,0,324640,13,false,{3,0,0,1,0,0,0,2}},
- {eheap_alloc,2097152,0,1037200,45,false,{2,1,1,3,4,3,2,2}},
- {fix_alloc,32768,0,29544,82,false,{22,0,0,0,0,0,0,0}},
+ [{driver_alloc,false,262144,0,
+ [{driver_alloc,1,32784}],
+ {0,0,0,0,0,0,0,1}},
+ {binary_alloc,false,32768,0,
+ [{binary_alloc,15,4304}],
+ {3,0,0,0,1,0,0,0}},
{...}|...]}}
]]></code>
</desc>
--
2.34.1
