1cpu_sup(3) Erlang Module Definition cpu_sup(3)
2
6 cpu_sup - A CPU Load and CPU Utilization Supervisor Process
7
9 cpu_sup is a process which supervises the CPU load and CPU utilization.
10 It is part of the OS_Mon application, see os_mon(6). Available for
11 Unix, although CPU utilization values (util/0,1) are only available for
12 Solaris, Linux and FreeBSD.
13 The load values are proportional to how long time a runnable Unix
15 process has to spend in the run queue before it is scheduled. Accord‐
16 ingly, higher values mean more system load. The returned value divided
17 by 256 produces the figure displayed by rup and top. What is displayed
18 as 2.00 in rup, is displayed as load up to the second mark in xload.
19 For example, rup displays a load of 128 as 0.50, and 512 as 2.00.
21 If the user wants to view load values as percentage of machine capac‐
23 ity, then this way of measuring presents a problem, because the load
24 values are not restricted to a fixed interval. In this case, the fol‐
25 lowing simple mathematical transformation can produce the load value as
26 a percentage:
27 PercentLoad = 100 * (1 - D/(D + Load))
29 D determines which load value should be associated with which percent‐
32 age. Choosing D = 50 means that 128 is 60% load, 256 is 80%, 512 is
33 90%, and so on.
34 Another way of measuring system load is to divide the number of busy
36 CPU cycles by the total number of CPU cycles. This produces values in
37 the 0-100 range immediately. However, this method hides the fact that a
38 machine can be more or less saturated. CPU utilization is therefore a
39 better name than system load for this measure.
40 A server which receives just enough requests to never become idle will
42 score a CPU utilization of 100%. If the server receives 50% more re‐
43 quests, it will still score 100%. When the system load is calculated
44 with the percentage formula shown previously, the load will increase
45 from 80% to 87%.
46 The avg1/0, avg5/0, and avg15/0 functions can be used for retrieving
48 system load values, and the util/0 and util/1 functions can be used for
49 retrieving CPU utilization values.
50 When run on Linux, cpu_sup assumes that the /proc file system is
52 present and accessible by cpu_sup. If it is not, cpu_sup will termi‐
53 nate.
54
56 nprocs() -> UnixProcesses | {error, Reason}
57 Types:
59 UnixProcesses = int()
61 Reason = term()
62 Returns the number of UNIX processes running on this machine.
64 This is a crude way of measuring the system load, but it may be
65 of interest in some cases.
66 Returns 0 if cpu_sup is not available.
68 avg1() -> SystemLoad | {error, Reason}
70 Types:
72 SystemLoad = int()
74 Reason = term()
75 Returns the average system load in the last minute, as described
77 above. 0 represents no load, 256 represents the load reported as
78 1.00 by rup.
79 Returns 0 if cpu_sup is not available.
81 avg5() -> SystemLoad | {error, Reason}
83 Types:
85 SystemLoad = int()
87 Reason = term()
88 Returns the average system load in the last five minutes, as de‐
90 scribed above. 0 represents no load, 256 represents the load re‐
91 ported as 1.00 by rup.
92 Returns 0 if cpu_sup is not available.
94 avg15() -> SystemLoad | {error, Reason}
96 Types:
98 SystemLoad = int()
100 Reason = term()
101 Returns the average system load in the last 15 minutes, as de‐
103 scribed above. 0 represents no load, 256 represents the load re‐
104 ported as 1.00 by rup.
105 Returns 0 if cpu_sup is not available.
107 util() -> CpuUtil | {error, Reason}
109 Types:
111 CpuUtil = float()
113 Reason = term()
114 Returns CPU utilization since the last call to util/0 or util/1
116 by the calling process.
117 Note:
119 The returned value of the first call to util/0 or util/1 by a
120 process will on most systems be the CPU utilization since system
121 boot, but this is not guaranteed and the value should therefore
122 be regarded as garbage. This also applies to the first call af‐
123 ter a restart of cpu_sup.
124 The CPU utilization is defined as the sum of the percentage
127 shares of the CPU cycles spent in all busy processor states (see
128 util/1 below) in average on all CPUs.
129 Returns 0 if cpu_sup is not available.
131 util(Opts) -> UtilSpec | {error, Reason}
133 Types:
135 Opts = [detailed | per_cpu]
137 UtilSpec = UtilDesc | [UtilDesc]
138 UtilDesc = {Cpus, Busy, NonBusy, Misc}
139 Cpus = all | int() | [int()]()
140 Busy = NonBusy = {State, Share} | Share
141 State = user | nice_user | kernel
142 | wait | idle | atom()
143 Share = float()
144 Misc = []
145 Reason = term()
146 Returns CPU utilization since the last call to util/0 or util/1
148 by the calling process, in more detail than util/0.
149 Note:
151 The returned value of the first call to util/0 or util/1 by a
152 process will on most systems be the CPU utilization since system
153 boot, but this is not guaranteed and the value should therefore
154 be regarded as garbage. This also applies to the first call af‐
155 ter a restart of cpu_sup.
156 Currently recognized options:
159 detailed:
161 The returned UtilDesc(s) will be even more detailed.
162 per_cpu:
164 Each CPU will be specified separately (assuming this infor‐
165 mation can be retrieved from the operating system), that is,
166 a list with one UtilDesc per CPU will be returned.
167 Description of UtilDesc = {Cpus, Busy, NonBusy, Misc}:
169 Cpus:
171 If the detailed and/or per_cpu option is given, this is the
172 CPU number, or a list of the CPU numbers.
173 If not, this is the atom all which implies that the UtilDesc
175 contains information about all CPUs.
176 Busy:
178 If the detailed option is given, this is a list of {State,
179 Share} tuples, where each tuple contains information about a
180 processor state that has been identified as a busy processor
181 state (see below). The atom State is the name of the state,
182 and the float Share represents the percentage share of the
183 CPU cycles spent in this state since the last call to util/0
184 or util/1.
185 If not, this is the sum of the percentage shares of the CPU
187 cycles spent in all states identified as busy.
188 If the per_cpu is not given, the value(s) presented are the
190 average of all CPUs.
191 NonBusy:
193 Similar to Busy, but for processor states that have been
194 identified as non-busy (see below).
195 Misc:
197 Currently unused; reserved for future use.
198 Currently these processor states are identified as busy:
200 user:
202 Executing code in user mode.
203 nice_user:
205 Executing code in low priority (nice) user mode. This state
206 is currently only identified on Linux.
207 kernel:
209 Executing code in kernel mode.
210 Currently these processor states are identified as non-busy:
212 wait:
214 Waiting. This state is currently only identified on Solaris.
215 idle:
217 Idle.
218 Note:
220 Identified processor states may be different on different oper‐
221 ating systems and may change between different versions of
222 cpu_sup on the same operating system. The sum of the percentage
223 shares of the CPU cycles spent in all busy and all non-busy pro‐
224 cessor states will always add up to 100%, though.
225 Returns {all,0,0,[]} if cpu_sup is not available.
228
230 os_mon(3)
231Ericsson AB os_mon 2.8 cpu_sup(3)