summaryrefslogtreecommitdiff
path: root/lib/tools/doc/src/instrument.xml
blob: b7e48ea3063dca92c2a68b259073da1944dee618 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1998</year><year>2011</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      The contents of this file are subject to the Erlang Public License,
      Version 1.1, (the "License"); you may not use this file except in
      compliance with the License. You should have received a copy of the
      Erlang Public License along with this software. If not, it can be
      retrieved online at http://www.erlang.org/.
    
      Software distributed under the License is distributed on an "AS IS"
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
      the License for the specific language governing rights 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>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>Note that this whole module is experimental, and the representations
        used as well as the functionality is likely to change in the future.</p>
      <p>The <c>instrument</c> module interface was slightly changed in
        Erlang/OTP R9C.</p>
    </note>
    <p>To start an Erlang runtime system with instrumentation, use the
      <c>+Mi*</c> set of command-line arguments to the <c>erl</c> command (see
      the erts_alloc(3) and erl(1) man pages).</p>
    <p>The basic object of study in the case of memory allocation is a memory
      allocation map. A memory allocation map contains a list of descriptors
      for each allocated memory block. Currently, a descriptor is a 4-tuple</p>
    <pre>
        {TypeNo, Address, Size, PidDesc}    </pre>
    <p>where <c>TypeNo</c> is the memory block type number, <c>Address</c>
      is its place in memory, and <c>Size</c> is its size, in bytes.
      <c>PidDesc</c> is either a tuple <c>{X,Y,Z}</c> identifying the
      process which was executing when the block was allocated, or
      <c>undefined</c> if no process was executing. The pid tuple
      <c>{X,Y,Z}</c> can be transformed into a real pid by usage of the
      <c>c:pid/3</c> function.</p>
    <p>Various details about memory allocation:</p>
    <p>Memory blocks are allocated both on the heap segment and on other memory
      segments. This can cause the instrumentation functionality to report
      very large holes. Currently the instrumentation functionality doesn't
      provide any support for distinguishing between holes between memory
      segments, and holes between allocated blocks inside memory segments.
      The current size of the process cannot be obtained from within Erlang,
      but can be seen with one of the system statistics tools, e.g.,
      <c>ps</c> or <c>top</c>. The Solaris utility <c>pmap</c> can be
      useful. It reports currently mapped memory segments. </p>
    <p>Overhead for instrumentation: When the emulator has been started with
      the <seealso marker="erts:erts_alloc#Mim">"+Mim true"</seealso>
      flag, each block is preceded by a 24 bytes large
      header on a 32-bit machine and a 48 bytes large header on a 64-bit
      machine. When the emulator has been started with the
      <seealso marker="erts:erts_alloc#Mis">"+Mis true"</seealso>
      flag, each block is preceded by an 8 bytes large header. These are the header
      sizes used by the Erlang 5.3/OTP R9C emulator. Other versions of the
      emulator may use other header sizes. The function
      <seealso marker="#block_header_size/1">block_header_size/1</seealso>
      can be used for retrieving the header size used for a specific memory
      allocation map. The time overhead for managing the instrumentation
      data is small.</p>
    <p>Sizes presented by the instrumentation functionality are (by the
      emulator) requested sizes, i.e. neither instrumentation headers nor
      headers used by allocators are included.</p>
  </description>
  <funcs>
    <func>
      <name>allocator_descr(MemoryData, TypeNo) -> AllocDescr | invalid_type | "unknown"</name>
      <fsummary>Returns a allocator description</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
        <v>TypeNo = int()</v>
        <v>AllocDescr = atom() | string()</v>
      </type>
      <desc>
        <p>Returns the allocator description of the allocator that
          manages memory blocks of type number <c>TypeNo</c> used in
          <c>MemoryData</c>.
          Valid <c>TypeNo</c>s are in the range returned by
          <seealso marker="#type_no_range/1">type_no_range/1</seealso> on
          this specific memory allocation map. If <c>TypeNo</c> is an
          invalid integer, <c>invalid_type</c> is returned.</p>
      </desc>
    </func>
    <func>
      <name>block_header_size(MemoryData) -> int()</name>
      <fsummary>Returns the memory block header size used by the emulator that generated the memory allocation map</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
      </type>
      <desc>
        <marker id="block_header_size_1"></marker>
        <p>Returns the memory block header size used by the
          emulator that generated the memory allocation map. The block
          header size may differ between different emulators.</p>
      </desc>
    </func>
    <func>
      <name>class_descr(MemoryData, TypeNo) -> ClassDescr | invalid_type | "unknown"</name>
      <fsummary>Returns a allocator description</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
        <v>TypeNo = int()</v>
        <v>ClassDescr = atom() | string()</v>
      </type>
      <desc>
        <p>Returns the class description of the class that
          the type number <c>TypeNo</c> used in <c>MemoryData</c> belongs
          to.
          Valid <c>TypeNo</c>s are in the range returned by
          <seealso marker="#type_no_range/1">type_no_range/1</seealso> on
          this specific memory allocation map. If <c>TypeNo</c> is an
          invalid integer, <c>invalid_type</c> is returned.</p>
      </desc>
    </func>
    <func>
      <name>descr(MemoryData) -> DescrMemoryData</name>
      <fsummary>Replace type numbers in memory allocation map with type descriptions</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
        <v>DescrMemoryData = {term(), DescrAllocList}</v>
        <v>DescrAllocList = [DescrDesc]</v>
        <v>DescrDesc = {TypeDescr, int(), int(), DescrPidDesc}</v>
        <v>TypeDescr = atom() | string()</v>
        <v>DescrPidDesc = pid() | undefined</v>
      </type>
      <desc>
        <p>Returns a memory allocation map where the type numbers (first
          element of <c>Desc</c>) have been replaced by type descriptions,
          and pid tuples (fourth element of <c>Desc</c>) have been
          replaced by real pids.</p>
      </desc>
    </func>
    <func>
      <name>holes(MemoryData) -> ok</name>
      <fsummary>Print out the sizes of unused memory blocks</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
      </type>
      <desc>
        <p>Prints out the size of each hole (i.e., the space between
          allocated blocks) on the terminal. <em>NOTE:</em> Really large holes
          are probably holes between memory segments.
          The memory allocation map has to be sorted (see
          <seealso marker="#sort/1">sort/1</seealso>).</p>
      </desc>
    </func>
    <func>
      <name>mem_limits(MemoryData) -> {Low, High}</name>
      <fsummary>Return lowest and highest memory address used</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
        <v>Low = High = int()</v>
      </type>
      <desc>
        <p>Returns a tuple <c>{Low, High}</c> indicating
          the lowest and highest address used.
          The memory allocation map has to be sorted (see
          <seealso marker="#sort/1">sort/1</seealso>).</p>
      </desc>
    </func>
    <func>
      <name>memory_data() -> MemoryData | false</name>
      <fsummary>Return the current memory allocation map</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
      </type>
      <desc>
        <p>Returns <c>MemoryData</c> (a the memory allocation map)
          if the emulator has been started with the "<c>+Mim true</c>"
          command-line argument; otherwise, <c>false</c>. <em>NOTE:</em><c>memory_data/0</c> blocks execution of other processes while
          the data is collected. The time it takes to collect the data can
          be substantial.</p>
      </desc>
    </func>
    <func>
      <name>memory_status(StatusType) -> [StatusInfo] | false</name>
      <fsummary>Return current memory allocation status</fsummary>
      <type>
        <v>StatusType = total | allocators | classes | types</v>
        <v>StatusInfo = {About, [Info]}</v>
        <v>About = atom()</v>
        <v>Info = {InfoName, Current, MaxSinceLast, MaxEver}</v>
        <v>InfoName = sizes|blocks</v>
        <v>Current = int()</v>
        <v>MaxSinceLast = int()</v>
        <v>MaxEver = int()</v>
      </type>
      <desc>
        <p>Returns a list of <c>StatusInfo</c> if the emulator has been
          started with the "<c>+Mis true</c>" or "<c>+Mim true</c>"
          command-line argument; otherwise, <c>false</c>. </p>
        <p>See the
          <seealso marker="#read_memory_status/1">read_memory_status/1</seealso>
          function for a description of the <c>StatusInfo</c> term.</p>
      </desc>
    </func>
    <func>
      <name>read_memory_data(File) -> MemoryData | {error, Reason}</name>
      <fsummary>Read memory allocation map</fsummary>
      <type>
        <v>File = string()</v>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
      </type>
      <desc>
        <marker id="read_memory_data_1"></marker>
        <p>Reads a memory allocation map from the file <c>File</c> and
          returns it. The file is assumed to have been created by
          <c>store_memory_data/1</c>. The error codes are the same as for
          <c>file:consult/1</c>.</p>
      </desc>
    </func>
    <func>
      <name>read_memory_status(File) -> MemoryStatus | {error, Reason}</name>
      <fsummary>Read memory allocation status from a file</fsummary>
      <type>
        <v>File = string()</v>
        <v>MemoryStatus = [{StatusType, [StatusInfo]}]</v>
        <v>StatusType = total | allocators | classes | types</v>
        <v>StatusInfo = {About, [Info]}</v>
        <v>About = atom()</v>
        <v>Info = {InfoName, Current, MaxSinceLast, MaxEver}</v>
        <v>InfoName = sizes|blocks</v>
        <v>Current = int()</v>
        <v>MaxSinceLast = int()</v>
        <v>MaxEver = int()</v>
      </type>
      <desc>
        <marker id="read_memory_status_1"></marker>
        <p>Reads memory allocation status from the file <c>File</c> and
          returns it. The file is assumed to have been created by
          <c>store_memory_status/1</c>. The error codes are the same as
          for <c>file:consult/1</c>.</p>
        <p>When <c>StatusType</c> is <c>allocators</c>, <c>About</c> is
          the allocator that the information is about. When
          <c>StatusType</c> is <c>types</c>, <c>About</c> is
          the memory block type that the information is about. Memory
          block types are not described other than by their name and may
          vary between emulators. When <c>StatusType</c> is <c>classes</c>,
          <c>About</c> is the memory block type class that information is
          presented about. Memory block types are classified after their
          use. Currently the following classes exist:</p>
        <taglist>
          <tag><c>process_data</c></tag>
          <item>Erlang process specific data.</item>
          <tag><c>binary_data</c></tag>
          <item>Erlang binaries.</item>
          <tag><c>atom_data</c></tag>
          <item>Erlang atoms.</item>
          <tag><c>code_data</c></tag>
          <item>Erlang code.</item>
          <tag><c>system_data</c></tag>
          <item>Other data used by the system</item>
        </taglist>
        <p>When <c>InfoName</c> is <c>sizes</c>, <c>Current</c>,
          <c>MaxSinceLast</c>, and <c>MaxEver</c> are, respectively, current
          size, maximum size since last call to
          <c>store_memory_status/1</c> or <c>memory_status/1</c> with the
          specific <c>StatusType</c>, and maximum size since the emulator
          was started. When <c>InfoName</c> is <c>blocks</c>, <c>Current</c>,
          <c>MaxSinceLast</c>, and <c>MaxEver</c> are, respectively, current
          number of blocks, maximum number of blocks since last call to
          <c>store_memory_status/1</c> or <c>memory_status/1</c> with the
          specific <c>StatusType</c>, and maximum number of blocks since the
          emulator was started. </p>
        <p><em>NOTE:</em>A memory block is accounted for at
          "the first level" allocator. E.g. <c>fix_alloc</c> allocates its
          memory pools via <c>ll_alloc</c>. When a <c>fix_alloc</c> block
          is allocated, neither the block nor the pool in which it resides
          are accounted for as memory allocated via <c>ll_alloc</c> even
          though it is.</p>
      </desc>
    </func>
    <func>
      <name>sort(MemoryData) -> MemoryData</name>
      <fsummary>Sort the memory allocation list</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
      </type>
      <desc>
        <marker id="sort_1"></marker>
        <p>Sorts a memory allocation map so that the addresses are in
          ascending order.</p>
      </desc>
    </func>
    <func>
      <name>store_memory_data(File) -> true|false</name>
      <fsummary>Store the current memory allocation map on a file</fsummary>
      <type>
        <v>File = string()</v>
      </type>
      <desc>
        <p>Stores the current memory allocation map on the file
          <c>File</c>. Returns <c>true</c> if the emulator has been
          started with the "<c>+Mim true</c>" command-line argument, and
          the map was successfully stored; otherwise, <c>false</c>. The
          contents of the file can later be read using
          <seealso marker="#read_memory_data/1">read_memory_data/1</seealso>.
          <em>NOTE:</em><c>store_memory_data/0</c> blocks execution of
          other processes while the data is collected. The time it takes
          to collect the data can be substantial.</p>
      </desc>
    </func>
    <func>
      <name>store_memory_status(File) -> true|false</name>
      <fsummary>Store the current memory allocation status on a file</fsummary>
      <type>
        <v>File = string()</v>
      </type>
      <desc>
        <p>Stores the current memory status on the file
          <c>File</c>. Returns <c>true</c> if the emulator has been
          started with the "<c>+Mis true</c>", or "<c>+Mim true</c>"
          command-line arguments, and the data was successfully stored;
          otherwise, <c>false</c>. The contents of the file can later be
          read using
          <seealso marker="#read_memory_status/1">read_memory_status/1</seealso>.</p>
      </desc>
    </func>
    <func>
      <name>sum_blocks(MemoryData) -> int()</name>
      <fsummary>Return the total amount of memory used</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
      </type>
      <desc>
        <p>Returns the total size of the memory blocks in the list.</p>
      </desc>
    </func>
    <func>
      <name>type_descr(MemoryData, TypeNo) -> TypeDescr | invalid_type</name>
      <fsummary>Returns a type description</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
        <v>TypeNo = int()</v>
        <v>TypeDescr = atom() | string()</v>
      </type>
      <desc>
        <p>Returns the type description of a type number used in
          <c>MemoryData</c>.
          Valid <c>TypeNo</c>s are in the range returned by
          <seealso marker="#type_no_range/1">type_no_range/1</seealso> on
          this specific memory allocation map. If <c>TypeNo</c> is an
          invalid integer, <c>invalid_type</c> is returned.</p>
      </desc>
    </func>
    <func>
      <name>type_no_range(MemoryData) -> {Min, Max}</name>
      <fsummary>Returns the memory block type numbers</fsummary>
      <type>
        <v>MemoryData = {term(), AllocList}</v>
        <v>AllocList = [Desc]</v>
        <v>Desc = {int(), int(), int(), PidDesc}</v>
        <v>PidDesc = {int(), int(), int()} | undefined</v>
        <v>Min = int()</v>
        <v>Max = int()</v>
      </type>
      <desc>
        <marker id="type_no_range_1"></marker>
        <p>Returns the memory block type number range used in
          <c>MemoryData</c>. When the memory allocation map was generated
          by an Erlang 5.3/OTP R9C or newer emulator, all integers <c>T</c>
          that satisfy <c>Min</c> &lt;= <c>T</c> &lt;= <c>Max</c> are
          valid type numbers. When the memory allocation map was generated
          by a pre Erlang 5.3/OTP R9C emulator, all integers in the
          range are <em>not</em> valid type numbers.</p>
      </desc>
    </func>
  </funcs>

  <section>
    <title>See Also</title>
    <p><seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>,
      <seealso marker="erts:erl">erl(1)</seealso></p>
  </section>
</erlref>