1instrument(3)              Erlang Module Definition              instrument(3)
2
3
4

NAME

6       instrument - Analysis and Utility Functions for Instrumentation
7

DESCRIPTION

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
13   Note:
14       Note  that  this  whole module is experimental, and the representations
15       used as well as the functionality is likely to change in the future.
16
17

DATA TYPES

19       block_histogram() = tuple()
20
21              A histogram of block sizes where each interval's upper bound  is
22              twice as high as the one before it.
23
24              The  upper  bound of the first interval is provided by the func‐
25              tion that returned the histogram, and the last interval  has  no
26              upper bound.
27
28       allocation_summary() =
29           {HistogramStart :: integer() >= 0,
30            UnscannedSize :: integer() >= 0,
31            Allocations ::
32                #{Origin :: atom() =>
33                      #{Type :: atom() => block_histogram()}}}
34
35              A  summary  of  allocated  block sizes (including their headers)
36              grouped by their Origin and Type.
37
38              Origin is generally which  NIF  or  driver  that  allocated  the
39              blocks, or 'system' if it could not be determined.
40
41              Type  is the allocation category that the blocks belong to, e.g.
42              db_term, message or binary.
43
44              If one or more carriers could not be  scanned  in  full  without
45              harming  the  responsiveness of the system, UnscannedSize is the
46              number of bytes that had to be skipped.
47
48       carrier_info_list() =
49           {HistogramStart :: integer() >= 0,
50            Carriers ::
51                [{AllocatorType :: atom(),
52                  TotalSize :: integer() >= 0,
53                  UnscannedSize :: integer() >= 0,
54                  AllocatedSize :: integer() >= 0,
55                  AllocatedCount :: integer() >= 0,
56                  InPool :: boolean(),
57                  FreeBlocks :: block_histogram()}]}
58
59              AllocatorType is the type of the  allocator  that  employs  this
60              carrier.
61
62              TotalSize  is  the  total  size  of  the  carrier, including its
63              header.
64
65              AllocatedSize is the combined size of  the  carrier's  allocated
66              blocks, including their headers.
67
68              AllocatedCount is the number of allocated blocks in the carrier.
69
70              InPool is whether the carrier is in the migration pool.
71
72              FreeBlocks  is  a  histogram of the free block sizes in the car‐
73              rier.
74
75              If the carrier could not be scanned in full without harming  the
76              responsiveness  of  the  system,  UnscannedSize is the number of
77              bytes that had to be skipped.
78

EXPORTS

80       allocations() -> {ok, Result} | {error, Reason}
81
82              Types:
83
84                 Result = allocation_summary()
85                 Reason = not_enabled
86
87              Shorthand for allocations(#{}).
88
89       allocations(Options) -> {ok, Result} | {error, Reason}
90
91              Types:
92
93                 Result = allocation_summary()
94                 Reason = not_enabled
95                 Options =
96                     #{scheduler_ids => [integer() >= 0],
97                       allocator_types => [atom()],
98                       histogram_start => integer() >= 1,
99                       histogram_width => integer() >= 1}
100
101              Returns a summary of  all  tagged  allocations  in  the  system,
102              optionally filtered by allocator type and scheduler id.
103
104              Only  binaries  and  allocations  made  by  NIFs and drivers are
105              tagged by default, but this can be configured an a per-allocator
106              basis with the +M<S>atags emulator option.
107
108              If  the specified allocator types are not enabled, the call will
109              fail with {error, not_enabled}.
110
111              The following options can be used:
112
113                allocator_types:
114                  The allocator types that will be searched. Note that  blocks
115                  can  move freely between allocator types, so restricting the
116                  search to certain allocators  may  return  unexpected  types
117                  (e.g.  process  heaps  when searching binary_alloc), or hide
118                  blocks that were migrated out.
119
120                  Defaults to all alloc_util allocators.
121
122                scheduler_ids:
123                  The  scheduler  ids  whose  allocator  instances   will   be
124                  searched.  A  scheduler  id  of  0  will refer to the global
125                  instance that is  not  tied  to  any  particular  scheduler.
126                  Defaults to all schedulers and the global instance.
127
128                histogram_start:
129                  The upper bound of the first interval in the allocated block
130                  size histograms. Defaults to 128.
131
132                histogram_width:
133                  The number of intervals in the  allocated  block  size  his‐
134                  tograms. Defaults to 18.
135
136              Example:
137
138              > instrument:allocations(#{ histogram_start => 128, histogram_width => 15 }).
139              {ok,{128,0,
140                   #{udp_inet =>
141                         #{driver_event_state => {0,0,0,0,0,0,0,0,0,1,0,0,0,0,0}},
142                     system =>
143                         #{heap => {0,0,0,0,20,4,2,2,2,3,0,1,0,0,1},
144                           db_term => {271,3,1,52,80,1,0,0,0,0,0,0,0,0,0},
145                           code => {0,0,0,5,3,6,11,22,19,20,10,2,1,0,0},
146                           binary => {18,0,0,0,7,0,0,1,0,0,0,0,0,0,0},
147                           message => {0,40,78,2,2,0,0,0,0,0,0,0,0,0,0},
148                           ... }
149                     spawn_forker =>
150                         #{driver_select_data_state =>
151                               {1,0,0,0,0,0,0,0,0,0,0,0,0,0,0}},
152                     ram_file_drv => #{drv_binary => {0,0,0,0,0,0,1,0,0,0,0,0,0,0,0}},
153                     prim_file =>
154                         #{process_specific_data => {2,0,0,0,0,0,0,0,0,0,0,0,0,0,0},
155                           nif_trap_export_entry => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
156                           monitor_extended => {0,1,0,0,0,0,0,0,0,0,0,0,0,0,0},
157                           drv_binary => {0,0,0,0,0,0,1,0,3,5,0,0,0,1,0},
158                           binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}},
159                     prim_buffer =>
160                         #{nif_internal => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
161                           binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}}}}}
162
163
164       carriers() -> {ok, Result} | {error, Reason}
165
166              Types:
167
168                 Result = carrier_info_list()
169                 Reason = not_enabled
170
171              Shorthand for carriers(#{}).
172
173       carriers(Options) -> {ok, Result} | {error, Reason}
174
175              Types:
176
177                 Result = carrier_info_list()
178                 Reason = not_enabled
179                 Options =
180                     #{scheduler_ids => [integer() >= 0],
181                       allocator_types => [atom()],
182                       histogram_start => integer() >= 1,
183                       histogram_width => integer() >= 1}
184
185              Returns a summary of all carriers in the system, optionally fil‐
186              tered by allocator type and scheduler id.
187
188              If the specified allocator types are not enabled, the call  will
189              fail with {error, not_enabled}.
190
191              The following options can be used:
192
193                allocator_types:
194                  The  allocator  types that will be searched. Defaults to all
195                  alloc_util allocators.
196
197                scheduler_ids:
198                  The  scheduler  ids  whose  allocator  instances   will   be
199                  searched.  A  scheduler  id  of  0  will refer to the global
200                  instance that is  not  tied  to  any  particular  scheduler.
201                  Defaults to all schedulers and the global instance.
202
203                histogram_start:
204                  The upper bound of the first interval in the free block size
205                  histograms. Defaults to 512.
206
207                histogram_width:
208                  The number of intervals in the free block  size  histograms.
209                  Defaults to 14.
210
211              Example:
212
213              > instrument:carriers(#{ histogram_start => 512, histogram_width => 8 }).
214              {ok,{512,
215                   [{ll_alloc,1048576,0,1048344,71,false,{0,0,0,0,0,0,0,0}},
216                    {binary_alloc,1048576,0,324640,13,false,{3,0,0,1,0,0,0,2}},
217                    {eheap_alloc,2097152,0,1037200,45,false,{2,1,1,3,4,3,2,2}},
218                    {fix_alloc,32768,0,29544,82,false,{22,0,0,0,0,0,0,0}},
219                    {...}|...]}}
220
221

SEE ALSO

223       erts_alloc(3), erl(1)
224
225
226
227Ericsson AB                       tools 3.2.1                    instrument(3)
Impressum