1msacc(3) Erlang Module Definition msacc(3)
2
6 msacc - Convenience functions for microstate accounting
7
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 Basic Scenario
15 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 Thread aux check_io emulator gc other port sleep
24 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 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 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 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 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 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 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 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
68 msacc_data() = [msacc_data_thread()]
69 msacc_data_thread() =
71 #{'$type' := msacc_data,
72 type := msacc_type(),
73 id := msacc_id(),
74 counters := msacc_data_counters()}
75 msacc_data_counters() = #{msacc_state() => integer() >= 0}
77 A map containing the different microstate accounting states and
79 the number of microseconds spent in it.
80 msacc_stats() = [msacc_stats_thread()]
82 msacc_stats_thread() =
84 #{'$type' := msacc_stats,
85 type := msacc_type(),
86 id := msacc_id(),
87 system := float(),
88 counters := msacc_stats_counters()}
89 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 msacc_stats_counters() =
96 #{msacc_state() => #{thread := float(), system := float()}}
97 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 msacc_type() =
105 aux |
106 async |
107 dirty_cpu_scheduler |
108 dirty_io_scheduler |
109 poll |
110 scheduler
111 msacc_id() = integer() >= 0
113 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 The different states that a thread can be in. See erlang:sta‐
132 tistics(microstate_accounting) for details.
133 msacc_print_options() = #{system => boolean()}
135 The different options that can be given to print/2.
137
139 available() -> boolean()
140 This function checks whether microstate accounting is available
142 or not.
143 start() -> boolean()
145 Start microstate accounting. Returns whether it was previously
147 enabled or disabled.
148 start(Time) -> true
150 Types:
152 Time = timeout()
154 Resets all counters and then starts microstate accounting for
156 the given milliseconds.
157 stop() -> boolean()
159 Stop microstate accounting. Returns whether is was previously
161 enabled or disabled.
162 reset() -> boolean()
164 Reset microstate accounting counters. Returns whether is was
166 enabled or disabled.
167 print() -> ok
169 Prints the current microstate accounting to standard out. Same
171 as msacc:print(msacc:stats(),#{}).
172 print(DataOrStats) -> ok
174 Types:
176 DataOrStats = msacc_data() | msacc_stats()
178 Print the given microstate statistics values to stdout. Same as
180 msacc:print(DataOrStats,#{}).
181 print(DataOrStats, Options) -> ok
183 Types:
185 DataOrStats = msacc_data() | msacc_stats()
187 Options = msacc_print_options()
188 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 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 msacc:print(msacc:stats(runtime,msacc:stats())).
200 If you want to only print run-time per thread type you can do:
202 msacc:print(msacc:stats(type,msacc:stats(runtime,msacc:stats()))).
204 Options
206 system:
208 Print percentage of time spent in each state out of system
209 time as well as thread time. Default: false.
210 print(FileOrDevice, DataOrStats, Options) -> ok
212 Types:
214 FileOrDevice = file:filename() | io:device()
216 DataOrStats = msacc_data() | msacc_stats()
217 Options = msacc_print_options()
218 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 stats() -> msacc_data()
224 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 stats(Analysis, Stats) -> integer() >= 0
231 Types:
233 Analysis = system_realtime | system_runtime
235 Stats = msacc_data()
236 Returns the system time for the given microstate statistics val‐
238 ues. System time is the accumulated time of all threads.
239 realtime:
241 Returns all time recorded for all threads.
242 runtime:
244 Returns all time spent doing work for all threads, i.e. all
245 time not spent in the sleep state.
246 stats(Analysis, Stats) -> msacc_stats()
248 Types:
250 Analysis = realtime | runtime
252 Stats = msacc_data()
253 Returns fractions of real-time or run-time spent in the various
255 threads from the given microstate statistics values.
256 stats(Analysis, StatsOrData) -> msacc_data() | msacc_stats()
258 Types:
260 Analysis = type
262 StatsOrData = msacc_data() | msacc_stats()
263 Returns a list of microstate statistics values where the values
265 for all threads of the same type has been merged.
266 to_file(Filename) -> ok | {error, file:posix()}
268 Types:
270 Filename = file:name_all()
272 Dumps the current microstate statistics counters to a file that
274 can be parsed with file:consult/1.
275 from_file(Filename) -> msacc_data()
277 Types:
279 Filename = file:name_all()
281 Read a file dump produced by to_file(Filename).
283Ericsson AB runtime_tools 1.13.2 msacc(3)