1cpu_sup(3) Erlang Module Definition cpu_sup(3)
2
3
4
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
14 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
20 For example, rup displays a load of 128 as 0.50, and 512 as 2.00.
21
22 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
28 PercentLoad = 100 * (1 - D/(D + Load))
29
30
31 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
35 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
41 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
47 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
51 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
58 Types:
59
60 UnixProcesses = int()
61 Reason = term()
62
63 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
67 Returns 0 if cpu_sup is not available.
68
69 avg1() -> SystemLoad | {error, Reason}
70
71 Types:
72
73 SystemLoad = int()
74 Reason = term()
75
76 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
80 Returns 0 if cpu_sup is not available.
81
82 avg5() -> SystemLoad | {error, Reason}
83
84 Types:
85
86 SystemLoad = int()
87 Reason = term()
88
89 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
93 Returns 0 if cpu_sup is not available.
94
95 avg15() -> SystemLoad | {error, Reason}
96
97 Types:
98
99 SystemLoad = int()
100 Reason = term()
101
102 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
106 Returns 0 if cpu_sup is not available.
107
108 util() -> CpuUtil | {error, Reason}
109
110 Types:
111
112 CpuUtil = float()
113 Reason = term()
114
115 Returns CPU utilization since the last call to util/0 or util/1
116 by the calling process.
117
118 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
125
126 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
130 Returns 0 if cpu_sup is not available.
131
132 util(Opts) -> UtilSpec | {error, Reason}
133
134 Types:
135
136 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
147 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
150 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
157
158 Currently recognized options:
159
160 detailed:
161 The returned UtilDesc(s) will be even more detailed.
162
163 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
168 Description of UtilDesc = {Cpus, Busy, NonBusy, Misc}:
169
170 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
174 If not, this is the atom all which implies that the UtilDesc
175 contains information about all CPUs.
176
177 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
186 If not, this is the sum of the percentage shares of the CPU
187 cycles spent in all states identified as busy.
188
189 If the per_cpu is not given, the value(s) presented are the
190 average of all CPUs.
191
192 NonBusy:
193 Similar to Busy, but for processor states that have been
194 identified as non-busy (see below).
195
196 Misc:
197 Currently unused; reserved for future use.
198
199 Currently these processor states are identified as busy:
200
201 user:
202 Executing code in user mode.
203
204 nice_user:
205 Executing code in low priority (nice) user mode. This state
206 is currently only identified on Linux.
207
208 kernel:
209 Executing code in kernel mode.
210
211 Currently these processor states are identified as non-busy:
212
213 wait:
214 Waiting. This state is currently only identified on Solaris.
215
216 idle:
217 Idle.
218
219 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
226
227 Returns {all,0,0,[]} if cpu_sup is not available.
228
230 os_mon(3)
231
232
233
234Ericsson AB os_mon 2.7.1 cpu_sup(3)