Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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)