instrument(3)

MODULE
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.

Some of the functions in this module are only available in Erlang compiled with instrumentation; otherwise they exit with badarg. This is noted below for the individual functions. To start an Erlang runtime system with instrumentation, use the command-line option -instr to the erl command.

The basic object of study in the case of memory allocation is a memory allocation list, which contains one descriptor for each allocated memory block. Currently, a descriptor is a 4-tuple
        {Type, Address, Size, Pid}

where Type indicates what the block is used for, Address is its place in memory, and Size is its size, in bytes.Pid is either undefined (if the block was allocated by the runtime system itself) or a tuple {A, B, C} representing the process which allocated the block, which corresponds to a pid with the user-visible representation <A.B.C> (the function c:pid/3 can be used to transform the numbers to a real pid).

Various details about memory allocation:

On Unix (for example, Solaris), memory for a process is allocated linearly, usually from 0. 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. (There may be a hole above the highest used memory block; in that case the functions in theinstrument module cannot tell you about it; you have to compare the High value from mem_limits/1 with the value which the system reports for Erlang.)

In the memory allocation list, certain small objects do not show up individually, since they are allocated from blocks of 20 objects (called "fixalloc" blocks). The blocks themselves do show up, but the amount of internal fragmentation in them currently cannot be observed.

Overhead for instrumentation: instrumented memory allocation uses 28 bytes extra for each block. The time overhead for managing the list is negligible.

EXPORTS

holes(AllocList) -> ok

    Types
        AllocList = [Desc]
        Desc = {int(), int(), int(), pid_tuple()}
        pid_tuple() = {int(), int(), int()}

    Prints out the size of each hole (i.e., the space between allocated blocks) on the terminal. The list must be sorted (see sort/1).

mem_limits(AllocList) -> {Low, High}

    Types
        AllocList = [Desc]
        Desc = {int(), int(), int(), pid_tuple()}
        pid_tuple() = {int(), int(), int()}
        Low = High = int()

    returns a tuple {Low, High} indicating the lowest and highest address used. The list must be sorted (see sort/1).

memory_data() -> AllocList

    Types
        AllocList = [Desc]
        Desc = {int(), int(), int(), pid_tuple()}
        pid_tuple() = {int(), int(), int()}

    Returns the memory allocation list. Only available in an Erlang runtime system compiled for instrumentation. Blocks execution of other processes while the list is collected.

read_memory_data(File) -> {ok, AllocList} | {error, Reason}

    Types
        File = string()
        AllocList = [Desc]
        Desc = {int(), int(), int(), pid_tuple()}
        pid_tuple() = {int(), int(), int()}

    Reads a memory allocation list from the file File. The file is assumed to have been created by store_memory_data/1. The error codes are the same as for file:consult/1.

sort(AllocList) -> AllocList

    Types
        AllocList = [Desc]
        Desc = {int(), int(), int(), pid_tuple()}
        pid_tuple() = {int(), int(), int()}

    Sorts a memory allocation list so the addresses are in ascending order. The list arguments to many of the functions in this module must be sorted. No other function in this module returns a sorted list.

store_memory_data(File) -> ok

    Types
        File = string()

    Stores the memory allocation list on the file File. The contents of the file can later be read using read_memory_data/1. Only available in an Erlang runtime system compiled for instrumentation. Blocks execution of other processes while the list is collected (the time to write the data is around 0.1 ms/line on a Sun Ultra 1).

    Failure: badarg if the file could not be written.

sum_blocks(AllocList) -> int()

    Types
        AllocList = [Desc]
        Desc = {int(), int(), int(), pid_tuple()}
        pid_tuple() = {int(), int(), int()}

    Returns the total size of the memory blocks in the list. The list must be sorted (see sort/1).

type_string(Type) -> string()

    Types
        Type = int()

    Translates a memory block type number into a readable string, which is a short description of the block type.

    Failure: badarg if the argument is not a valid block type number.

AUTHOR
Arndt Jonasson - support@erlang.ericsson.se