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 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 The instrument module interface was slightly changed in Erlang/OTP R9C.
18 To start an Erlang runtime system with instrumentation, use the +Mi*
21 set of command-line arguments to the erl command (see the erts_alloc(3)
22 and erl(1) man pages).
23 The basic object of study in the case of memory allocation is a memory
25 allocation map. A memory allocation map contains a list of descriptors
26 for each allocated memory block. Currently, a descriptor is a 4-tuple
27 {TypeNo, Address, Size, PidDesc}
29 where TypeNo is the memory block type number, Address is its place in
31 memory, and Size is its size, in bytes. PidDesc is either a tuple
32 {X,Y,Z} identifying the process which was executing when the block was
33 allocated, or undefined if no process was executing. The pid tuple
34 {X,Y,Z} can be transformed into a real pid by usage of the c:pid/3
35 function.
36 Various details about memory allocation:
38 Memory blocks are allocated both on the heap segment and on other mem‐
40 ory segments. This can cause the instrumentation functionality to
41 report very large holes. Currently the instrumentation functionality
42 doesn't provide any support for distinguishing between holes between
43 memory segments, and holes between allocated blocks inside memory seg‐
44 ments. The current size of the process cannot be obtained from within
45 Erlang, but can be seen with one of the system statistics tools, e.g.,
46 ps or top. The Solaris utility pmap can be useful. It reports currently
47 mapped memory segments.
48 Overhead for instrumentation: When the emulator has been started with
50 the "+Mim true" flag, each block is preceded by a 24 bytes large header
51 on a 32-bit machine and a 48 bytes large header on a 64-bit machine.
52 When the emulator has been started with the "+Mis true" flag, each
53 block is preceded by an 8 bytes large header. These are the header
54 sizes used by the Erlang 5.3/OTP R9C emulator. Other versions of the
55 emulator may use other header sizes. The function block_header_size/1
56 can be used for retrieving the header size used for a specific memory
57 allocation map. The time overhead for managing the instrumentation data
58 is small.
59 Sizes presented by the instrumentation functionality are (by the emula‐
61 tor) requested sizes, i.e. neither instrumentation headers nor headers
62 used by allocators are included.
63
65 allocator_descr(MemoryData, TypeNo) -> AllocDescr | invalid_type |
66 "unknown"
67 Types:
69 MemoryData = {term(), AllocList}
71 AllocList = [Desc]
72 Desc = {int(), int(), int(), PidDesc}
73 PidDesc = {int(), int(), int()} | undefined
74 TypeNo = int()
75 AllocDescr = atom() | string()
76 Returns the allocator description of the allocator that manages
78 memory blocks of type number TypeNo used in MemoryData. Valid
79 TypeNos are in the range returned by type_no_range/1 on this
80 specific memory allocation map. If TypeNo is an invalid integer,
81 invalid_type is returned.
82 block_header_size(MemoryData) -> int()
84 Types:
86 MemoryData = {term(), AllocList}
88 AllocList = [Desc]
89 Desc = {int(), int(), int(), PidDesc}
90 PidDesc = {int(), int(), int()} | undefined
91 Returns the memory block header size used by the emulator that
93 generated the memory allocation map. The block header size may
94 differ between different emulators.
95 class_descr(MemoryData, TypeNo) -> ClassDescr | invalid_type |
97 "unknown"
98 Types:
100 MemoryData = {term(), AllocList}
102 AllocList = [Desc]
103 Desc = {int(), int(), int(), PidDesc}
104 PidDesc = {int(), int(), int()} | undefined
105 TypeNo = int()
106 ClassDescr = atom() | string()
107 Returns the class description of the class that the type number
109 TypeNo used in MemoryData belongs to. Valid TypeNos are in the
110 range returned by type_no_range/1 on this specific memory allo‐
111 cation map. If TypeNo is an invalid integer, invalid_type is
112 returned.
113 descr(MemoryData) -> DescrMemoryData
115 Types:
117 MemoryData = {term(), AllocList}
119 AllocList = [Desc]
120 Desc = {int(), int(), int(), PidDesc}
121 PidDesc = {int(), int(), int()} | undefined
122 DescrMemoryData = {term(), DescrAllocList}
123 DescrAllocList = [DescrDesc]
124 DescrDesc = {TypeDescr, int(), int(), DescrPidDesc}
125 TypeDescr = atom() | string()
126 DescrPidDesc = pid() | undefined
127 Returns a memory allocation map where the type numbers (first
129 element of Desc) have been replaced by type descriptions, and
130 pid tuples (fourth element of Desc) have been replaced by real
131 pids.
132 holes(MemoryData) -> ok
134 Types:
136 MemoryData = {term(), AllocList}
138 AllocList = [Desc]
139 Desc = {int(), int(), int(), PidDesc}
140 PidDesc = {int(), int(), int()} | undefined
141 Prints out the size of each hole (i.e., the space between allo‐
143 cated blocks) on the terminal. NOTE: Really large holes are
144 probably holes between memory segments. The memory allocation
145 map has to be sorted (see sort/1).
146 mem_limits(MemoryData) -> {Low, High}
148 Types:
150 MemoryData = {term(), AllocList}
152 AllocList = [Desc]
153 Desc = {int(), int(), int(), PidDesc}
154 PidDesc = {int(), int(), int()} | undefined
155 Low = High = int()
156 Returns a tuple {Low, High} indicating the lowest and highest
158 address used. The memory allocation map has to be sorted (see
159 sort/1).
160 memory_data() -> MemoryData | false
162 Types:
164 MemoryData = {term(), AllocList}
166 AllocList = [Desc]
167 Desc = {int(), int(), int(), PidDesc}
168 PidDesc = {int(), int(), int()} | undefined
169 Returns MemoryData (a the memory allocation map) if the emulator
171 has been started with the "+Mim true" command-line argument;
172 otherwise, false. NOTE:memory_data/0 blocks execution of other
173 processes while the data is collected. The time it takes to col‐
174 lect the data can be substantial.
175 memory_status(StatusType) -> [StatusInfo] | false
177 Types:
179 StatusType = total | allocators | classes | types
181 StatusInfo = {About, [Info]}
182 About = atom()
183 Info = {InfoName, Current, MaxSinceLast, MaxEver}
184 InfoName = sizes|blocks
185 Current = int()
186 MaxSinceLast = int()
187 MaxEver = int()
188 Returns a list of StatusInfo if the emulator has been started
190 with the "+Mis true" or "+Mim true" command-line argument; oth‐
191 erwise, false.
192 See the read_memory_status/1 function for a description of the
194 StatusInfo term.
195 read_memory_data(File) -> MemoryData | {error, Reason}
197 Types:
199 File = string()
201 MemoryData = {term(), AllocList}
202 AllocList = [Desc]
203 Desc = {int(), int(), int(), PidDesc}
204 PidDesc = {int(), int(), int()} | undefined
205 Reads a memory allocation map from the file File and returns it.
207 The file is assumed to have been created by store_memory_data/1.
208 The error codes are the same as for file:consult/1.
209 read_memory_status(File) -> MemoryStatus | {error, Reason}
211 Types:
213 File = string()
215 MemoryStatus = [{StatusType, [StatusInfo]}]
216 StatusType = total | allocators | classes | types
217 StatusInfo = {About, [Info]}
218 About = atom()
219 Info = {InfoName, Current, MaxSinceLast, MaxEver}
220 InfoName = sizes|blocks
221 Current = int()
222 MaxSinceLast = int()
223 MaxEver = int()
224 Reads memory allocation status from the file File and returns
226 it. The file is assumed to have been created by store_mem‐
227 ory_status/1. The error codes are the same as for file:con‐
228 sult/1.
229 When StatusType is allocators, About is the allocator that the
231 information is about. When StatusType is types, About is the
232 memory block type that the information is about. Memory block
233 types are not described other than by their name and may vary
234 between emulators. When StatusType is classes, About is the mem‐
235 ory block type class that information is presented about. Memory
236 block types are classified after their use. Currently the fol‐
237 lowing classes exist:
238 process_data:
240 Erlang process specific data.
241 binary_data:
243 Erlang binaries.
244 atom_data:
246 Erlang atoms.
247 code_data:
249 Erlang code.
250 system_data:
252 Other data used by the system
253 When InfoName is sizes, Current, MaxSinceLast, and MaxEver are,
255 respectively, current size, maximum size since last call to
256 store_memory_status/1 or memory_status/1 with the specific Sta‐
257 tusType, and maximum size since the emulator was started. When
258 InfoName is blocks, Current, MaxSinceLast, and MaxEver are,
259 respectively, current number of blocks, maximum number of blocks
260 since last call to store_memory_status/1 or memory_status/1 with
261 the specific StatusType, and maximum number of blocks since the
262 emulator was started.
263 NOTE:A memory block is accounted for at "the first level" allo‐
265 cator. E.g. fix_alloc allocates its memory pools via ll_alloc.
266 When a fix_alloc block is allocated, neither the block nor the
267 pool in which it resides are accounted for as memory allocated
268 via ll_alloc even though it is.
269 sort(MemoryData) -> MemoryData
271 Types:
273 MemoryData = {term(), AllocList}
275 AllocList = [Desc]
276 Desc = {int(), int(), int(), PidDesc}
277 PidDesc = {int(), int(), int()} | undefined
278 Sorts a memory allocation map so that the addresses are in
280 ascending order.
281 store_memory_data(File) -> true|false
283 Types:
285 File = string()
287 Stores the current memory allocation map on the file File.
289 Returns true if the emulator has been started with the "+Mim
290 true" command-line argument, and the map was successfully
291 stored; otherwise, false. The contents of the file can later be
292 read using read_memory_data/1. NOTE:store_memory_data/0 blocks
293 execution of other processes while the data is collected. The
294 time it takes to collect the data can be substantial.
295 store_memory_status(File) -> true|false
297 Types:
299 File = string()
301 Stores the current memory status on the file File. Returns true
303 if the emulator has been started with the "+Mis true", or "+Mim
304 true" command-line arguments, and the data was successfully
305 stored; otherwise, false. The contents of the file can later be
306 read using read_memory_status/1.
307 sum_blocks(MemoryData) -> int()
309 Types:
311 MemoryData = {term(), AllocList}
313 AllocList = [Desc]
314 Desc = {int(), int(), int(), PidDesc}
315 PidDesc = {int(), int(), int()} | undefined
316 Returns the total size of the memory blocks in the list.
318 type_descr(MemoryData, TypeNo) -> TypeDescr | invalid_type
320 Types:
322 MemoryData = {term(), AllocList}
324 AllocList = [Desc]
325 Desc = {int(), int(), int(), PidDesc}
326 PidDesc = {int(), int(), int()} | undefined
327 TypeNo = int()
328 TypeDescr = atom() | string()
329 Returns the type description of a type number used in Memory‐
331 Data. Valid TypeNos are in the range returned by type_no_range/1
332 on this specific memory allocation map. If TypeNo is an invalid
333 integer, invalid_type is returned.
334 type_no_range(MemoryData) -> {Min, Max}
336 Types:
338 MemoryData = {term(), AllocList}
340 AllocList = [Desc]
341 Desc = {int(), int(), int(), PidDesc}
342 PidDesc = {int(), int(), int()} | undefined
343 Min = int()
344 Max = int()
345 Returns the memory block type number range used in MemoryData.
347 When the memory allocation map was generated by an Erlang
348 5.3/OTP R9C or newer emulator, all integers T that satisfy Min
349 <= T <= Max are valid type numbers. When the memory allocation
350 map was generated by a pre Erlang 5.3/OTP R9C emulator, all
351 integers in the range are not valid type numbers.
352
354 erts_alloc(3), erl(1)
355Ericsson AB tools 2.11.2.1 instrument(3)