Microstate Accounting

msacc

msacc
Convenience functions for microstate accounting
Module msacc was introduced in OTP 19.0.

This module implements some convenience functions for analyzing microstate accounting data. For details about how to use the basic api and what the different states represent see erlang:statistics(microstate_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 multiplying 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.

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

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.

This function checks whether microstate accounting is available or not.

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

Types

Time = timeout()

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

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

Reset microstate accounting counters. Returns whether is was enabled or disabled.

Types

DataOrStats = msacc_data() | msacc_stats()

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.

Types

Analysis = system_realtime | system_runtime
Stats = msacc_data()

Returns the system time for the given microstate statistics values. 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.

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.