instrument
Analysis and Utility Functions for Instrumentation
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(3) 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.
Functions
allocator_descr(MemoryData, TypeNo) -> AllocDescr | invalid_type | "unknown"
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 TypeNo
s 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()
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"
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 TypeNo
s 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
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
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}
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
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
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}
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}
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
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
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 successfuly 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
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 successfuly stored;
otherwise, false
. The contents of the file can later be
read using
read_memory_status/1.
sum_blocks(MemoryData) -> int()
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
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 TypeNo
s 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}
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.