1msacc(3)                   Erlang Module Definition                   msacc(3)
2
3
4

NAME

6       msacc - Convenience functions for microstate accounting
7

DESCRIPTION

9       This  module  implements  some  convenience functions for analyzing mi‐
10       crostate accounting data. For details about how to use  the  basic  api
11       and  what  the  different  states  represent see  erlang:statistics(mi‐
12       crostate_accounting).
13
14       Basic Scenario
15
16       1> msacc:start(1000).
17       ok
18       2> msacc:print().
19       Average thread real-time    : 1000513 us
20       Accumulated system run-time :    2213 us
21       Average scheduler run-time  :    1076 us
22
23               Thread      aux check_io emulator       gc    other     port    sleep
24
25       Stats per thread:
26            async( 0)    0.00%    0.00%    0.00%    0.00%    0.00%    0.00%  100.00%
27            async( 1)    0.00%    0.00%    0.00%    0.00%    0.00%    0.00%  100.00%
28              aux( 1)    0.00%    0.00%    0.00%    0.00%    0.00%    0.00%   99.99%
29        scheduler( 1)    0.00%    0.03%    0.13%    0.00%    0.01%    0.00%   99.82%
30        scheduler( 2)    0.00%    0.00%    0.00%    0.00%    0.03%    0.00%   99.97%
31
32       Stats per type:
33                async    0.00%    0.00%    0.00%    0.00%    0.00%    0.00%  100.00%
34                  aux    0.00%    0.00%    0.00%    0.00%    0.00%    0.00%   99.99%
35            scheduler    0.00%    0.02%    0.06%    0.00%    0.02%    0.00%   99.89%
36       ok
37
38
39       This first command enables microstate accounting for 1000 milliseconds.
40       See  start/0,  stop/0, reset/0 and start/1 for more details. The second
41       command prints the statistics gathered during that  time.  First  three
42       general statistics are printed.
43
44         Average real-time:
45           The  average time spent collecting data in the threads. This should
46           be close to the time which data was collected.
47
48         System run-time:
49           The total run-time of all threads in the system. This is  what  you
50           get if you call msacc:stats(total_runtime,Stats).
51
52         Average scheduler run-time:
53           The average run-time for the schedulers. This is the average amount
54           of time the schedulers did not sleep.
55
56       Then one column per state is printed with a the percentage of time this
57       thread  spent  in the state out of it's own real-time. After the thread
58       specific time, the accumulated time for each type of thread is  printed
59       in a similar format.
60
61       Since  we  have  the average real-time and the percentage spent in each
62       state we can easily calculate the time spent in each state by multiply‐
63       ing  Average thread real-time with Thread state %, i.e. to get the time
64       Scheduler 1 spent in the emulator state  we  do  1000513us  *  0.13%  =
65       1300us.
66

DATA TYPES

68       msacc_data() = [msacc_data_thread()]
69
70       msacc_data_thread() =
71           #{'$type' := msacc_data,
72             type := msacc_type(),
73             id := msacc_id(),
74             counters := msacc_data_counters()}
75
76       msacc_data_counters() = #{msacc_state() => integer() >= 0}
77
78              A  map containing the different microstate accounting states and
79              the number of microseconds spent in it.
80
81       msacc_stats() = [msacc_stats_thread()]
82
83       msacc_stats_thread() =
84           #{'$type' := msacc_stats,
85             type := msacc_type(),
86             id := msacc_id(),
87             system := float(),
88             counters := msacc_stats_counters()}
89
90              A map containing information about a specific thread.  The  per‐
91              centages  in the map can be either run-time or real-time depend‐
92              ing on if runtime or realtime was requested from stats/2. system
93              is the percentage of total system time for this specific thread.
94
95       msacc_stats_counters() =
96           #{msacc_state() => #{thread := float(), system := float()}}
97
98              A  map  containing  the  different microstate accounting states.
99              Each value in the map contains another map with  the  percentage
100              of  time  that this thread has spent in the specific state. Both
101              the percentage of system time and the  time  for  that  specific
102              thread is part of the map.
103
104       msacc_type() =
105           aux | async | dirty_cpu_scheduler | dirty_io_scheduler |
106           poll | scheduler
107
108       msacc_id() = integer() >= 0
109
110       msacc_state() =
111           alloc | aux | bif | busy_wait | check_io | emulator | ets |
112           gc | gc_fullsweep | nif | other | port | send | sleep | timers
113
114              The  different  states that a thread can be in. See  erlang:sta‐
115              tistics(microstate_accounting) for details.
116
117       msacc_print_options() = #{system => boolean()}
118
119              The different options that can be given to print/2.
120

EXPORTS

122       available() -> boolean()
123
124              This function checks whether microstate accounting is  available
125              or not.
126
127       start() -> boolean()
128
129              Start  microstate  accounting. Returns whether it was previously
130              enabled or disabled.
131
132       start(Time) -> true
133
134              Types:
135
136                 Time = timeout()
137
138              Resets all counters and then starts  microstate  accounting  for
139              the given milliseconds.
140
141       stop() -> boolean()
142
143              Stop  microstate  accounting.  Returns whether is was previously
144              enabled or disabled.
145
146       reset() -> boolean()
147
148              Reset microstate accounting counters. Returns whether is was en‐
149              abled or disabled.
150
151       print() -> ok
152
153              Prints  the  current microstate accounting to standard out. Same
154              as msacc:print(msacc:stats(),#{}).
155
156       print(DataOrStats) -> ok
157
158              Types:
159
160                 DataOrStats = msacc_data() | msacc_stats()
161
162              Print the given microstate statistics values to stdout. Same  as
163              msacc:print(DataOrStats,#{}).
164
165       print(DataOrStats, Options) -> ok
166
167              Types:
168
169                 DataOrStats = msacc_data() | msacc_stats()
170                 Options = msacc_print_options()
171
172              Print  the  given  microstate statistics values to standard out.
173              With many states this can be quite verbose. See the top of  this
174              reference  manual  for  a  brief  description of what the fields
175              mean.
176
177              It is possible to print more specific  types  of  statistics  by
178              first  manipulating  the DataOrStats using stats/2. For instance
179              if you want to print the percentage of run-time for each  thread
180              you can do:
181
182              msacc:print(msacc:stats(runtime,msacc:stats())).
183
184              If you want to only print run-time per thread type you can do:
185
186              msacc:print(msacc:stats(type,msacc:stats(runtime,msacc:stats()))).
187
188              Options
189
190                system:
191                  Print  percentage  of time spent in each state out of system
192                  time as well as thread time. Default: false.
193
194       print(FileOrDevice, DataOrStats, Options) -> ok
195
196              Types:
197
198                 FileOrDevice = file:filename() | io:device()
199                 DataOrStats = msacc_data() | msacc_stats()
200                 Options = msacc_print_options()
201
202              Print the given microstate statistics values to the  given  file
203              or  device.  The  other  arguments  behave  the  same way as for
204              print/2.
205
206       stats() -> msacc_data()
207
208              Returns a runtime system independent version of  the  microstate
209              statistics  data  presented  by erlang:statistics(microstate_ac‐
210              counting). All counters have been normalized to be in  microsec‐
211              ond resolution.
212
213       stats(Analysis, Stats) -> integer() >= 0
214
215              Types:
216
217                 Analysis = system_realtime | system_runtime
218                 Stats = msacc_data()
219
220              Returns the system time for the given microstate statistics val‐
221              ues. System time is the accumulated time of all threads.
222
223                realtime:
224                  Returns all time recorded for all threads.
225
226                runtime:
227                  Returns all time spent doing work for all threads, i.e.  all
228                  time not spent in the sleep state.
229
230       stats(Analysis, Stats) -> msacc_stats()
231
232              Types:
233
234                 Analysis = realtime | runtime
235                 Stats = msacc_data()
236
237              Returns  fractions of real-time or run-time spent in the various
238              threads from the given microstate statistics values.
239
240       stats(Analysis, StatsOrData) -> msacc_data() | msacc_stats()
241
242              Types:
243
244                 Analysis = type
245                 StatsOrData = msacc_data() | msacc_stats()
246
247              Returns a list of microstate statistics values where the  values
248              for all threads of the same type has been merged.
249
250       to_file(Filename) -> ok | {error, file:posix()}
251
252              Types:
253
254                 Filename = file:name_all()
255
256              Dumps  the current microstate statistics counters to a file that
257              can be parsed with  file:consult/1.
258
259       from_file(Filename) -> msacc_data()
260
261              Types:
262
263                 Filename = file:name_all()
264
265              Read a file dump produced by  to_file(Filename).
266
267
268
269Ericsson AB                   runtime_tools 1.19                      msacc(3)
Impressum