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       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
18

DATA TYPES

20       block_histogram() = tuple()
21
22              A  histogram of block sizes where each interval's upper bound is
23              twice as high as the one before it.
24
25              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
29              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
33              > 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
36
37       allocation_summary() =
38           {HistogramStart :: integer() >= 0,
39            UnscannedSize :: integer() >= 0,
40            Allocations ::
41                #{Origin :: atom() =>
42                      #{Type :: atom() => block_histogram()}}}
43
44              A summary of allocated block  sizes  (including  their  headers)
45              grouped by their Origin and Type.
46
47              Origin  is  generally  which  NIF  or  driver that allocated the
48              blocks, or 'system' if it could not be determined.
49
50              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
54              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
58       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
71              AllocatorType is the type of the  allocator  that  employs  this
72              carrier.
73
74              InPool is whether the carrier is in the migration pool.
75
76              TotalSize  is  the  total  size  of  the  carrier, including its
77              header.
78
79              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
84              FreeBlocks  is  a  histogram of the free block sizes in the car‐
85              rier.
86
87              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

EXPORTS

92       allocations() -> {ok, Result} | {error, Reason}
93
94              Types:
95
96                 Result = allocation_summary()
97                 Reason = not_enabled
98
99              Shorthand for allocations(#{}).
100
101       allocations(Options) -> {ok, Result} | {error, Reason}
102
103              Types:
104
105                 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
113              Returns a summary of all tagged allocations in the  system,  op‐
114              tionally filtered by allocator type and scheduler id.
115
116              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
120              If  the specified allocator types are not enabled, the call will
121              fail with {error, not_enabled}.
122
123              The following options can be used:
124
125                allocator_types:
126                  The allocator types that will be searched.
127
128                  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
135                  Defaults to all alloc_util allocators.
136
137                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
143                histogram_start:
144                  The upper bound of the first interval in the allocated block
145                  size histograms. Defaults to 128.
146
147                histogram_width:
148                  The  number  of  intervals  in the allocated block size his‐
149                  tograms. Defaults to 18.
150
151              Example:
152
153              > 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
178
179       carriers() -> {ok, Result} | {error, Reason}
180
181              Types:
182
183                 Result = carrier_info_list()
184                 Reason = not_enabled
185
186              Shorthand for carriers(#{}).
187
188       carriers(Options) -> {ok, Result} | {error, Reason}
189
190              Types:
191
192                 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
200              Returns a summary of all carriers in the system, optionally fil‐
201              tered by allocator type and scheduler id.
202
203              If  the specified allocator types are not enabled, the call will
204              fail with {error, not_enabled}.
205
206              The following options can be used:
207
208                allocator_types:
209                  The allocator types that will be searched. Defaults  to  all
210                  alloc_util allocators.
211
212                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
218                histogram_start:
219                  The upper bound of the first interval in the free block size
220                  histograms. Defaults to 512.
221
222                histogram_width:
223                  The  number  of intervals in the free block size histograms.
224                  Defaults to 14.
225
226              Example:
227
228              > 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
238

SEE ALSO

240       erts_alloc(3), erl(1)
241
242
243
244Ericsson AB                    runtime_tools 2.0                 instrument(3)
Impressum