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:

        {TypeNo, Address, Size, PidDesc}

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.

erts_alloc(3), erl(1)

Arndt Jonasson - support@erlang.ericsson.se
Rickard Green - support@erlang.ericsson.se