1instrument(3) Erlang Module Definition instrument(3)
2
6 instrument - Analysis and Utility Functions for Instrumentation
7
9 The module instrument contains support for studying the resource usage
10 in an Erlang runtime system. Currently, only the allocation of memory
11 can be studied.
12 Note:
14 Since this module inspects internal details of the runtime system it
15 may differ greatly from one version to another. We make no compatibil‐
16 ity guarantees in this module.
17
20 block_histogram() = tuple()
21 A histogram of block sizes where each interval's upper bound is
23 twice as high as the one before it.
24 The upper bound of the first interval is provided by the func‐
26 tion that returned the histogram, and the last interval has no
27 upper bound.
28 For example, the histogram below has 40 (message) blocks between
30 256-512 bytes in size, 78 blocks between 512-1024 bytes,2 blocks
31 between 1-2KB, and 2 blocks between 2-4KB.
32 > instrument:allocations(#{ histogram_start => 128, histogram_width => 15 }).
34 {ok, {128, 0, #{ message => {0,40,78,2,2,0,0,0,0,0,0,0,0,0,0}, ... } }}
35 allocation_summary() =
38 {HistogramStart :: integer() >= 0,
39 UnscannedSize :: integer() >= 0,
40 Allocations ::
41 #{Origin :: atom() =>
42 #{Type :: atom() => block_histogram()}}}
43 A summary of allocated block sizes (including their headers)
45 grouped by their Origin and Type.
46 Origin is generally which NIF or driver that allocated the
48 blocks, or 'system' if it could not be determined.
49 Type is the allocation category that the blocks belong to, e.g.
51 db_term, message or binary. The categories correspond to those
52 in erl_alloc.types.
53 If one or more carriers could not be scanned in full without
55 harming the responsiveness of the system, UnscannedSize is the
56 number of bytes that had to be skipped.
57 carrier_info_list() =
59 {HistogramStart :: integer() >= 0,
60 Carriers ::
61 [{AllocatorType :: atom(),
62 InPool :: boolean(),
63 TotalSize :: integer() >= 0,
64 UnscannedSize :: integer() >= 0,
65 Allocations ::
66 [{Type :: atom(),
67 Count :: integer() >= 0,
68 Size :: integer() >= 0}],
69 FreeBlocks :: block_histogram()}]}
70 AllocatorType is the type of the allocator that employs this
72 carrier.
73 InPool is whether the carrier is in the migration pool.
75 TotalSize is the total size of the carrier, including its
77 header.
78 Allocations is a summary of the allocated blocks in the carrier.
80 Note that carriers may contain multiple different block types
81 when carrier pools are shared between different allocator types
82 (see the erts_alloc documentation for more details).
83 FreeBlocks is a histogram of the free block sizes in the car‐
85 rier.
86 If the carrier could not be scanned in full without harming the
88 responsiveness of the system, UnscannedSize is the number of
89 bytes that had to be skipped.
90
92 allocations() -> {ok, Result} | {error, Reason}
93 Types:
95 Result = allocation_summary()
97 Reason = not_enabled
98 Shorthand for allocations(#{}).
100 allocations(Options) -> {ok, Result} | {error, Reason}
102 Types:
104 Result = allocation_summary()
106 Reason = not_enabled
107 Options =
108 #{scheduler_ids => [integer() >= 0],
109 allocator_types => [atom()],
110 histogram_start => integer() >= 1,
111 histogram_width => integer() >= 1}
112 Returns a summary of all tagged allocations in the system, op‐
114 tionally filtered by allocator type and scheduler id.
115 Only binaries and allocations made by NIFs and drivers are
117 tagged by default, but this can be configured an a per-allocator
118 basis with the +M<S>atags emulator option.
119 If the specified allocator types are not enabled, the call will
121 fail with {error, not_enabled}.
122 The following options can be used:
124 allocator_types:
126 The allocator types that will be searched.
127 Specifying a specific allocator type may lead to strange re‐
129 sults when carrier migration between different allocator
130 types has been enabled: you may see unexpected types (e.g.
131 process heaps when searching binary_alloc), or fewer blocks
132 than expected if the carriers the blocks are on have been
133 migrated out to an allocator of a different type.
134 Defaults to all alloc_util allocators.
136 scheduler_ids:
138 The scheduler ids whose allocator instances will be
139 searched. A scheduler id of 0 will refer to the global in‐
140 stance that is not tied to any particular scheduler. De‐
141 faults to all schedulers and the global instance.
142 histogram_start:
144 The upper bound of the first interval in the allocated block
145 size histograms. Defaults to 128.
146 histogram_width:
148 The number of intervals in the allocated block size his‐
149 tograms. Defaults to 18.
150 Example:
152 > instrument:allocations(#{ histogram_start => 128, histogram_width => 15 }).
154 {ok,{128,0,
155 #{udp_inet =>
156 #{driver_event_state => {0,0,0,0,0,0,0,0,0,1,0,0,0,0,0}},
157 system =>
158 #{heap => {0,0,0,0,20,4,2,2,2,3,0,1,0,0,1},
159 db_term => {271,3,1,52,80,1,0,0,0,0,0,0,0,0,0},
160 code => {0,0,0,5,3,6,11,22,19,20,10,2,1,0,0},
161 binary => {18,0,0,0,7,0,0,1,0,0,0,0,0,0,0},
162 message => {0,40,78,2,2,0,0,0,0,0,0,0,0,0,0},
163 ... }
164 spawn_forker =>
165 #{driver_select_data_state =>
166 {1,0,0,0,0,0,0,0,0,0,0,0,0,0,0}},
167 ram_file_drv => #{drv_binary => {0,0,0,0,0,0,1,0,0,0,0,0,0,0,0}},
168 prim_file =>
169 #{process_specific_data => {2,0,0,0,0,0,0,0,0,0,0,0,0,0,0},
170 nif_trap_export_entry => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
171 monitor_extended => {0,1,0,0,0,0,0,0,0,0,0,0,0,0,0},
172 drv_binary => {0,0,0,0,0,0,1,0,3,5,0,0,0,1,0},
173 binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}},
174 prim_buffer =>
175 #{nif_internal => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
176 binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}}}}}
177 carriers() -> {ok, Result} | {error, Reason}
180 Types:
182 Result = carrier_info_list()
184 Reason = not_enabled
185 Shorthand for carriers(#{}).
187 carriers(Options) -> {ok, Result} | {error, Reason}
189 Types:
191 Result = carrier_info_list()
193 Reason = not_enabled
194 Options =
195 #{scheduler_ids => [integer() >= 0],
196 allocator_types => [atom()],
197 histogram_start => integer() >= 1,
198 histogram_width => integer() >= 1}
199 Returns a summary of all carriers in the system, optionally fil‐
201 tered by allocator type and scheduler id.
202 If the specified allocator types are not enabled, the call will
204 fail with {error, not_enabled}.
205 The following options can be used:
207 allocator_types:
209 The allocator types that will be searched. Defaults to all
210 alloc_util allocators.
211 scheduler_ids:
213 The scheduler ids whose allocator instances will be
214 searched. A scheduler id of 0 will refer to the global in‐
215 stance that is not tied to any particular scheduler. De‐
216 faults to all schedulers and the global instance.
217 histogram_start:
219 The upper bound of the first interval in the free block size
220 histograms. Defaults to 512.
221 histogram_width:
223 The number of intervals in the free block size histograms.
224 Defaults to 14.
225 Example:
227 > instrument:carriers(#{ histogram_start => 512, histogram_width => 8 }).
229 {ok,{512,
230 [{driver_alloc,false,262144,0,
231 [{driver_alloc,1,32784}],
232 {0,0,0,0,0,0,0,1}},
233 {binary_alloc,false,32768,0,
234 [{binary_alloc,15,4304}],
235 {3,0,0,0,1,0,0,0}},
236 {...}|...]}}
237
240 erts_alloc(3), erl(1)
241Ericsson AB runtime_tools 2.0 instrument(3)