Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
instrument(3)		   Erlang Module Definition		 instrument(3)

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.

DATA TYPES
       block_histogram() = tuple()

	      A	histogram of block sizes where each interval's upper bound  is
	      twice as high as the one before it.

	      The  upper  bound	of the first interval is provided by the func-
	      tion that	returned the histogram,	and the	last interval  has  no
	      upper bound.

       allocation_summary() =
	   {HistogramStart :: integer()	>= 0,
	    UnscannedSize :: integer() >= 0,
	    Allocations	::
		#{Origin :: atom() =>
		      #{Type ::	atom() => block_histogram()}}}

	      A	 summary  of  allocated	 block sizes (including	their headers)
	      grouped by their Origin and Type.

	      Origin is	generally which	 NIF  or  driver  that	allocated  the
	      blocks, or 'system' if it	could not be determined.

	      Type  is the allocation category that the	blocks belong to, e.g.
	      db_term, message or binary.

	      If one or	more carriers could not	be  scanned  in	 full  without
	      harming  the  responsiveness of the system, UnscannedSize	is the
	      number of	bytes that had to be skipped.

       carrier_info_list() =
	   {HistogramStart :: integer()	>= 0,
	    Carriers ::
		[{AllocatorType	:: atom(),
		  TotalSize :: integer() >= 0,
		  UnscannedSize	:: integer() >=	0,
		  AllocatedSize	:: integer() >=	0,
		  AllocatedCount :: integer() >= 0,
		  InPool :: boolean(),
		  FreeBlocks ::	block_histogram()}]}

	      AllocatorType is the type	of the	allocator  that	 employs  this
	      carrier.

	      TotalSize	 is  the  total	 size  of  the	carrier, including its
	      header.

	      AllocatedSize is the combined size of  the  carrier's  allocated
	      blocks, including	their headers.

	      AllocatedCount is	the number of allocated	blocks in the carrier.

	      InPool is	whether	the carrier is in the migration	pool.

	      FreeBlocks  is  a	 histogram of the free block sizes in the car-
	      rier.

	      If the carrier could not be scanned in full without harming  the
	      responsiveness  of  the  system,	UnscannedSize is the number of
	      bytes that had to	be skipped.

EXPORTS
       allocations() ->	{ok, Result} | {error, Reason}

	      Types:

		 Result	= allocation_summary()
		 Reason	= not_enabled

	      Shorthand	for allocations(#{}).

       allocations(Options) -> {ok, Result} | {error, Reason}

	      Types:

		 Result	= allocation_summary()
		 Reason	= not_enabled
		 Options =
		     #{scheduler_ids =>	[integer() >= 0],
		       allocator_types => [atom()],
		       histogram_start => integer() >= 1,
		       histogram_width => integer() >= 1}

	      Returns a	summary	of all tagged allocations in the  system,  op-
	      tionally filtered	by allocator type and scheduler	id.

	      Only  binaries  and  allocations	made  by  NIFs and drivers are
	      tagged by	default, but this can be configured an a per-allocator
	      basis with the +M_S_atags	emulator option.

	      If  tagged  allocations  are not enabled on any of the specified
	      allocator	types, the call	will fail with {error, not_enabled}.

	      The following options can	be used:

		allocator_types:
		  The allocator	types that will	be searched. Defaults  to  all
		  alloc_util allocators.

		scheduler_ids:
		  The	scheduler   ids	 whose	allocator  instances  will  be
		  searched. A scheduler	id of 0	will refer to the  global  in-
		  stance  that	is  not	 tied to any particular	scheduler. De-
		  faults to all	schedulers and the global instance.

		histogram_start:
		  The upper bound of the first interval	in the allocated block
		  size histograms. Defaults to 128.

		histogram_width:
		  The  number  of  intervals  in the allocated block size his-
		  tograms. Defaults to 18.

	      Example:

	      >	instrument:allocations(#{ histogram_start => 128, histogram_width => 15	}).
	      {ok,{128,0,
		   #{udp_inet =>
			 #{driver_event_state => {0,0,0,0,0,0,0,0,0,1,0,0,0,0,0}},
		     system =>
			 #{heap	=> {0,0,0,0,20,4,2,2,2,3,0,1,0,0,1},
			   db_term => {271,3,1,52,80,1,0,0,0,0,0,0,0,0,0},
			   code	=> {0,0,0,5,3,6,11,22,19,20,10,2,1,0,0},
			   binary => {18,0,0,0,7,0,0,1,0,0,0,0,0,0,0},
			   message => {0,40,78,2,2,0,0,0,0,0,0,0,0,0,0},
			   ... }
		     spawn_forker =>
			 #{driver_select_data_state =>
			       {1,0,0,0,0,0,0,0,0,0,0,0,0,0,0}},
		     ram_file_drv => #{drv_binary => {0,0,0,0,0,0,1,0,0,0,0,0,0,0,0}},
		     prim_file =>
			 #{process_specific_data => {2,0,0,0,0,0,0,0,0,0,0,0,0,0,0},
			   nif_trap_export_entry => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
			   monitor_extended => {0,1,0,0,0,0,0,0,0,0,0,0,0,0,0},
			   drv_binary => {0,0,0,0,0,0,1,0,3,5,0,0,0,1,0},
			   binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}},
		     prim_buffer =>
			 #{nif_internal	=> {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0},
			   binary => {0,4,0,0,0,0,0,0,0,0,0,0,0,0,0}}}}}

       carriers() -> {ok, Result} | {error, Reason}

	      Types:

		 Result	= carrier_info_list()
		 Reason	= not_enabled

	      Shorthand	for carriers(#{}).

       carriers(Options) -> {ok, Result} | {error, Reason}

	      Types:

		 Result	= carrier_info_list()
		 Reason	= not_enabled
		 Options =
		     #{scheduler_ids =>	[integer() >= 0],
		       allocator_types => [atom()],
		       histogram_start => integer() >= 1,
		       histogram_width => integer() >= 1}

	      Returns a	summary	of all carriers	in the system, optionally fil-
	      tered by allocator type and scheduler id.

	      If  the specified	allocator types	are not	enabled, the call will
	      fail with	{error,	not_enabled}.

	      The following options can	be used:

		allocator_types:
		  The allocator	types that will	be searched. Defaults  to  all
		  alloc_util allocators.

		scheduler_ids:
		  The	scheduler   ids	 whose	allocator  instances  will  be
		  searched. A scheduler	id of 0	will refer to the  global  in-
		  stance  that	is  not	 tied to any particular	scheduler. De-
		  faults to all	schedulers and the global instance.

		histogram_start:
		  The upper bound of the first interval	in the free block size
		  histograms. Defaults to 512.

		histogram_width:
		  The  number  of intervals in the free	block size histograms.
		  Defaults to 14.

	      Example:

	      >	instrument:carriers(#{ histogram_start => 512, histogram_width => 8 }).
	      {ok,{512,
		   [{ll_alloc,1048576,0,1048344,71,false,{0,0,0,0,0,0,0,0}},
		    {binary_alloc,1048576,0,324640,13,false,{3,0,0,1,0,0,0,2}},
		    {eheap_alloc,2097152,0,1037200,45,false,{2,1,1,3,4,3,2,2}},
		    {fix_alloc,32768,0,29544,82,false,{22,0,0,0,0,0,0,0}},
		    {...}|...]}}

SEE ALSO
       erts_alloc(3), erl(1)

Ericsson AB			   tools 3.1			 instrument(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=instrument&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help