<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1998</year><year>2013</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örn Johnsson</responsible> <docno>1</docno> <approved>Bjö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> <= <c>T</c> <= <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>