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
10       microstate accounting data. For details about how to use the basic  api
11       and   what   the   different   states   represent  see   erlang:statis‐
12       tics(microstate_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 |
106           async |
107           dirty_cpu_scheduler |
108           dirty_io_scheduler |
109           poll |
110           scheduler
111
112       msacc_id() = integer() >= 0
113
114       msacc_state() =
115           alloc |
116           aux |
117           bif |
118           busy_wait |
119           check_io |
120           emulator |
121           ets |
122           gc |
123           gc_fullsweep |
124           nif |
125           other |
126           port |
127           send |
128           sleep |
129           timers
130
131              The  different  states that a thread can be in. See  erlang:sta‐
132              tistics(microstate_accounting) for details.
133
134       msacc_print_options() = #{system => boolean()}
135
136              The different options that can be given to print/2.
137

EXPORTS

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