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

FreeBSD Manual Pages

  
 
  

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

NAME
       msacc - Convenience functions for microstate accounting

DESCRIPTION
       This  module  implements	 some  convenience functions for analyzing mi-
       crostate	accounting data. For details about how to use  the  basic  api
       and  what  the  different  states  represent see	 erlang:statistics(mi-
       crostate_accounting).

       Basic Scenario

       1> msacc:start(1000).
       ok
       2> msacc:print().
       Average thread real-time	   : 1000513 us
       Accumulated system run-time :	2213 us
       Average scheduler run-time  :	1076 us

	       Thread	   aux check_io	emulator       gc    other     port    sleep

       Stats per thread:
	    async( 0)	 0.00%	  0.00%	   0.00%    0.00%    0.00%    0.00%  100.00%
	    async( 1)	 0.00%	  0.00%	   0.00%    0.00%    0.00%    0.00%  100.00%
	      aux( 1)	 0.00%	  0.00%	   0.00%    0.00%    0.00%    0.00%   99.99%
	scheduler( 1)	 0.00%	  0.03%	   0.13%    0.00%    0.01%    0.00%   99.82%
	scheduler( 2)	 0.00%	  0.00%	   0.00%    0.00%    0.03%    0.00%   99.97%

       Stats per type:
		async	 0.00%	  0.00%	   0.00%    0.00%    0.00%    0.00%  100.00%
		  aux	 0.00%	  0.00%	   0.00%    0.00%    0.00%    0.00%   99.99%
	    scheduler	 0.00%	  0.02%	   0.06%    0.00%    0.02%    0.00%   99.89%
       ok

       This first command enables microstate accounting	for 1000 milliseconds.
       See  start/0,  stop/0, reset/0 and start/1 for more details. The	second
       command prints the statistics gathered during that  time.  First	 three
       general statistics are printed.

	 Average real-time:
	   The	average	time spent collecting data in the threads. This	should
	   be close to the time	which data was collected.

	 System	run-time:
	   The total run-time of all threads in	the system. This is  what  you
	   get if you call msacc:stats(total_runtime,Stats).

	 Average scheduler run-time:
	   The average run-time	for the	schedulers. This is the	average	amount
	   of time the schedulers did not sleep.

       Then one	column per state is printed with a the percentage of time this
       thread  spent  in the state out of it's own real-time. After the	thread
       specific	time, the accumulated time for each type of thread is  printed
       in a similar format.

       Since  we  have	the average real-time and the percentage spent in each
       state we	can easily calculate the time spent in each state by multiply-
       ing  Average thread real-time with Thread state %, i.e. to get the time
       Scheduler 1 spent in the	emulator state	we  do	1000513us  *  0.13%  =
       1300us.

DATA TYPES
       msacc_data() = [msacc_data_thread()]

       msacc_data_thread() =
	   #{'$type' :=	msacc_data,
	     type := msacc_type(),
	     id	:= msacc_id(),
	     counters := msacc_data_counters()}

       msacc_data_counters() = #{msacc_state() => integer() >= 0}

	      A	 map containing	the different microstate accounting states and
	      the number of microseconds spent in it.

       msacc_stats() = [msacc_stats_thread()]

       msacc_stats_thread() =
	   #{'$type' :=	msacc_stats,
	     type := msacc_type(),
	     id	:= msacc_id(),
	     system := float(),
	     counters := msacc_stats_counters()}

	      A	map containing information about a specific thread.  The  per-
	      centages	in the map can be either run-time or real-time depend-
	      ing on if	runtime	or realtime was	requested from stats/2.	system
	      is the percentage	of total system	time for this specific thread.

       msacc_stats_counters() =
	   #{msacc_state() => #{thread := float(), system := float()}}

	      A	 map  containing  the  different microstate accounting states.
	      Each value in the	map contains another map with  the  percentage
	      of  time	that this thread has spent in the specific state. Both
	      the percentage of	system time and	the  time  for	that  specific
	      thread is	part of	the map.

       msacc_type() =
	   aux |
	   async |
	   dirty_cpu_scheduler |
	   dirty_io_scheduler |
	   poll	|
	   scheduler

       msacc_id() = integer() >= 0

       msacc_state() =
	   alloc |
	   aux |
	   bif |
	   busy_wait |
	   check_io |
	   emulator |
	   ets |
	   gc |
	   gc_fullsweep	|
	   nif |
	   other |
	   port	|
	   send	|
	   sleep |
	   timers

	      The  different  states that a thread can be in. See  erlang:sta-
	      tistics(microstate_accounting) for details.

       msacc_print_options() = #{system	=> boolean()}

	      The different options that can be	given to print/2.

EXPORTS
       available() -> boolean()

	      This function checks whether microstate accounting is  available
	      or not.

       start() -> boolean()

	      Start  microstate	 accounting. Returns whether it	was previously
	      enabled or disabled.

       start(Time) -> true

	      Types:

		 Time =	timeout()

	      Resets all counters and then starts  microstate  accounting  for
	      the given	milliseconds.

       stop() -> boolean()

	      Stop  microstate	accounting.  Returns whether is	was previously
	      enabled or disabled.

       reset() -> boolean()

	      Reset microstate accounting counters. Returns whether is was en-
	      abled or disabled.

       print() -> ok

	      Prints  the  current microstate accounting to standard out. Same
	      as msacc:print(msacc:stats(),#{}).

       print(DataOrStats) -> ok

	      Types:

		 DataOrStats = msacc_data() | msacc_stats()

	      Print the	given microstate statistics values to stdout. Same  as
	      msacc:print(DataOrStats,#{}).

       print(DataOrStats, Options) -> ok

	      Types:

		 DataOrStats = msacc_data() | msacc_stats()
		 Options = msacc_print_options()

	      Print  the  given	 microstate statistics values to standard out.
	      With many	states this can	be quite verbose. See the top of  this
	      reference	 manual	 for  a	 brief	description of what the	fields
	      mean.

	      It is possible to	print more specific  types  of	statistics  by
	      first  manipulating  the DataOrStats using stats/2. For instance
	      if you want to print the percentage of run-time for each	thread
	      you can do:

	      msacc:print(msacc:stats(runtime,msacc:stats())).

	      If you want to only print	run-time per thread type you can do:

	      msacc:print(msacc:stats(type,msacc:stats(runtime,msacc:stats()))).

	      Options

		system:
		  Print	 percentage  of	time spent in each state out of	system
		  time as well as thread time. Default:	false.

       print(FileOrDevice, DataOrStats,	Options) -> ok

	      Types:

		 FileOrDevice =	file:filename()	| io:device()
		 DataOrStats = msacc_data() | msacc_stats()
		 Options = msacc_print_options()

	      Print the	given microstate statistics values to the  given  file
	      or  device.  The	other  arguments  behave  the  same way	as for
	      print/2.

       stats() -> msacc_data()

	      Returns a	runtime	system independent version of  the  microstate
	      statistics  data	presented  by erlang:statistics(microstate_ac-
	      counting). All counters have been	normalized to be in  microsec-
	      ond resolution.

       stats(Analysis, Stats) -> integer() >= 0

	      Types:

		 Analysis = system_realtime | system_runtime
		 Stats = msacc_data()

	      Returns the system time for the given microstate statistics val-
	      ues. System time is the accumulated time of all threads.

		realtime:
		  Returns all time recorded for	all threads.

		runtime:
		  Returns all time spent doing work for	all threads, i.e.  all
		  time not spent in the	sleep state.

       stats(Analysis, Stats) -> msacc_stats()

	      Types:

		 Analysis = realtime | runtime
		 Stats = msacc_data()

	      Returns  fractions of real-time or run-time spent	in the various
	      threads from the given microstate	statistics values.

       stats(Analysis, StatsOrData) -> msacc_data() | msacc_stats()

	      Types:

		 Analysis = type
		 StatsOrData = msacc_data() | msacc_stats()

	      Returns a	list of	microstate statistics values where the	values
	      for all threads of the same type has been	merged.

       to_file(Filename) -> ok | {error, file:posix()}

	      Types:

		 Filename = file:name_all()

	      Dumps  the current microstate statistics counters	to a file that
	      can be parsed with  file:consult/1.

       from_file(Filename) -> msacc_data()

	      Types:

		 Filename = file:name_all()

	      Read a file dump produced	by  to_file(Filename).

Ericsson AB		     runtime_tools 1.13.2		      msacc(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS

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

home | help