Merge pull request #6829 from josevalim/jv-move-instrument

Move instrument.erl to runtime_tools

OTP-18487

9 files changed, 791 insertions, 1 deletions

diff --git a/lib/runtime_tools/doc/src/Makefile b/lib/runtime_tools/doc/src/Makefile
index bed1358730..eb8dee2dee 100644
--- a/lib/runtime_tools/doc/src/Makefile
+++ b/lib/runtime_tools/doc/src/Makefile
@@ -40,6 +40,7 @@ XML_REF3_FILES = \
 	dbg.xml \
 	dyntrace.xml \
 	erts_alloc_config.xml \
+	instrument.xml \
 	system_information.xml \
 	msacc.xml \
 	scheduler.xml
diff --git a/lib/runtime_tools/doc/src/instrument.xml b/lib/runtime_tools/doc/src/instrument.xml
new file mode 100644
index 0000000000..80a5e8c3ba
--- /dev/null
+++ b/lib/runtime_tools/doc/src/instrument.xml
@@ -0,0 +1,255 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1998</year><year>2022</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+ 
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+    
+    </legalnotice>
+
+    <title>instrument</title>
+    <prepared>Arndt Jonasson</prepared>
+    <responsible>Torbj&ouml;rn Johnsson</responsible>
+    <docno>1</docno>
+    <approved>Bj&ouml;rn Gustavsson</approved>
+    <checked></checked>
+    <date>98-04-01</date>
+    <rev>PA1</rev>
+    <file>instrument.sgml</file>
+  </header>
+  <module since="">instrument</module>
+  <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>
+    <note>
+      <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>
+    <datatype>
+      <name name="block_histogram"/>
+      <desc>
+        <p>A histogram of block sizes where each interval's upper bound is 
+          twice as high as the one before it.</p>
+        <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>
+      <name name="allocation_summary"/>
+      <desc>
+        <p>A summary of allocated block sizes (including their headers) grouped
+          by their <c><anno>Origin</anno></c> and <c><anno>Type</anno></c>.</p>
+        <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>. 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>
+       </desc>
+    </datatype>
+    <datatype>
+      <name name="carrier_info_list"/>
+      <desc>
+        <p><c><anno>AllocatorType</anno></c> is the type of the allocator that
+          employs this carrier.</p>
+        <p><c><anno>InPool</anno></c> is whether the carrier is in the
+          migration pool.</p>
+        <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. 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
+          responsiveness of the system, <c><anno>UnscannedSize</anno></c> is
+          the number of bytes that had to be skipped.</p>
+       </desc>
+    </datatype>
+  </datatypes>
+  <funcs>
+
+    <func>
+      <name name="allocations" arity="0" since="OTP 21.0"/>
+      <fsummary>Return a summary of all allocations in the system.</fsummary>
+      <desc>
+        <p>Shorthand for
+          <seemfa marker="#allocations/1"><c>allocations(#{})</c>.</seemfa></p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="allocations" arity="1" since="OTP 21.0"/>
+      <fsummary>Return a summary of all allocations filtered by allocator type
+        and scheduler id.</fsummary>
+      <desc>
+        <p>Returns a summary of all tagged allocations in the system,
+          optionally filtered by allocator type and scheduler id.</p>
+        <p>Only binaries and allocations made by NIFs and drivers are tagged by
+          default, but this can be configured an a per-allocator basis with the
+          <seecref marker="erts:erts_alloc#M_atags"><c>+M&lt;S&gt;atags</c>
+          </seecref> emulator option.</p>
+        <p>If the specified allocator types are not enabled, the call will fail
+          with <c>{error, not_enabled}</c>.</p>
+        <p>The following options can be used:</p>
+        <taglist>
+          <tag><c>allocator_types</c></tag>
+          <item>
+            <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>
+          <item>
+            <p>The scheduler ids whose allocator instances will be searched. A
+              scheduler id of 0 will refer to the global instance that is not
+              tied to any particular scheduler. Defaults to all schedulers and
+              the global instance.</p>
+          </item>
+          <tag><c>histogram_start</c></tag>
+          <item>
+            <p>The upper bound of the first interval in the allocated block
+              size histograms. Defaults to 128.</p>
+          </item>
+          <tag><c>histogram_width</c></tag>
+          <item>
+            <p>The number of intervals in the allocated block size histograms.
+              Defaults to 18.</p>
+          </item>
+        </taglist>
+        <p><em>Example:</em></p>
+        <code type="none"><![CDATA[
+> instrument:allocations(#{ histogram_start => 128, histogram_width => 15 }).
+{ok,{128,0,
+     #{udp_inet =>
+           #{driver_event_state => {0,0,0,0,0,0,0,0,0,1,0,0,0,0,0}},
+       system =>
+           #{heap => {0,0,0,0,20,4,2,2,2,3,0,1,0,0,1},
+             db_term => {271,3,1,52,80,1,0,0,0,0,0,0,0,0,0},
+             code => {0,0,0,5,3,6,11,22,19,20,10,2,1,0,0},
+             binary => {18,0,0,0,7,0,0,1,0,0,0,0,0,0,0},
+             message => {0,40,78,2,2,0,0,0,0,0,0,0,0,0,0},
+             ... }
+       spawn_forker =>
+           #{driver_select_data_state =>
+                 {1,0,0,0,0,0,0,0,0,0,0,0,0,0,0}},
+       ram_file_drv => #{drv_binary => {0,0,0,0,0,0,1,0,0,0,0,0,0,0,0}},
+       prim_file =>
+           #{process_specific_data => {2,0,0,0,0,0,0,0,0,0,0,0,0,0,0},
+             nif_trap_export_entry => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
+             monitor_extended => {0,1,0,0,0,0,0,0,0,0,0,0,0,0,0},
+             drv_binary => {0,0,0,0,0,0,1,0,3,5,0,0,0,1,0},
+             binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}},
+       prim_buffer =>
+           #{nif_internal => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
+             binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}}}}}
+     ]]></code>
+      </desc>
+    </func>
+
+    <func>
+      <name name="carriers" arity="0" since="OTP 21.0"/>
+      <fsummary>Return a list of all carriers in the system.</fsummary>
+      <desc>
+        <p>Shorthand for
+          <seemfa marker="#carriers/1"><c>carriers(#{})</c>.</seemfa></p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="carriers" arity="1" since="OTP 21.0"/>
+      <fsummary>Return a list of all carriers filtered by allocator type and
+        scheduler id.</fsummary>
+      <desc>
+        <p>Returns a summary of all carriers in the system, optionally filtered
+          by allocator type and scheduler id.</p>
+        <p>If the specified allocator types are not enabled, the call will fail
+          with <c>{error, not_enabled}</c>.</p>
+        <p>The following options can be used:</p>
+        <taglist>
+          <tag><c>allocator_types</c></tag>
+          <item>
+            <p>The allocator types that will be searched. Defaults to all
+              <c>alloc_util</c> allocators.</p>
+          </item>
+          <tag><c>scheduler_ids</c></tag>
+          <item>
+            <p>The scheduler ids whose allocator instances will be searched. A
+              scheduler id of 0 will refer to the global instance that is not
+              tied to any particular scheduler. Defaults to all schedulers and
+              the global instance.</p>
+          </item>
+          <tag><c>histogram_start</c></tag>
+          <item>
+            <p>The upper bound of the first interval in the free block size
+              histograms. Defaults to 512.</p>
+          </item>
+          <tag><c>histogram_width</c></tag>
+          <item>
+            <p>The number of intervals in the free block size histograms.
+              Defaults to 14.</p>
+          </item>
+        </taglist>
+        <p><em>Example:</em></p>
+        <code type="none"><![CDATA[
+> instrument:carriers(#{ histogram_start => 512, histogram_width => 8 }).
+{ok,{512,
+     [{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>
+    </func>
+
+  </funcs>
+
+  <section>
+    <title>See Also</title>
+    <p><seecref marker="erts:erts_alloc">erts_alloc(3)</seecref>,
+      <seecom marker="erts:erl">erl(1)</seecom></p>
+  </section>
+</erlref>
+
diff --git a/lib/runtime_tools/doc/src/ref_man.xml b/lib/runtime_tools/doc/src/ref_man.xml
index fdca65422d..ea6e55893a 100644
--- a/lib/runtime_tools/doc/src/ref_man.xml
+++ b/lib/runtime_tools/doc/src/ref_man.xml
@@ -36,6 +36,7 @@
   <xi:include href="dbg.xml"/>
   <xi:include href="dyntrace.xml"/>
   <xi:include href="erts_alloc_config.xml"/>
+  <xi:include href="instrument.xml"/>
   <xi:include href="msacc.xml"/>
   <xi:include href="scheduler.xml"/>
   <xi:include href="system_information.xml"/>
diff --git a/lib/runtime_tools/doc/src/specs.xml b/lib/runtime_tools/doc/src/specs.xml
index 33fe7fa370..f3152d0f0c 100644
--- a/lib/runtime_tools/doc/src/specs.xml
+++ b/lib/runtime_tools/doc/src/specs.xml
@@ -3,4 +3,5 @@
   <xi:include href="../specs/specs_system_information.xml"/>
   <xi:include href="../specs/specs_msacc.xml"/>
   <xi:include href="../specs/specs_scheduler.xml"/>
+  <xi:include href="../specs/specs_instrument.xml"/>
 </specs>
diff --git a/lib/runtime_tools/src/Makefile b/lib/runtime_tools/src/Makefile
index 8e8c4074f5..6fe6511a64 100644
--- a/lib/runtime_tools/src/Makefile
+++ b/lib/runtime_tools/src/Makefile
@@ -38,6 +38,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/runtime_tools-$(VSN)
 MODULES= \
 	appmon_info \
 	erts_alloc_config \
+	instrument \
 	runtime_tools \
 	runtime_tools_sup \
 	dbg \
diff --git a/lib/runtime_tools/src/instrument.erl b/lib/runtime_tools/src/instrument.erl
new file mode 100644
index 0000000000..6b2de541ec
--- /dev/null
+++ b/lib/runtime_tools/src/instrument.erl
@@ -0,0 +1,159 @@
+%%
+%% %CopyrightBegin%
+%% 
+%% Copyright Ericsson AB 1998-2021. All Rights Reserved.
+%% 
+%% Licensed under the Apache License, Version 2.0 (the "License");
+%% you may not use this file except in compliance with the License.
+%% You may obtain a copy of the License at
+%%
+%%     http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%% 
+%% %CopyrightEnd%
+%%
+-module(instrument).
+
+-export([allocations/0, allocations/1,
+         carriers/0, carriers/1]).
+
+-type block_histogram() :: tuple().
+
+-type allocation_summary() ::
+    {HistogramStart :: non_neg_integer(),
+     UnscannedSize :: non_neg_integer(),
+     Allocations :: #{ Origin :: atom() =>
+                       #{ Type :: atom() => block_histogram() }}}.
+
+-spec allocations() -> {ok, Result} | {error, Reason} when
+    Result :: allocation_summary(),
+    Reason :: not_enabled.
+allocations() ->
+    allocations(#{}).
+
+-spec allocations(Options) -> {ok, Result} | {error, Reason} when
+    Result :: allocation_summary(),
+    Reason :: not_enabled,
+    Options :: #{ scheduler_ids => list(non_neg_integer()),
+                  allocator_types => list(atom()),
+                  histogram_start => pos_integer(),
+                  histogram_width => pos_integer() }.
+allocations(Options) ->
+    Ref = make_ref(),
+
+    Defaults = #{ scheduler_ids => lists:seq(0, erts_internal:no_aux_work_threads()-1),
+                  allocator_types => erlang:system_info(alloc_util_allocators),
+                  histogram_start => 128,
+                  histogram_width => 18 },
+
+    {HistStart, MsgCount} =
+        dispatch_gather(maps:merge(Defaults, Options), Ref,
+                        fun erts_internal:gather_alloc_histograms/1),
+
+    alloc_hist_receive(HistStart, MsgCount, Ref).
+
+alloc_hist_receive(_HistStart, 0, _Ref) ->
+    {error, not_enabled};
+alloc_hist_receive(HistStart, MsgCount, Ref) when MsgCount > 0 ->
+    {Unscanned, Histograms} = alloc_hist_receive_1(MsgCount, Ref, 0, #{}),
+    {ok, {HistStart, Unscanned, Histograms}}.
+
+alloc_hist_receive_1(0, _Ref, Unscanned, Result) ->
+    {Unscanned, Result};
+alloc_hist_receive_1(MsgCount, Ref, Unscanned0, Result0) ->
+    receive
+        {Ref, Unscanned, Tags} ->
+            Result = lists:foldl(fun alloc_hist_fold_result/2, Result0, Tags),
+            alloc_hist_receive_1(MsgCount - 1, Ref, Unscanned0 + Unscanned, Result)
+    end.
+
+alloc_hist_fold_result({Id, Type, BlockHist}, Result0) ->
+    IdAllocs0 = maps:get(Id, Result0, #{}),
+    MergedHists = case maps:find(Type, IdAllocs0) of
+                      {ok, PrevHist} ->
+                          alloc_hist_merge_hist(tuple_size(BlockHist),
+                                                BlockHist,
+                                                PrevHist);
+                      error ->
+                          BlockHist
+                  end,
+    IdAllocs = IdAllocs0#{ Type => MergedHists },
+    Result0#{ Id => IdAllocs }.
+
+alloc_hist_merge_hist(0, A, _B) ->
+    A;
+alloc_hist_merge_hist(Index, A, B) ->
+    Merged = setelement(Index, A, element(Index, A) + element(Index, B)),
+    alloc_hist_merge_hist(Index - 1, Merged, B).
+
+-type carrier_info_list() ::
+    {HistogramStart :: non_neg_integer(),
+     Carriers :: [{AllocatorType :: atom(),
+                   InPool :: boolean(),
+                   TotalSize :: non_neg_integer(),
+                   UnscannedSize :: non_neg_integer(),
+                   Allocations :: {Type :: atom(),
+                                   Count :: non_neg_integer(),
+                                   Size :: non_neg_integer()},
+                   FreeBlocks :: block_histogram()}]}.
+
+-spec carriers() -> {ok, Result} | {error, Reason} when
+    Result :: carrier_info_list(),
+    Reason :: not_enabled.
+carriers() ->
+    carriers(#{}).
+
+-spec carriers(Options) -> {ok, Result} | {error, Reason} when
+    Result :: carrier_info_list(),
+    Reason :: not_enabled,
+    Options :: #{ scheduler_ids => list(non_neg_integer()),
+                  allocator_types => list(atom()),
+                  histogram_start => pos_integer(),
+                  histogram_width => pos_integer() }.
+carriers(Options) ->
+    Ref = make_ref(),
+
+    Defaults = #{ scheduler_ids => lists:seq(0, erts_internal:no_aux_work_threads()-1),
+                  allocator_types => erlang:system_info(alloc_util_allocators),
+                  histogram_start => 512,
+                  histogram_width => 14 },
+
+    {HistStart, MsgCount} =
+        dispatch_gather(maps:merge(Defaults, Options), Ref,
+                        fun erts_internal:gather_carrier_info/1),
+
+    carrier_info_receive(HistStart, MsgCount, Ref).
+
+carrier_info_receive(_HistStart, 0, _Ref) ->
+    {error, not_enabled};
+carrier_info_receive(HistStart, MsgCount, Ref) ->
+    {ok, {HistStart, carrier_info_receive_1(MsgCount, Ref, [])}}.
+
+carrier_info_receive_1(0, _Ref, Result) ->
+    lists:flatten(Result);
+carrier_info_receive_1(MsgCount, Ref, Result0) ->
+    receive
+        {Ref, Carriers} ->
+            carrier_info_receive_1(MsgCount - 1, Ref, [Carriers, Result0])
+    end.
+
+dispatch_gather(#{ allocator_types := AllocatorTypes,
+                   scheduler_ids := SchedulerIds,
+                   histogram_start := HistStart,
+                   histogram_width := HistWidth }, Ref, Gather)
+        when is_list(AllocatorTypes),
+             is_list(SchedulerIds),
+             HistStart >= 1, HistStart =< (1 bsl 28),
+             HistWidth >= 1, HistWidth =< 32 ->
+    MsgCount = lists:sum(
+        [Gather({AllocatorType, SchedId, HistWidth, HistStart, Ref}) ||
+         SchedId <- SchedulerIds,
+         AllocatorType <- AllocatorTypes]),
+    {HistStart, MsgCount};
+dispatch_gather(_, _, _) ->
+    error(badarg).
diff --git a/lib/runtime_tools/src/runtime_tools.app.src b/lib/runtime_tools/src/runtime_tools.app.src
index dfdd58015b..0738ddf3e4 100644
--- a/lib/runtime_tools/src/runtime_tools.app.src
+++ b/lib/runtime_tools/src/runtime_tools.app.src
@@ -23,7 +23,7 @@
     {modules,      [appmon_info, dbg,observer_backend,runtime_tools,
                     runtime_tools_sup,erts_alloc_config,
 		    ttb_autostart,dyntrace,system_information,
-                    scheduler,
+                    scheduler, instrument,
                     msacc]},
     {registered,   [runtime_tools_sup]},
     {applications, [kernel, stdlib]},
diff --git a/lib/runtime_tools/test/Makefile b/lib/runtime_tools/test/Makefile
index c9578d376e..429683f044 100644
--- a/lib/runtime_tools/test/Makefile
+++ b/lib/runtime_tools/test/Makefile
@@ -5,6 +5,7 @@ include $(ERL_TOP)/make/$(TARGET)/otp.mk
 MODULES =  \
 	dyntrace_SUITE \
 	dyntrace_lttng_SUITE \
+	instrument_SUITE \
 	runtime_tools_SUITE \
 	system_information_SUITE \
 	dbg_SUITE \
diff --git a/lib/runtime_tools/test/instrument_SUITE.erl b/lib/runtime_tools/test/instrument_SUITE.erl
new file mode 100644
index 0000000000..616bc5a895
--- /dev/null
+++ b/lib/runtime_tools/test/instrument_SUITE.erl
@@ -0,0 +1,371 @@
+%%
+%% %CopyrightBegin%
+%%
+%% Copyright Ericsson AB 1998-2021. All Rights Reserved.
+%%
+%% Licensed under the Apache License, Version 2.0 (the "License");
+%% you may not use this file except in compliance with the License.
+%% You may obtain a copy of the License at
+%%
+%%     http://www.apache.org/licenses/LICENSE-2.0
+%%
+%% Unless required by applicable law or agreed to in writing, software
+%% distributed under the License is distributed on an "AS IS" BASIS,
+%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+%% See the License for the specific language governing permissions and
+%% limitations under the License.
+%%
+%% %CopyrightEnd%
+%%
+-module(instrument_SUITE).
+
+-export([all/0, suite/0, init_per_suite/1, end_per_suite/1]).
+
+-export([allocations_enabled/1, allocations_disabled/1, allocations_ramv/1,
+         carriers_enabled/1, carriers_disabled/1]).
+
+-export([test_all_alloc/2, test_per_alloc/2, test_format/3, test_abort/1,
+         generate_test_blocks/0, churn_memory/0]).
+
+-include_lib("common_test/include/ct.hrl").
+
+suite() ->
+    [{ct_hooks,[ts_install_cth]},
+     {timetrap,{minutes,5}}].
+
+all() -> 
+    [allocations_enabled, allocations_disabled, allocations_ramv,
+     carriers_enabled, carriers_disabled].
+
+init_per_suite(Config) ->
+    case test_server:is_asan() of
+	true ->
+	    %% No point testing own allocators under address sanitizer.
+	    {skip, "Address sanitizer"};
+	false ->
+	    Config
+    end.
+
+end_per_suite(_Config) ->
+    ok.
+
+
+-define(GENERATED_SBC_BLOCK_COUNT, 1000).
+-define(GENERATED_MBC_BLOCK_COUNT, ?GENERATED_SBC_BLOCK_COUNT).
+
+-define(GENERATED_BLOCK_COUNT, (?GENERATED_SBC_BLOCK_COUNT +
+                                ?GENERATED_MBC_BLOCK_COUNT)).
+-define(GENERATED_CARRIER_COUNT, ?GENERATED_SBC_BLOCK_COUNT).
+
+allocations_test(Args, Plain, PerAlloc) ->
+    run_test(Args, fun(Node) ->
+                 ok = rpc:call(Node, ?MODULE, test_all_alloc,
+                               [fun instrument:allocations/0, Plain]),
+                 ok = rpc:call(Node, ?MODULE, test_per_alloc,
+                               [fun instrument:allocations/1, PerAlloc]),
+                 ok = rpc:call(Node, ?MODULE, test_format,
+                               [#{ histogram_start => 512,
+                                   histogram_width => 4 },
+                                fun instrument:allocations/1,
+                                fun verify_allocations_output/2]),
+                 ok = rpc:call(Node, ?MODULE, test_abort,
+                               [fun erts_internal:gather_alloc_histograms/1])
+             end).
+
+allocations_enabled(Config) when is_list(Config) ->
+    allocations_test(["+Meamax", "+Muatags", "true"],
+                     fun verify_allocations_enabled/1,
+                     fun verify_allocations_enabled/2).
+
+allocations_disabled(Config) when is_list(Config) ->
+    allocations_test(["+Meamax", "+Muatags", "false"],
+                     fun verify_allocations_disabled/1,
+                     fun verify_allocations_disabled/2).
+
+allocations_ramv(Config) when is_list(Config) ->
+    allocations_test(["+Meamax", "+Muatags","true", "+Muramv","true"],
+                     fun verify_allocations_enabled/1,
+                     fun verify_allocations_enabled/2).
+
+verify_allocations_disabled(_AllocType, Result) ->
+    verify_allocations_disabled(Result).
+
+verify_allocations_disabled({ok, {_HistStart, _UnscannedBytes, Allocs}}) ->
+    true = Allocs =:= #{};
+verify_allocations_disabled({error, not_enabled}) ->
+    ok.
+
+%% Skip types that have unstable results or are unaffected by +Muatags
+verify_allocations_enabled(literal_alloc, _Result) -> ok;
+verify_allocations_enabled(temp_alloc, _Result) -> ok;
+verify_allocations_enabled(sl_alloc, _Result) -> ok;
+verify_allocations_enabled(_AllocType, Result) ->
+    verify_allocations_enabled(Result).
+
+verify_allocations_enabled({ok, {_HistStart, _UnscannedBytes, Allocs}}) ->
+    true = Allocs =/= #{}.
+
+verify_allocations_output(#{}, {ok, {_, _, Allocs}}) when Allocs =:= #{} ->
+    %% This happens when the allocator is enabled but tagging is disabled. If
+    %% there's an error that causes Allocs to always be empty when enabled it
+    %% will be caught by verify_allocations_enabled.
+    ok;
+verify_allocations_output(#{}, {error, not_enabled}) ->
+    ok;
+verify_allocations_output(#{ histogram_start := HistStart,
+                             histogram_width := HistWidth },
+                    {ok, {HistStart, _UnscannedBytes, ByOrigin}}) ->
+    AllHistograms = lists:flatten([maps:values(ByType) ||
+                                   ByType <- maps:values(ByOrigin)]),
+
+    %% Do the histograms look alright?
+    HistogramSet = ordsets:from_list(AllHistograms),
+    Verified = [H || H <- HistogramSet,
+                tuple_size(H) =:= HistWidth,
+                hist_sum(H) >= 1],
+    [] = ordsets:subtract(HistogramSet, Verified),
+
+    %% Do we have at least as many blocks as we've generated?
+    BlockCount = lists:foldl(fun(Hist, Acc) ->
+                                 hist_sum(Hist) + Acc
+                             end, 0, AllHistograms),
+    GenTotalBlockCount = ?GENERATED_BLOCK_COUNT,
+    GenSBCBlockCount = ?GENERATED_SBC_BLOCK_COUNT,
+    if
+        BlockCount < GenSBCBlockCount ->
+            ct:fail("Found ~p blocks, required at least ~p (SB)." ,
+                    [BlockCount, GenSBCBlockCount]);
+        BlockCount >= GenTotalBlockCount ->
+            ct:pal("Found ~p blocks, expected at least ~p (SB + MB).",
+                    [BlockCount, GenTotalBlockCount]);
+        BlockCount < GenTotalBlockCount ->
+            ct:pal("Found ~p blocks, expected at least ~p (SB + MB), but this "
+                    "may be due to MBCs being skipped if they're about to be "
+                    "scanned just as they're fetched from the carrier pool.",
+                    [BlockCount, GenTotalBlockCount])
+    end,
+
+    ok.
+
+%% %% %% %% %% %%
+
+carriers_test(Args, Plain, PerAlloc) ->
+    run_test(Args, fun(Node) ->
+                 ok = rpc:call(Node, ?MODULE, test_all_alloc,
+                               [fun instrument:carriers/0, Plain]),
+                 ok = rpc:call(Node, ?MODULE, test_per_alloc,
+                               [fun instrument:carriers/1, PerAlloc]),
+                 ok = rpc:call(Node, ?MODULE, test_format,
+                               [#{ histogram_start => 1024,
+                                   histogram_width => 4 },
+                                fun instrument:carriers/1,
+                                fun verify_carriers_output/2]),
+                 ok = rpc:call(Node, ?MODULE, test_abort,
+                               [fun erts_internal:gather_carrier_info/1])
+             end).
+
+carriers_enabled(Config) when is_list(Config) ->
+    carriers_test(["+Meamax"],
+                  fun verify_carriers_enabled/1,
+                  fun verify_carriers_enabled/2).
+
+carriers_disabled(Config) when is_list(Config) ->
+    carriers_test(["+Meamin"],
+                  fun verify_carriers_disabled/1,
+                  fun verify_carriers_disabled/2).
+
+verify_carriers_disabled(_AllocType, Result) ->
+    verify_carriers_disabled(Result).
+
+verify_carriers_disabled({error, not_enabled}) ->
+    ok;
+verify_carriers_disabled({ok, {_HistStart, Carriers}}) ->
+    verify_carriers_disabled_1(Carriers).
+
+verify_carriers_disabled_1([]) ->
+    ok;
+%% literal_alloc and temp_alloc can't be disabled, so we have to accept their
+%% presence in carriers_disabled/test_all_alloc.
+verify_carriers_disabled_1([Carrier | Rest]) when
+        element(1, Carrier) =:= literal_alloc;
+        element(1, Carrier) =:= temp_alloc ->
+    verify_carriers_disabled_1(Rest).
+
+verify_carriers_enabled(_AllocType, Result) ->
+    verify_carriers_enabled(Result).
+
+verify_carriers_enabled({ok, {_HistStart, [_|_]=_Carriers}}) ->
+    ok.
+
+verify_carriers_output(#{ histogram_start := HistStart,
+                          histogram_width := HistWidth },
+                       {ok, {HistStart, AllCarriers}}) ->
+
+    %% Do the carriers look alright?
+    CarrierSet = ordsets:from_list(AllCarriers),
+    Verified = [C || {AllocType,
+                      InPool,
+                      TotalSize,
+                      UnscannedSize,
+                      Allocations,
+                      FreeBlockHist} = C <- CarrierSet,
+                is_atom(AllocType),
+                is_boolean(InPool),
+                is_integer(TotalSize), TotalSize >= 1,
+                is_integer(UnscannedSize), UnscannedSize < TotalSize,
+                                           UnscannedSize >= 0,
+                is_list(Allocations),
+                tuple_size(FreeBlockHist) =:= HistWidth,
+                carrier_block_check(Allocations, FreeBlockHist)],
+    [] = ordsets:subtract(CarrierSet, Verified),
+
+    %% Do we have at least as many carriers as we've generated?
+    CarrierCount = length(AllCarriers),
+    GenSBCCount = ?GENERATED_SBC_BLOCK_COUNT,
+    if
+        CarrierCount < GenSBCCount ->
+            ct:fail("Carrier count is ~p, expected at least ~p (SBC).",
+                [CarrierCount, GenSBCCount]);
+        CarrierCount >= GenSBCCount ->
+            ct:pal("Found ~p carriers, required at least ~p (SBC)." ,
+                [CarrierCount, GenSBCCount])
+    end,
+
+    ok;
+verify_carriers_output(#{}, {error, not_enabled}) ->
+    ok.
+
+carrier_block_check(Allocations, FreeHist) ->
+    AllocCount = lists:foldl(fun({_Type, Count, _Size}, Acc) ->
+                                     Count + Acc
+                             end, 0, Allocations),
+
+    %% A carrier must contain at least one block, and the number of free blocks
+    %% must not exceed the number of allocated blocks + 1.
+    FreeCount = hist_sum(FreeHist),
+
+    (AllocCount + FreeCount) >= 1 andalso FreeCount =< (AllocCount + 1).
+
+%% %% %% %% %% %%
+
+test_all_alloc(Gather, Verify) ->
+    Verify(Gather()),
+    ok.
+
+test_per_alloc(Gather, Verify) ->
+    [begin
+         Verify(T, Gather(#{ allocator_types => [T] }))
+     end || T <- erlang:system_info(alloc_util_allocators)],
+    ok.
+
+test_format(#{ allocator_types := _ }, _, _) ->
+    error(badarg);
+test_format(Options0, Gather, Verify) ->
+    %% We limit format checking to binary_alloc since we generated the test
+    %% vectors there.
+    Options = Options0#{ allocator_types => [binary_alloc] },
+    Verify(Options, Gather(Options)),
+    ok.
+
+test_abort(Gather) ->
+    %% There's no way for us to tell whether this actually aborted or ran to
+    %% completion, but it might catch a few segfaults.
+    %% This testcase is mostly useful when run in an debug emulator as it needs
+    %% the modified reduction count to trigger the odd trap scenarios
+    Runner = self(),
+    Ref = make_ref(),
+    spawn_opt(fun() ->
+                      [begin
+                           Ref2 = make_ref(),
+                           [Gather({Type, SchedId, 1, 1, Ref2}) ||
+                               Type <- erlang:system_info(alloc_util_allocators),
+                               SchedId <- lists:seq(0, erlang:system_info(schedulers))]
+                       end || _ <- lists:seq(1,100)],
+                      Runner ! Ref
+              end, [{priority, max}]),
+    receive
+        Ref -> ok
+    end.
+
+hist_sum(H) -> hist_sum_1(H, tuple_size(H), 0).
+hist_sum_1(_H, 0, A) -> A;
+hist_sum_1(H, N, A) -> hist_sum_1(H, N - 1, element(N, H) + A).
+
+%%
+
+run_test(Args0, Test) ->
+    %% Override single-block carrier threshold for binaries to ensure we have
+    %% coverage for that path. generate_test_blocks builds a few binaries that
+    %% crosses this threshold.
+    %%
+    %% We also set the abandon carrier threshold to 70% to provoke more
+    %% activity in the carrier pool.
+    Args = Args0 ++ ["+MBsbct", "1", "+Muacul", "70"],
+    {ok, Peer, Node} = ?CT_PEER(Args),
+
+    ok = rpc:call(Node, ?MODULE, generate_test_blocks, []),
+    ok = Test(Node),
+
+    ok = rpc:call(Node, ?MODULE, churn_memory, []),
+    ok = Test(Node),
+
+    peer:stop(Peer).
+
+generate_test_blocks() ->
+    Runner = self(),
+    Ref = make_ref(),
+    spawn(fun() ->
+              %% We've set the single-block carrier threshold to 1KB so one
+              %% ought to land in a SBC and the other in a MBC. Both are kept
+              %% alive forever.
+              SBCs = [<<I, 0:(1 bsl 10)/unit:8>> ||
+                      I <- lists:seq(1, ?GENERATED_SBC_BLOCK_COUNT)],
+              MBCs = [<<I, 0:64/unit:8>> ||
+                      I <- lists:seq(1, ?GENERATED_MBC_BLOCK_COUNT)],
+              Runner ! Ref,
+              receive
+                   gurka -> gaffel ! {SBCs, MBCs}
+              end
+          end),
+    receive
+        Ref -> ok
+    end.
+
+churn_memory() ->
+    %% All processes spawned from here on have 'low' priority to avoid starving
+    %% others (e.g. the rpc process) which could cause the test to time out.
+    [begin
+         churn_list_to_binary(),
+         churn_processes(),
+         churn_ets()
+     end || _ <- lists:seq(1, erlang:system_info(schedulers))],
+    ok.
+
+churn_processes() ->
+    Pid = spawn_opt(fun churn_processes/0, [{priority, low}]),
+    [Pid ! <<I, 0:128/unit:8>> || I <- lists:seq(1, 128)].
+
+%% Nearly all types have a few allocations at all times but sl_alloc is
+%% often empty. list_to_binary on large inputs will yield and spill the
+%% state into an 'estack' which is allocated through sl_alloc.
+%%
+%% This is inherently unstable so we skip the verification step for this
+%% type, but there's still a point to hammering it.
+churn_list_to_binary() ->
+    List = binary_to_list(<<0:(1 bsl 20)/unit:8>>),
+    spawn_opt(fun() -> churn_list_to_binary_1(List) end, [{priority, low}]).
+
+churn_list_to_binary_1(List) ->
+    _ = id(list_to_binary(List)),
+    churn_list_to_binary_1(List).
+
+churn_ets() ->
+    spawn_opt(fun() -> churn_ets_1(ets:new(gurka, [])) end, [{priority, low}]).
+
+churn_ets_1(Tab) ->
+    ets:insert(Tab, {gaffel, lists:seq(1, 16)}),
+    ets:delete_all_objects(Tab),
+    churn_ets_1(Tab).
+
+id(I) ->
+    I.