msacc(3erl) Erlang Module Definition msacc(3erl)
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.15 msacc(3erl)