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

NAME

6       cpu_sup - A CPU Load and CPU Utilization Supervisor Process
7

DESCRIPTION

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
43       requests, 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

EXPORTS

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
90              described  above.  0 represents no load, 256 represents the load
91              reported 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
103              described  above.  0 represents no load, 256 represents the load
104              reported 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
123              after 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
155              after 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

SEE ALSO

230       os_mon(3)
231
232
233
234Ericsson AB                      os_mon 2.4.7                       cpu_sup(3)
Impressum