Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all 
NAME
instrument - Analysis and Utility Functions for Instrumentation
DESCRIPTION
The module instrument contains support for studying the resource usage in an Erlang
runtime system. Currently, only the allocation of memory can be studied.
Note:
Note that this whole module is experimental, and the representations used as well as the
functionality is likely to change in the future.
The instrument module interface was slightly changed in Erlang/OTP R9C.
To start an Erlang runtime system with instrumentation, use the +Mi* set of command-line
arguments to the erl command (see the erts_alloc(3erl) and erl(1) man pages).
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
{TypeNo, Address, Size, PidDesc}
where TypeNo is the memory block type number, Address is its place in memory, and Size is
its size, in bytes. PidDesc is either a tuple {X,Y,Z} identifying the process which was
executing when the block was allocated, or undefined if no process was executing. The pid
tuple {X,Y,Z} can be transformed into a real pid by usage of the c:pid/3 function.
Various details about memory allocation:
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., ps or top. The Solaris utility pmap can be
useful. It reports currently mapped memory segments.
Overhead for instrumentation: When the emulator has been started with the "+Mim true"
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 "+Mis true"
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 block_header_size/1 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.
Sizes presented by the instrumentation functionality are (by the emulator) requested
sizes, i.e. neither instrumentation headers nor headers used by allocators are included.
EXPORTS
allocator_descr(MemoryData, TypeNo) -> AllocDescr | invalid_type | "unknown"
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
TypeNo = int()
AllocDescr = atom() | string()
Returns the allocator description of the allocator that manages memory blocks of
type number TypeNo used in MemoryData. Valid TypeNos are in the range returned by
type_no_range/1 on this specific memory allocation map. If TypeNo is an invalid
integer, invalid_type is returned.
block_header_size(MemoryData) -> int()
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
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.
class_descr(MemoryData, TypeNo) -> ClassDescr | invalid_type | "unknown"
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
TypeNo = int()
ClassDescr = atom() | string()
Returns the class description of the class that the type number TypeNo used in
MemoryData belongs to. Valid TypeNos are in the range returned by type_no_range/1
on this specific memory allocation map. If TypeNo is an invalid integer,
invalid_type is returned.
descr(MemoryData) -> DescrMemoryData
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
DescrMemoryData = {term(), DescrAllocList}
DescrAllocList = [DescrDesc]
DescrDesc = {TypeDescr, int(), int(), DescrPidDesc}
TypeDescr = atom() | string()
DescrPidDesc = pid() | undefined
Returns a memory allocation map where the type numbers (first element of Desc) have
been replaced by type descriptions, and pid tuples (fourth element of Desc) have
been replaced by real pids.
holes(MemoryData) -> ok
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
Prints out the size of each hole (i.e., the space between allocated blocks) on the
terminal. NOTE: Really large holes are probably holes between memory segments. The
memory allocation map has to be sorted (see sort/1).
mem_limits(MemoryData) -> {Low, High}
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
Low = High = int()
Returns a tuple {Low, High} indicating the lowest and highest address used. The
memory allocation map has to be sorted (see sort/1).
memory_data() -> MemoryData | false
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
Returns MemoryData (a the memory allocation map) if the emulator has been started
with the "+Mim true" command-line argument; otherwise, false. NOTE:memory_data/0
blocks execution of other processes while the data is collected. The time it takes
to collect the data can be substantial.
memory_status(StatusType) -> [StatusInfo] | false
Types:
StatusType = total | allocators | classes | types
StatusInfo = {About, [Info]}
About = atom()
Info = {InfoName, Current, MaxSinceLast, MaxEver}
InfoName = sizes|blocks
Current = int()
MaxSinceLast = int()
MaxEver = int()
Returns a list of StatusInfo if the emulator has been started with the "+Mis true"
or "+Mim true" command-line argument; otherwise, false.
See the read_memory_status/1 function for a description of the StatusInfo term.
read_memory_data(File) -> MemoryData | {error, Reason}
Types:
File = string()
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
Reads a memory allocation map from the file File and returns it. The file is
assumed to have been created by store_memory_data/1. The error codes are the same
as for file:consult/1.
read_memory_status(File) -> MemoryStatus | {error, Reason}
Types:
File = string()
MemoryStatus = [{StatusType, [StatusInfo]}]
StatusType = total | allocators | classes | types
StatusInfo = {About, [Info]}
About = atom()
Info = {InfoName, Current, MaxSinceLast, MaxEver}
InfoName = sizes|blocks
Current = int()
MaxSinceLast = int()
MaxEver = int()
Reads memory allocation status from the file File and returns it. The file is
assumed to have been created by store_memory_status/1. The error codes are the same
as for file:consult/1.
When StatusType is allocators, About is the allocator that the information is
about. When StatusType is types, About 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 StatusType is classes, About is the memory
block type class that information is presented about. Memory block types are
classified after their use. Currently the following classes exist:
process_data:
Erlang process specific data.
binary_data:
Erlang binaries.
atom_data:
Erlang atoms.
code_data:
Erlang code.
system_data:
Other data used by the system
When InfoName is sizes, Current, MaxSinceLast, and MaxEver are, respectively,
current size, maximum size since last call to store_memory_status/1 or
memory_status/1 with the specific StatusType, and maximum size since the emulator
was started. When InfoName is blocks, Current, MaxSinceLast, and MaxEver are,
respectively, current number of blocks, maximum number of blocks since last call to
store_memory_status/1 or memory_status/1 with the specific StatusType, and maximum
number of blocks since the emulator was started.
NOTE:A memory block is accounted for at "the first level" allocator. E.g. fix_alloc
allocates its memory pools via ll_alloc. When a fix_alloc block is allocated,
neither the block nor the pool in which it resides are accounted for as memory
allocated via ll_alloc even though it is.
sort(MemoryData) -> MemoryData
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
Sorts a memory allocation map so that the addresses are in ascending order.
store_memory_data(File) -> true|false
Types:
File = string()
Stores the current memory allocation map on the file File. Returns true if the
emulator has been started with the "+Mim true" command-line argument, and the map
was successfully stored; otherwise, false. The contents of the file can later be
read using read_memory_data/1. NOTE:store_memory_data/0 blocks execution of other
processes while the data is collected. The time it takes to collect the data can be
substantial.
store_memory_status(File) -> true|false
Types:
File = string()
Stores the current memory status on the file File. Returns true if the emulator has
been started with the "+Mis true", or "+Mim true" command-line arguments, and the
data was successfully stored; otherwise, false. The contents of the file can later
be read using read_memory_status/1.
sum_blocks(MemoryData) -> int()
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
Returns the total size of the memory blocks in the list.
type_descr(MemoryData, TypeNo) -> TypeDescr | invalid_type
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
TypeNo = int()
TypeDescr = atom() | string()
Returns the type description of a type number used in MemoryData. Valid TypeNos are
in the range returned by type_no_range/1 on this specific memory allocation map. If
TypeNo is an invalid integer, invalid_type is returned.
type_no_range(MemoryData) -> {Min, Max}
Types:
MemoryData = {term(), AllocList}
AllocList = [Desc]
Desc = {int(), int(), int(), PidDesc}
PidDesc = {int(), int(), int()} | undefined
Min = int()
Max = int()
Returns the memory block type number range used in MemoryData. When the memory
allocation map was generated by an Erlang 5.3/OTP R9C or newer emulator, all
integers T that satisfy Min <= T <= Max 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 not valid type numbers.
SEE ALSO
erts_alloc(3erl), erl(1)