# cpu_sup

### MODULE

cpu_sup

### MODULE SUMMARY

A CPU Load and CPU Utilization Supervisor Process

### DESCRIPTION

`cpu_sup` is part of the `os_mon` application and all configuration parameters are defined in the reference documentation for the `os_mon` application.

`cpu_sup` is a process which supervises the CPU load and CPU utilization.

The load values are proportional to how long time a runnable UNIX process has to spend in the run queue before it is scheduled. Accordingly, higher values mean more system load. The returned value divided by 256 produces the figure displayed by `rup` and `top`. What is displayed as 2.00 in `rup`, is displayed as as load up to the second mark in `xload`.

For example, `rup` displays a load of 128 as 0.50, and 512 as 2.00.

If the user wants to view load values as percentages of machine capacity, then this way of measuring presents a problem, because the load values are not restricted to a fixed interval. In this case, the following simple mathematical transformation can produce the load value as a percentage:

PercentLoad = 100 * (1 - D/(D + Load))

`D` determines which load value should be associated with which percentage. Choosing `D` = 50 means that 128 is 60% load, 256 is 80%, 512 is 90%, and so on.

Another way of measuring system load is to divide the number of busy CPU cycles by the total number of CPU cycles. This produces values in the 0-100 range immediately. However, this method hides the fact that a machine can be more or less saturated. CPU utilization is therefore a better name than system load for this measure.

A server which receives just enough requests to never become idle will score a CPU utilization of 100%. If the server receives 50% more requests, it will still scores 100%. When the system load is calculated with the percentage formula shown previously, the load will increase from 80% to 87%.

The `avg1/0`, `avg5/0`, and `avg15/0` functions can be used for retrieving system load values, and the `util/0`, and `util/1` functions can be used for retrieving CPU utilization values. System load values can currently be retrieved on Solaris, Linux, FreeBSD, and OpenBSD. CPU utilization values can currently be retrieved on Solaris and Linux.

When run on Linux, `cpu_sup` assumes that the `/proc` file system is present and accessible by `cpu_sup`. If it is not, `cpu_sup` will fail.

### EXPORTS

`nprocs() -> UnixProcesses | {error, Reason}`

Types:

`UnixProcesses = integer()`
`Reason = term()`

Returns the number of UNIX processes running on this machine. This is a crude way of measuring the system load, but it may be of interest in some cases.

`avg1() -> SystemLoad | {error, Reason}`

Types:

`SystemLoad = integer()`
`Reason = term()`

Returns the average system load in the last 60 seconds, as described above. 0 represents no load, 256 represents the load reported as 1.00 by `rup`.

`avg5() -> SystemLoad | {error, Reason}`

Types:

`SystemLoad = integer()`
`Reason = term()`

Returns the average system load from the last 300 seconds, as described above. 0 represents no load, 256 represents the load reported as 1.00 by `rup`.

`avg15() -> SystemLoad | {error, Reason}`

Types:

`SystemLoad = integer()`
`Reason = term()`

Returns the average system load from the last 900 seconds, as described above. 0 represents no load, 256 represents the load reported as 1.00 by `rup`.

`util(ArgList) -> UtilSpec | {error, Reason}`

Types:

`ArgList = [Arg]`
`Arg = atom()`
`UtilSpec = UtilDesc | [UtilDesc]`
`UtilDesc = {Cpus, Busy, NonBusy, Misc}`
`Cpus = integer() | [integer()] | atom()`
`Busy = CpuStateDesc`
`NonBusy = CpuStateDesc`
`CpuStateDesc = float() | [{atom(), float()}]`
`Misc = [{atom(), term()}]`
`Reason = term()`

Returns a CPU utilization specification of the CPU utilization since the last call to `util/0` or `util/1` by the calling process.

| The returned value of the first call to `util/0` or `util/1` by a process will on most systems be the CPU utilization since system boot, but this is not guaranteed and the value should therefore be regarded as garbage. This also applies to the first call to `util/0` or `util/1` by a process after a restart of `cpu_sup`.

Currently recognized `Arg`uments:

`detailed`
  The returned `UtilDesc`(s) will be more detailed.
`per_cpu`
  Each CPU will be specified separately (assuming this information can be retrieved from the operating system), i.e. one `UtilDesc` per CPU will be returned.

If the `per_cpu` has been passed as `Arg`ument, a list of `UtilDesc`s will be returned; otherwise, only one `UtilDesc` will be returned.

Description of the `UtilDesc`:

`Cpus`
  If `detailed` and/or `per_cpu` has been passed as arguments, this element will contain the CPU number, or a list of CPU numbers of the CPU or CPUs that the `UtilDesc` contains information about.
  If neither `detailed` nor `per_cpu` has been passed as arguments, this field will contain the atom `all` which implies that the `UtilDesc` contains information about all CPUs.
`Busy`
  If `detailed` has been passed as argument, this element will contain a list of `{atom(), float()}` tuples. Each tuple in the list contains information about a processor state that has been identified as a busy processor state. The first element is the name of the state, and the second element contains a float representing the percentage share of the CPU cycles spent in this state since the last call to `util/0` or `util/1`.
  If `detailed` hasn't been passed as argument, this element will contain the sum of the percentage shares of the CPU cycles spent in all states identified as busy.
  If `per_cpu` hasn't been passed, the value(s) presented are the average of all CPUs.
`NonBusy`
  The same as for the `Busy` element, but for processor states that has been identified as non-busy.
`Misc`
  Miscellaneous information. Currently unused; reserved for future use.

Currently these processor states are identified as busy:

`user`
  Executing code in user mode.
`nice_user`
  Executing code in low priority (nice) user mode. This state is currently only identified on Linux.
`kernel`
  Executing code in kernel mode.

Currently these processor states are identified as non-busy:

`wait`
  Waiting. This state is currently only identified on Solaris.
`idle`
  Idle.

| Identified processor states may be different on different operation systems and may change between different versions of `cpu_sup` on the same operating system. The sum of the percentage shares of the CPU cycles spent in all busy and all non-busy processor states will always add up to 100%, though.

Failure: `badarg` if the `ArgList` is not a list of recognized `Arg`uments.

`util() -> CpuUtil | {error, Reason}`

Types:

`CpuUtil = float()`
`Reason = term()`

Returns CPU utilization since the last call to `util/0` or `util/1` by the calling process.

| The returned value of the first call to `util/0` or `util/1` by a process will on most systems be the CPU utilization since system boot, but this is not guaranteed and the value should therefore be regarded as garbage. This also applies to the first call to `util/0` or `util/1` by a process after a restart of `cpu_sup`.

The CPU utilization is defined as the sum of the percentage shares of the CPU cycles spent in all busy processor states (see `util/1`) in average on all CPUs.

### See Also

os_mon(3)

### AUTHORS

Janne Lindblad - support@erlang.ericsson.se
Rickard Green - support@erlang.ericsson.se

os_mon 1.7.4
Copyright © 1991-2005 Ericsson AB