os_mon

v2.11.1-rc0

OS Monitoring Application

Description

The operating system monitor, OS_Mon, provides the following services:

cpu_sup CPU load and utilization supervision (Unix)

disksup Disk supervision(Unix, Windows)

memsup Memory supervision (Unix, Windows)

os_sup Interface to OS system messages (Solaris, Windows)

To simplify usage of OS_Mon on distributed Erlang systems, it is not considered an error trying to use a service at a node where it is not available (either because OS_Mon is not running, or because the service is not available for that OS, or because the service is not started). Instead, a warning message is issued via error_logger and a dummy value is returned, which one is specified in the man pages for the respective services.

Configuration

When OS_Mon is started, by default all services available for the OS, except os_sup, are automatically started. This configuration can be changed using the following application configuration parameters:

start_cpu_sup = bool() - Specifies if cpu_sup should be started. Defaults to true.

start_disksup = bool() - Specifies if disksup should be started. Defaults to true.

start_memsup = bool() - Specifies if memsup should be started. Defaults to true.

start_os_sup = bool() - Specifies if os_sup should be started. Defaults to false.

Configuration parameters effecting the different OS_Mon services are described in the respective man pages.

See config for information about how to change the value of configuration parameters.

See Also

cpu_sup, disksup, memsup, os_sup, nteventlog, snmp.

OS_Mon Release Notes

This document describes the changes made to the OS_Mon application.

Os_Mon 2.11.1

Fixed Bugs and Malfunctions

NIFs and linked-in drivers are now loadable when running in an Erlang source tree on Windows.

Own Id: OTP-19686 Aux Id: PR-9969

Os_Mon 2.11

Fixed Bugs and Malfunctions

Enhance specs of timeout for improving documentation and dialyzer analysis.

Own Id: OTP-19604 Aux Id: PR-9574

Improvements and New Features

disksup will now recognize HAMMER2 volumes.

Own Id: OTP-19207 Aux Id: PR-8704

The license and copyright header has changed format to include an SPDX-License-Identifier. At the same time, most files have been updated to follow a uniform standard for license headers.

Own Id: OTP-19575 Aux Id: PR-9670

Os_Mon 2.10.1

Fixed Bugs and Malfunctions

Fixed the memsup memory alarm to use available_memory when available, instead of always using free_memory.

Own Id: OTP-19304 Aux Id: PR-8776, GH-8759

Os_Mon 2.10

Improvements and New Features

Function specifications and types have been added to all public API functions.

Own Id: OTP-18913

The documentation has been migrated to use Markdown and ExDoc.

Own Id: OTP-18955 Aux Id: PR-8026

Os_Mon 2.9.1

Fixed Bugs and Malfunctions

Fixed some benign compile warnings on Windows.

Own Id: OTP-18895

Os_Mon 2.9

Fixed Bugs and Malfunctions

Fix internal os_mon_sysinfo:get_disk_info/1 function to not crash when run on Windows with multiple drives.

Own Id: OTP-18246 Aux Id: PR-6284 GH-6156

Fixed a memory leak when calling cpu_sup:util/0,1 on FreeBSD.

Own Id: OTP-18546 Aux Id: GH-7070, PR-7071

Improvements and New Features

The disksup:get_disk_info/0 and disksup:get_disk_info/1 functions have been introduced. These can be used in order to immediately fetch information about current disk usage.

Own Id: OTP-18303 Aux Id: PR-6384

Runtime dependencies have been updated.

Own Id: OTP-18350

Support for cpu_sup:util() on OpenBSD.

Own Id: OTP-18566 Aux Id: PR-7080

Os_Mon 2.8.2.1

Fixed Bugs and Malfunctions

Fixed runtime dependencies.

Own Id: OTP-19064

Os_Mon 2.8.2

Fixed Bugs and Malfunctions

Avoid error report from failing erlang:port_close at shutdown of cpu_sup and memsup. Bug exists since OTP 25.3 (os_mon-2.8.1).

Own Id: OTP-18559 Aux Id: ERIERL-942

Os_Mon 2.8.1

Fixed Bugs and Malfunctions

The port programs used by cpu_sup and memsup are now gracefully shut down when cpu_sup and memsup are shut down.

Own Id: OTP-18469 Aux Id: PR-6689

Os_Mon 2.8

Improvements and New Features

The disk_space_check_interval configuration parameter of disksup can now be set to values smaller than a minute.

Own Id: OTP-18304 Aux Id: PR-6385

Os_Mon 2.7.1

Fixed Bugs and Malfunctions

On a Mac with Apple Silicon, memsup:get_os_wordsize/0 would return 32 instead of 64.

Own Id: OTP-17441

Os_Mon 2.7

Improvements and New Features

The temporarily introduced configuration parameter memsup_improved_system_memory_data has been removed.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-16943 Aux Id: OTP-16906

Fix disk_sup to also search the system PATH on linux when looking for the df program.

Own Id: OTP-16944 Aux Id: PR-2787

Os_Mon 2.6.1

Improvements and New Features

The configuration parameter memsup_improved_system_memory_data has been introduced. It can be used to modify the result returned by memsup:get_system_memory_data(). For more information see the memsup documentation.

Note that the configuration parameter is intended to be removed in OTP 24 and the modified result is intended to be used as of OTP 24.

Own Id: OTP-16906 Aux Id: ERIERL-532

Os_Mon 2.6

Fixed Bugs and Malfunctions

memsup now returns the correct amount of system memory on macOS.

Own Id: OTP-16798 Aux Id: ERL-1327

Improvements and New Features

Fix memsup:get_os_wordsize/0 to return the current size on aarch64.

Own Id: OTP-16742

Os_Mon 2.5.2

Fixed Bugs and Malfunctions

Fix various compiler warnings on 64-bit Windows.

Own Id: OTP-15800

Improvements and New Features

Refactored the internal handling of deprecated and removed functions.

Own Id: OTP-16469

Os_Mon 2.5.1.1

Improvements and New Features

The configuration parameter memsup_improved_system_memory_data has been introduced. It can be used to modify the result returned by memsup:get_system_memory_data(). For more information see the memsup documentation.

Note that the configuration parameter is intended to be removed in OTP 24 and the modified result is intended to be used as of OTP 24.

Own Id: OTP-16906 Aux Id: ERIERL-532

Os_Mon 2.5.1

Fixed Bugs and Malfunctions

Fix disk_sup to ignore squashfs on Linux when determining if a mounted filesystem is full or not.

Own Id: OTP-15778

Fix bug where cpu_sup:util() always returned 100% on systems not using gnu libc, for example Alpine OS.

Own Id: OTP-15974 Aux Id: ERL-1012

Os_Mon 2.5

Fixed Bugs and Malfunctions

Fix typespec of cpu_sup:util().

Own Id: OTP-15770 Aux Id: PR-2208

Improvements and New Features

The application otp_mibs has been removed from OTP. Some of its components (mibs) have been moved to other apps (snmp), or removed completely (os_mon).

Own Id: OTP-14984 Aux Id: OTP-15329

Os_Mon 2.4.7

Fixed Bugs and Malfunctions

Due to /proc restrictions in newer Android releases enforced by SELinux, cpu_sup is fixed so that it gets some basic CPU stats using the sysinfo syscall rather than reading /proc/loadavg.

Own Id: OTP-15387 Aux Id: PR-1966

Os_Mon 2.4.6

Fixed Bugs and Malfunctions

Improved documentation.

Own Id: OTP-15190

Os_Mon 2.4.5

Fixed Bugs and Malfunctions

Fix disksup to handle mount paths with spaces in them.

Own Id: OTP-14513

Os_Mon 2.4.4

Fixed Bugs and Malfunctions

Removed all old unused files in the documentation.

Own Id: OTP-14475 Aux Id: ERL-409, PR-1493

Os_Mon 2.4.3

Fixed Bugs and Malfunctions

On macOS 10.13 (High Sierra), disksup could not grab information for any disks that used the new APFS file system. That has been corrected.

Own Id: OTP-14560 Aux Id: ERL-461

Os_Mon 2.4.2

Improvements and New Features

Support s390x in os_mon.

Own Id: OTP-14161 Aux Id: PR-1309

Os_Mon 2.4.1

Fixed Bugs and Malfunctions

Fix type specification for cpu_sup:util/1

Own Id: OTP-13526 Aux Id: PR-1029

Fix strict compilation on SUN/SPARC

Own Id: OTP-13548 Aux Id: PR-1046

Implement cpu_sup:util/0,1 on Mac OSX

Own Id: OTP-13597 Aux Id: PR-1049

Fix memsup:get_os_wordsize() on 64-bit FreeBSD and 64-bit Linux PPC

Own Id: OTP-13601 Aux Id: PR-1039

Os_Mon 2.4

Improvements and New Features

cpu_sup should use native sysctl/libkvm calls on BSD

This avoids forking off with os:cmd every time we just want to collect the load averages. riak does this every second, which results in a lot of unnecessary load.

Own Id: OTP-12730

Implement native cpu_sup:util/0,1 for FreeBSD

Own Id: OTP-12796

Os_Mon 2.3.1

Fixed Bugs and Malfunctions

Do not crash with badmatch when integer part of loadavg has more than 2 digits.

Own Id: OTP-12581

Improvements and New Features

Fix compilation of memsup on OpenBSD.

Own Id: OTP-12404

Os_Mon 2.3

Improvements and New Features

Adds a new application parameter 'disksup_posix_only', to make diskup use only options defined in the POSIX standard.

Own Id: OTP-12053

Os_Mon 2.2.15

Fixed Bugs and Malfunctions

Application upgrade (appup) files are corrected for the following applications:

asn1, common_test, compiler, crypto, debugger, dialyzer, edoc, eldap, erl_docgen, et, eunit, gs, hipe, inets, observer, odbc, os_mon, otp_mibs, parsetools, percept, public_key, reltool, runtime_tools, ssh, syntax_tools, test_server, tools, typer, webtool, wx, xmerl

A new test utility for testing appup files is added to test_server. This is now used by most applications in OTP.

(Thanks to Tobias Schlager)

Own Id: OTP-11744

Improvements and New Features

Calls to erlang:open_port/2 with 'spawn' are updated to handle space in the command path.

Own Id: OTP-10842

Os_Mon 2.2.14

Fixed Bugs and Malfunctions

Fix incorrect reporting of memory on OS X via memsup. Thanks to Christopher Meiklejohn.

Own Id: OTP-11454

Os_Mon 2.2.13

Fixed Bugs and Malfunctions

Use 'df -k -l' to query FreeBSD and OpenBSD about diskspace on local disks. Previously 'df' -k -t ufs' was used but this will not handle zfs or other disks. Just use '-l' instead of listing potential filesystems.

Own Id: OTP-11207

Improvements and New Features

Fix compilation on Solaris. Thanks to Maciej Malecki.

Own Id: OTP-11213

Fix broken cpu_sup:nprocs and others on Solaris 64-bit. Thanks to Simon Cornish.

Own Id: OTP-11298

Os_Mon 2.2.12

Fixed Bugs and Malfunctions

Compilation fixes for NetBSD. Thanks to YAMAMOTO Takashi.

Own Id: OTP-10941

Improvements and New Features

Fixed disksup:get_disk_data for SUSv3, specifically OS X ML. Thanks to Sriram Melkote.

Own Id: OTP-10945

Os_Mon 2.2.11

Fixed Bugs and Malfunctions

Removed deprecated function calls to snmp

Own Id: OTP-10448

Os_Mon 2.2.10

Fixed Bugs and Malfunctions

Infinity timeout added to internal calls in disksup to allow it to work properly under very heavy load.

Own Id: OTP-10100

Clarify error messages from os_mon port programs

Own Id: OTP-10161

Os_Mon 2.2.9

Fixed Bugs and Malfunctions

Fix segmentation fault in memsup

when /proc/meminfo does not include information about buffers/cache (for instance inside OpenVZ container) (Thanks to Anton Vorobev)

Own Id: OTP-9913

Os_Mon 2.2.8

Improvements and New Features

Erlang/OTP can now be built using parallel make if you limit the number of jobs, for instance using 'make -j6' or 'make -j10'. 'make -j' does not work at the moment because of some missing dependencies.

Own Id: OTP-9451

Tuple funs (a two-element tuple with a module name and a function) are now officially deprecated and will be removed in R16. Use 'fun M:F/A' instead. To make you aware that your system uses tuple funs, the very first time a tuple fun is applied, a warning will be sent to the error logger.

Own Id: OTP-9649

Os_Mon 2.2.7

Fixed Bugs and Malfunctions

Remove misc. compiler warnings

Own Id: OTP-9542

Os_Mon 2.2.6

Fixed Bugs and Malfunctions

Add NetBSD support to memsup and disksup (Thanks to Andrew Thompson)

Own Id: OTP-9216

Add support for DragonFlyBSD to memsup

DragonFly was partially supported by os_mon already but when trying to start the os_mon application it'd crash with an error about an unknown operating system in memsup. This patch changes memsup to use the FreeBSD sysctl method to get memory information when on DragonFly. (Thanks to Andrew Thompson )

Own Id: OTP-9217

Os_Mon 2.2.5

Improvements and New Features

Cleanups suggested by tidier and modernization of types and specs.

Own Id: OTP-8455

Os_Mon 2.2.4

Fixed Bugs and Malfunctions

Memsup did not read memory correctly on macOS X Snowleopard. This has now been corrected. (Thanks to Joel Reymont)

Own Id: OTP-8211

Removed unused code in cpu_sup.erl.

Own Id: OTP-8226

Improvements and New Features

The documentation is now built with open source tools (xsltproc and fop) that exists on most platforms. One visible change is that the frames are removed.

Own Id: OTP-8201

Os_Mon 2.2.3

Fixed Bugs and Malfunctions

A missing define in memsup.c caused a build error on IRIX machines. This has now been fixed.

Own Id: OTP-8094

Os_Mon 2.2.2

Fixed Bugs and Malfunctions

disksup:get_disk_data/0 returned disk volume in bytes instead of kbytes as stated in the documentation. The problem occurred on Windows only and is now corrected.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-7741

Os_Mon 2.2.1

Fixed Bugs and Malfunctions

An error in memsup could cause os_mon to report erroneous memory values on windows for ranges of memory between 2GB and 4GB. This have now been fixed.

Own Id: OTP-7944

Improvements and New Features

Added support for dragonfly OS.

Own Id: OTP-7938

Os_Mon 2.2

Improvements and New Features

The copyright notices have been updated.

Own Id: OTP-7851

Os_Mon 2.1.8

Fixed Bugs and Malfunctions

A problem with OTP-OS-MON-MIB.mib for 64-bit environments has now been fixed. The mib has been extended with 64-bit memory retrieval counterparts.

In addition, a new function get_os_wordsize/0 has been added in the memsup module

Own Id: OTP-7441

An error in memsup.c caused the compilation to crash on bsd environments. This has now been fixed.

Own Id: OTP-7558

Os_Mon 2.1.7

Fixed Bugs and Malfunctions

Fixed a build error that occurred on NetBSD (Thanks to Per Hedeland and Raphael Langerhorst)

Own Id: OTP-7505

Improvements and New Features

Memory information in memsup:get_system_memory_data/0 now has additional entries in its property list for Linux.

Own Id: OTP-7409 Aux Id: seq10984

Os_Mon 2.1.6

Fixed Bugs and Malfunctions

System information retrieval on darwin platforms with environments locales not conforming to the C locale caused an error in cpu_sup resulting in process termination.

Own Id: OTP-7320

Os_Mon 2.1.5

Improvements and New Features

CPU utilization, on linux, is now measured via a port program instead of os:cmd in erlang. This should enhance performance.

Own Id: OTP-7108 Aux Id: OTP-6935

Os_Mon 2.1.3

Improvements and New Features

Extended memsup memory probing on Linux to use a port program to probe memory usage. This is faster than the previous implementation.

Own Id: OTP-6860 Aux Id: seq10616

Os_Mon 2.1.2.1

Improvements and New Features

Minor Makefile changes.

Own Id: OTP-6689

OS_Mon 2.1.2

Fixed Bugs and Malfunctions

When the memsup_system_only flag was set to true, a badmatch exception occurred in the function os_mon_mib:get_load/1.

Own Id: OTP-6351 Aux Id: seq10517

OS_Mon 2.1.1

Fixed Bugs and Malfunctions

Did not build on Mac OS X.

Added support for IRIX. (Thanks to Michel Urvoy and Daniel Solaz.)

Own Id: OTP-6136

Improvements and New Features

disksup: Now using round(T*100) instead of trunc(T*100) when setting the threshold value given a float T.

Own Id: OTP-6153

Os_Mon 2.1

Fixed Bugs and Malfunctions

In 2.0, a call to alarm_handler:get_alarms/0 was introduced in memsup and disksup. This will lead to problems if the default alarm_handler event handler is not used, however, and the call has now been removed. (Thanks to Serge Aleynikov for pointing this out.)

Own Id: OTP-6029

A bug that in rare cases caused cpu_sup to crash has been corrected.

Own Id: OTP-6102 Aux Id: seq10312

OS_Mon 2.0

A note on backwards compatibility: The behaviour of OS_Mon 2.0 is backwards compatible under normal operation, but has changed somewhat in error situations: The services do not terminate and the API functions do not raise exceptions in all cases where they did before. Also, in the case where a service does terminate, the exit reason may be different. See below for details.

Fixed Bugs and Malfunctions

A call to a OS_Mon service (cpu_sup, disksup, ...) when OS_Mon is not running, or when the service is not available for the OS, or when the service is not started, will no longer result in an exception. Instead a warning is issued via error_logger and a dummy value is returned, which one is specified in the man pages for the respective service.

The reason is that it should not be necessary for a service to be started on each and every node of a distributed Erlang system for the OS-MON-MIB and other OS_Mon users to work properly.

Own Id: OTP-4332 Aux Id: seq7358

References to the obsolete EVA application in OTP-OS-MON-MIB has been removed.

Own Id: OTP-5699

Setting the option memsup_system_only to true did not work, but would crash the memsup process.

Own Id: OTP-5890 Aux Id: seq10185

cpu_sup:nprocs/0 returned 0 on FreeBsd.

Own Id: OTP-5901

If the OS_Mon service disksup or memsup was restarted, the same alarm could be set twice. Also, set alarms were not cleared when the application was stopped.

Own Id: OTP-5910

Improvements and New Features

Thresholds and time intervals in disksup and memsup are now configurable in run-time.

Own Id: OTP-4246 Aux Id: Seq7230

memsup can now handle systems with more than 4GB of RAM.

Own Id: OTP-5800 Aux Id: seq10130

The entire OS_Mon application (code and documentation) has been reviewed and consequently updated with the goal to make the application more robust, homogeneous and easier to configure.

The behaviour under normal operation is backwards compatible. However, recoverable errors now no longer terminate the affected service (and thus possible the entire application), instead error_logger is used to warn the user if/when such errors occurs. Also, in the case of unrecoverable errors, the services have been made more homogeneous with respect to behavior and exit reasons. See below for more information and refer to the man pages for details.

Port handling has been unified, meaning that if a port program sends garbage or unexpectedly dies, this is now handled the same way by all OS_Mon services, namely immediate process termination with the exit reason {port_error,Garbage} or {port_died,Reason}, respectively.

Application configuration parameter handling has been unified. Bad parameter values are no longer silently ignored (disksup) or cause application termination (memsup, os_sup). Instead a warning is issued and the default value for the parameter is used. Also, some cases where a bad parameter value accidentally could be accepted have been corrected.

Message handling has been unified. Unknown (gen_server-) calls cause process termination, whereas unknown casts and messages are now ignored by all OS_Mon services.

Own Id: OTP-5897

The following changes have been made to the os_sup service:

It is now available on Windows, using nteventlog as backend.

On Solaris, enabling the service (that is, installing a new configuration file for syslogd etc.) can now be done outside the os_sup process. The reason for this is that the Erlang emulator should normally not be run with root privileges, as is otherwise required. The new application configuration parameter os_sup_config must be set to false.

Also, os_sup can now be configured using a new configuration parameter os_sup_mfa to call an arbitrary Erlang function when a message is received from the OS.

Own Id: OTP-5925

The memsup service has been rewritten, replacing the supervised memsup_helper with a linked help process. This gives the memsup process more control and prevents a situation where it gets out of synch with the received memory data and thus possibly returns erroneous results.

Own Id: OTP-5927

OS_Mon 1.8.1

Fixed Bugs and Malfunctions

cpu_sup:util/0 failed with error reason negative_diff when called the first time on a machine (hw) that had been up for a very long time.

Own Id: OTP-5869 Aux Id: seq10166

OS_Mon 1.8

Improvements and New Features

The memsup part of the OS_Mon application has been made more stable. If there are (possibly temporary) problems collecting memory data, the interface functions (get_memory_data/0, get_system_memory_data/0) now do not fail, but return the previously collected value, if any, or a dummy value otherwise. Also, a warning message is printed.

* POTENTIAL INCOMPATIBILITY *

Own Id: OTP-5798

OS_Mon 1.7.4

Fixed Bugs and Malfunctions

Corrected several problems in the error handling/error recovery (especially when OS_Mon is starting up).

Own Id: OTP-5559

OS_Mon 1.7.3

Improvements and New Features

memsup.c will now compile on OpenBSD. (Thanks to Geoff White and Jay Nelson.)

The disksup and cpu_sup modules now work on Mac OS X (tested on Mac OS 10.3.8).

The memsup module should now work on Linux 2.6.* as well as on older Linuxes. (/proc/meminfo has slightly different formats in different releases of Linux.)

Own Id: OTP-5421
Aux Id: OTP-5194, OTP-5228, OTP-5291

OS_Mon 1.7.2

This version is identical with 1.7.

cpu_sup

A CPU Load and CPU Utilization Supervisor Process

cpu_sup is a process which supervises the CPU load and CPU utilization. It is part of the OS_Mon application, see os_mon(6). Available for Unix, although CPU utilization values (util/0,1) are only available for Solaris, Linux, FreeBSD and OpenBSD.

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 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 percentage 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 score 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.

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 terminate.

See Also

os_mon(3)

Summary

Types

util_cpus()

util_desc()

util_state()

util_value()

Functions

avg1()

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

avg5()

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

avg15()

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

nprocs()

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.

util()

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

util/1

Returns CPU utilization since the last call to util/0 or util/1 by the calling process, in more detail than util/0.

Types

util_cpus()

(not exported)

-type util_cpus() :: all | integer() | [integer()].

util_desc()

(not exported)

-type util_desc() :: {util_cpus(), util_value(), util_value(), []}.

util_state()

(not exported)

-type util_state() :: user | nice_user | kernel | wait | idle.

util_value()

(not exported)

-type util_value() :: [{util_state(), number()}] | number().

Functions

avg1()

-spec avg1() -> SystemLoad :: integer() | {error, any()}.

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

Returns 0 if cpu_sup is not available.

avg5()

-spec avg5() -> SystemLoad :: integer() | {error, any()}.

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

Returns 0 if cpu_sup is not available.

avg15()

-spec avg15() -> SystemLoad :: integer() | {error, any()}.

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

Returns 0 if cpu_sup is not available.

nprocs()

-spec nprocs() -> UnixProcesses :: integer() | {error, any()}.

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.

Returns 0 if cpu_sup is not available.

util()

-spec util() -> CpuUtil :: number() | {error, any()}.

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

Note

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 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.

Returns 0 if cpu_sup is not available.

util/1

-spec util([detailed | per_cpu]) -> util_desc() | [util_desc()] | {error, any()}.

Returns CPU utilization since the last call to util/0 or util/1 by the calling process, in more detail than util/0.

Note

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 after a restart of cpu_sup.

Currently recognized options:

detailed - The returned UtilDesc(s) will be even more detailed.

per_cpu - Each CPU will be specified separately (assuming this information can be retrieved from the operating system), that is, a list with one UtilDesc per CPU will be returned.

Description of UtilDesc = {Cpus, Busy, NonBusy, Misc}:

Cpus - If the detailed and/or per_cpu option is given, this is the CPU number, or a list of the CPU numbers.

If not, this is the atom all which implies that the UtilDesc contains information about all CPUs.

Busy - If the detailed option is given, this is a list of {State, Share} tuples, where each tuple contains information about a processor state that has been identified as a busy processor state (see below). The atom State is the name of the state, and the float Share represents the percentage share of the CPU cycles spent in this state since the last call to util/0 or util/1.

If not, this is the sum of the percentage shares of the CPU cycles spent in all states identified as busy.

If the per_cpu is not given, the value(s) presented are the average of all CPUs.

NonBusy - Similar to Busy, but for processor states that have been identified as non-busy (see below).

Misc - 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.

Note

Identified processor states may be different on different operating 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.

Returns {all,0,0,[]} if cpu_sup is not available.

disksup

A Disk Supervisor Process

disksup is a process which supervises the available disk space in the system. It is part of the OS_Mon application, see os_mon(6). Available for Unix and Windows.

Periodically checks the disks. For each disk or partition which uses more than a certain amount of the available space, the alarm {{disk_almost_full, MountedOn}, []} is set.

On Unix - All (locally) mounted disks are checked, including the swap disk if it is present.

On WIN32 - All logical drives of type "FIXED_DISK" are checked.

Alarms are reported to the SASL alarm handler, see alarm_handler. To set an alarm, alarm_handler:set_alarm(Alarm) is called where Alarm is the alarm specified above.

The alarms are cleared automatically when the alarm cause is no longer valid.

Configuration

The following configuration parameters can be used to change the default values for time interval and threshold:

disk_space_check_interval = time/0 - The time interval for the periodic disk space check. The default is 30 minutes.

disk_almost_full_threshold = float() - The threshold, as percentage of total disk space, for how much disk can be utilized before the disk_almost_full alarm is set. The default is 0.80 (80%).

disksup_posix_only = bool() - Specifies whether the disksup helper process should only use POSIX conformant commands (true) or not. The default is false. Setting this parameter to true can be necessary on embedded systems with stripped-down versions of Unix tools like df. The returned disk data and alarms can be different when using this option.

The parameter is ignored on platforms that are known to not be POSIX compatible (Windows and SunOS).

See config for information about how to change the value of configuration parameters.

See Also

alarm_handler, os_mon

Summary

Types

time()

Time unit used for disklog APIs.

Functions

get_almost_full_threshold()

Returns the threshold, in percent, for disk space utilization.

get_check_interval()

Returns the time interval, in milliseconds, for the periodic disk space check.

get_disk_data()

Returns the result of the latest disk check.

get_disk_info()

Immediately fetches total space, available space and capacity for local disks.

get_disk_info(Path)

Immediately fetches total space, available space and capacity for a path.

set_almost_full_threshold(Float)

Changes the threshold, given as a float (0.0 =< Float =< 1.0), for disk space utilization.

set_check_interval(Value)

Changes the time interval for the periodic disk space check.

Types

time()

(not exported)

-type time() :: pos_integer() | {TimeUnit :: erlang:time_unit(), Time :: pos_integer()}.

Time unit used for disklog APIs.

Supported units are:

integer() >= 1 - The time interval in minutes.

{TimeUnit, Time} - The time interval Time in a time unit specified by TimeUnit where TimeUnit is of the type erlang:time_unit/0 and Time is a positive integer. The time interval needs to be at least one millisecond long.

Functions

get_almost_full_threshold()

-spec get_almost_full_threshold() -> Percent :: integer().

Returns the threshold, in percent, for disk space utilization.

get_check_interval()

-spec get_check_interval() -> Milliseconds :: timer:time().

Returns the time interval, in milliseconds, for the periodic disk space check.

get_disk_data()

-spec get_disk_data() -> [DiskData]
                       when
                           DiskData :: {Id, TotalKiB, Capacity},
                           Id :: string(),
                           TotalKiB :: integer(),
                           Capacity :: integer().

Returns the result of the latest disk check.

Id is a string that identifies the disk or partition. TotalKiB is the total size of the disk or partition in kibibytes. Capacity is the percentage of disk space used.

The function is asynchronous in the sense that it does not invoke a disk check, but returns the latest available value.

Returns [{"none",0,0}] if disksup is not available.

get_disk_info()

(since OTP 26.0)

-spec get_disk_info() -> [DiskData]
                       when
                           DiskData :: {Id, TotalKiB, AvailableKiB, Capacity},
                           Id :: string(),
                           TotalKiB :: integer(),
                           AvailableKiB :: integer(),
                           Capacity :: integer().

Immediately fetches total space, available space and capacity for local disks.

Id is a string that identifies the disk or partition. TotalKiB is the total size of the disk or partition in kibibytes. AvailableKiB is the disk space used in kibibytes. Capacity is the percentage of disk space used.

Returns [{"none",0,0,0}] if disksup is not available.

get_disk_info(Path)

(since OTP 26.0)

-spec get_disk_info(Path :: string()) -> [DiskData]
                       when
                           DiskData :: {Id, TotalKiB, AvailableKiB, Capacity},
                           Id :: string(),
                           TotalKiB :: integer(),
                           AvailableKiB :: integer(),
                           Capacity :: integer().

Immediately fetches total space, available space and capacity for a path.

Id is a string that identifies the disk or partition. TotalKiB is the total size of the disk or partition in kibibytes. AvailableKiB is the disk space used in kibibytes. Capacity is the percentage of disk space used.

Returns [{Path,0,0,0}] if the Path is invalid or space can't be determined. Returns [{"none",0,0,0}] if disksup is not available.

set_almost_full_threshold(Float)

-spec set_almost_full_threshold(Float :: float()) -> ok.

Changes the threshold, given as a float (0.0 =< Float =< 1.0), for disk space utilization.

The change will take effect during the next disk space check and is non-persist. That is, in case of a process restart, this value is forgotten and the default value will be used. See Configuration above.

set_check_interval(Value)

-spec set_check_interval(time()) -> ok.

Changes the time interval for the periodic disk space check.

The change will take effect after the next disk space check and is non-persist. That is, in case of a process restart, this value is forgotten and the default value will be used. See Configuration above.

memsup

A Memory Supervisor Process

memsup is a process which supervises the memory usage for the system and for individual processes. It is part of the OS_Mon application, see os_mon. Available for Unix and Windows.

Periodically performs a memory check:

If more than a certain amount of available system memory is allocated, as reported by the underlying operating system, the alarm {system_memory_high_watermark, []} is set. How the amount of available memory is determined depends on the underlying OS and may change as better values become available.

If any Erlang process Pid in the system has allocated more than a certain amount of total system memory, the alarm {process_memory_high_watermark, Pid} is set.

Alarms are reported to the SASL alarm handler, see alarm_handler. To set an alarm, alarm_handler:set_alarm(Alarm) is called where Alarm is either of the alarms specified above.

The alarms are cleared automatically when the alarm cause is no longer valid.

The function get_memory_data() can be used to retrieve the result of the latest periodic memory check.

There is also a interface to system dependent memory data, get_system_memory_data(). The result is highly dependent on the underlying operating system and the interface is targeted primarily for systems without virtual memory. However, the output on other systems is still valid, although sparse.

A call to get_system_memory_data/0 is more costly than a call to get_memory_data/0 as data is collected synchronously when this function is called.

The total system memory reported under UNIX is the number of physical pages of memory times the page size, and the available memory is the number of available physical pages times the page size. This is a reasonable measure as swapping should be avoided anyway, but the task of defining total memory and available memory is difficult because of virtual memory and swapping.

Configuration

The following configuration parameters can be used to change the default values for time intervals and thresholds:

memory_check_interval = int()>0 - The time interval, in minutes, for the periodic memory check. The default is one minute.

system_memory_high_watermark = float() - The threshold, as percentage of system memory, for how much system memory can be allocated before the corresponding alarm is set. The default is 0.80 (80%).

process_memory_high_watermark = float() - The threshold, as percentage of system memory, for how much system memory can be allocated by one Erlang process before the corresponding alarm is set. The default is 0.05 (5%).

memsup_helper_timeout = int()>0 - A timeout, in seconds, for how long the memsup process should wait for a result from a memory check. If the timeout expires, a warning message "OS_MON (memsup) timeout" is issued via error_logger and any pending, synchronous client calls will return a dummy value. Normally, this situation should not occur. There have been cases on Linux, however, where the pseudo file from which system data is read is temporarily unavailable when the system is heavily loaded.

The default is 30 seconds.

memsup_system_only = bool() - Specifies whether the memsup process should only check system memory usage (true) or not. The default is false, meaning that information regarding both system memory usage and Erlang process memory usage is collected.

It is recommended to set this parameter to true on systems with many concurrent processes, as each process memory check makes a traversal of the entire list of processes.

See config for information about how to change the value of configuration parameters.

See Also

alarm_handler, os_mon

Summary

Functions

get_check_interval()

Returns the time interval, in milliseconds, for the periodic memory check.

get_helper_timeout()

Returns the timeout value, in seconds, for memory checks.

get_memory_data()

Returns the result of the latest memory check, where Total is the total memory size and Allocated the allocated memory size, in bytes.

get_os_wordsize()

Returns the wordsize of the current running operating system.

get_procmem_high_watermark()

Returns the threshold, in percent, for process memory allocation.

get_sysmem_high_watermark()

Returns the threshold, in percent, for system memory allocation.

get_system_memory_data()

Invokes a memory check and returns the resulting, system dependent, data as a list of tagged tuples, where Tag currently can be one of the following

set_check_interval(Minutes)

Changes the time interval, given in minutes, for the periodic memory check.

set_helper_timeout(Seconds)

Changes the timeout value, given in seconds, for memory checks.

set_procmem_high_watermark(Float)

Changes the threshold, given as a float, for process memory allocation.

set_sysmem_high_watermark(Float)

Changes the threshold, given as a float, for system memory allocation.

Functions

get_check_interval()

-spec get_check_interval() -> Milliseconds :: timer:time().

Returns the time interval, in milliseconds, for the periodic memory check.

get_helper_timeout()

-spec get_helper_timeout() -> Seconds :: integer().

Returns the timeout value, in seconds, for memory checks.

get_memory_data()

-spec get_memory_data() -> {Total, Allocated, Worst}
                         when
                             Total :: integer(),
                             Allocated :: integer(),
                             Worst :: {Pid, PidAllocated} | undefined,
                             Pid :: pid(),
                             PidAllocated :: integer().

Returns the result of the latest memory check, where Total is the total memory size and Allocated the allocated memory size, in bytes.

Worst is the pid and number of allocated bytes of the largest Erlang process on the node. If memsup should not collect process data, that is if the configuration parameter memsup_system_only was set to true, Worst is undefined.

The function is normally asynchronous in the sense that it does not invoke a memory check, but returns the latest available value. The one exception if is the function is called before a first memory check is finished, in which case it does not return a value until the memory check is finished.

Returns {0,0,{pid(),0}} or {0,0,undefined} if memsup is not available, or if all memory checks so far have timed out.

get_os_wordsize()

-spec get_os_wordsize() -> Wordsize when Wordsize :: 32 | 64 | unsupported_os.

Returns the wordsize of the current running operating system.

get_procmem_high_watermark()

-spec get_procmem_high_watermark() -> integer().

Returns the threshold, in percent, for process memory allocation.

get_sysmem_high_watermark()

-spec get_sysmem_high_watermark() -> integer().

Returns the threshold, in percent, for system memory allocation.

get_system_memory_data()

-spec get_system_memory_data() -> MemDataList
                                when MemDataList :: [{Tag, Size}], Tag :: atom(), Size :: integer().

Invokes a memory check and returns the resulting, system dependent, data as a list of tagged tuples, where Tag currently can be one of the following:

total_memory - The total amount of memory available to the Erlang emulator, allocated and free. May or may not be equal to the amount of memory configured in the system.

available_memory - Informs about the amount memory that is available for increased usage if there is an increased memory need. This value is not based on a calculation of the other provided values and should give a better value of the amount of memory that actually is available than calculating a value based on the other values reported. This value is currently only present on newer Linux kernels. If this value is not available on Linux, you can use the sum of cached_memory, buffered_memory, and free_memory as an approximation.

free_memory - The amount of free memory available to the Erlang emulator for allocation.

system_total_memory - The amount of memory available to the whole operating system. This may well be equal to total_memory but not necessarily.

buffered_memory - The amount of memory the system uses for temporary storing raw disk blocks.

cached_memory - The amount of memory the system uses for cached files read from disk. On Linux, also memory marked as reclaimable in the kernel slab allocator will be added to this value.

total_swap - The amount of total amount of memory the system has available for disk swap.

free_swap - The amount of memory the system has available for disk swap.

Note

Note that new tagged tuples may be introduced in the result at any time without prior notice

Note that the order of the tuples in the resulting list is undefined and may change at any time.

All memory sizes are presented as number of bytes.

Returns the empty list [] if memsup is not available, or if the memory check times out.

set_check_interval(Minutes)

-spec set_check_interval(Minutes :: non_neg_integer()) -> ok.

Changes the time interval, given in minutes, for the periodic memory check.

The change will take effect after the next memory check and is non-persistent. That is, in case of a process restart, this value is forgotten and the default value will be used. See Configuration.

set_helper_timeout(Seconds)

-spec set_helper_timeout(Seconds :: non_neg_integer()) -> ok.

Changes the timeout value, given in seconds, for memory checks.

The change will take effect for the next memory check and is non-persistent. That is, in the case of a process restart, this value is forgotten and the default value will be used. See Configuration above.

set_procmem_high_watermark(Float)

-spec set_procmem_high_watermark(Float :: term()) -> ok.

Changes the threshold, given as a float, for process memory allocation.

The change will take effect during the next periodic memory check and is non-persistent. That is, in case of a process restart, this value is forgotten and the default value will be used. See Configuration.

set_sysmem_high_watermark(Float)

-spec set_sysmem_high_watermark(Float :: term()) -> ok.

Changes the threshold, given as a float, for system memory allocation.

The change will take effect during the next periodic memory check and is non-persistent. That is, in case of a process restart, this value is forgotten and the default value will be used. See Configuration above.

nteventlog

Interface to Windows Event Log

nteventlog provides a generic interface to the Windows event log. It is part of the OS_Mon application, see os_mon.

This module is used as the Windows backend for os_sup. See os_sup.

To retain backwards compatibility, this module can also be used to start a standalone nteventlog process which is not part of the OS_Mon supervision tree. When starting such a process, the user has to supply an identifier as well as a callback function to handle the messages.

The identifier, an arbitrary string, should be reused whenever the same application (or node) wants to start the process. nteventlog is informed about all events that have arrived to the eventlog since the last accepted message for the current identifier. As long as the same identifier is used, the same eventlog record will not be sent to nteventlog more than once (with the exception of when graved system failures arise, in which case the last records written before the failure may be sent to Erlang again after reboot).

If the event log is configured to wrap around automatically, records that have arrived to the log and been overwritten when nteventlog was not running are lost. However, it detects this state and loses no records that are not overwritten.

The callback function works as described in os_sup.

See Also

os_mon, os_sup

Windows NT documentation

Summary

Functions

start(Identifier, MFA)

Equivalent to start_link(Identifier, MFA) except that no link is created between nteventlog and the calling process.

start_link(Identifier, MFA)

This function starts the standalone nteventlog process and, if start_link/2 is used, links to it.

stop()

Stops nteventlog. Usually only used during development. The server does not have to be shut down gracefully to maintain its state.

Functions

start(Identifier, MFA)

-spec start(Identifier, MFA) -> Result
               when
                   Identifier :: string() | atom(),
                   MFA :: {Mod, Func, Args},
                   Mod :: atom(),
                   Func :: atom(),
                   Args :: [term()],
                   Result :: {ok, Pid} | {error, {already_started, Pid}},
                   Pid :: pid().

Equivalent to start_link(Identifier, MFA) except that no link is created between nteventlog and the calling process.

start_link(Identifier, MFA)

-spec start_link(Identifier, MFA) -> Result
                    when
                        Identifier :: string() | atom(),
                        MFA :: {Mod, Func, Args},
                        Mod :: atom(),
                        Func :: atom(),
                        Args :: [term()],
                        Result :: {ok, Pid} | {error, {already_started, Pid}},
                        Pid :: pid().

This function starts the standalone nteventlog process and, if start_link/2 is used, links to it.

Identifier is an identifier as described above.

MFA is the supplied callback function. When nteventlog receives information about a new event, this function will be called as apply(Mod, Func, [Event|Args]) where Event is a tuple

stop()

-spec stop() -> stopped.

Stops nteventlog. Usually only used during development. The server does not have to be shut down gracefully to maintain its state.

os_sup

Interface to OS System Messages

os_sup is a process providing a message passing service from the operating system to the error logger in the Erlang runtime system. It is part of the OS_Mon application, see os_mon. Available for Solaris and Windows.

Messages received from the operating system results in an user defined callback function being called. This function can do whatever filtering and formatting is necessary and then deploy any type of logging suitable for the user's application.

Solaris Operation

The Solaris (SunOS 5.x) messages are retrieved from the syslog daemon, syslogd.

Enabling the service includes actions which require root privileges, such as change of ownership and file privileges of an executable binary file, and creating a modified copy of the configuration file for syslogd. When os_sup is terminated, the service must be disabled, meaning the original configuration must be restored. Enabling/disabling can be done either outside or inside os_sup. See Configuration below.

Warning

This process cannot run in multiple instances on the same hardware. OS_Mon must be configured to start os_sup on one node only if two or more Erlang nodes execute on the same machine.

The format of received events is not defined.

Windows Operation

The Windows messages are retrieved from the eventlog file.

The nteventlog module is used to implement os_sup. See nteventlog. Note that the start functions of nteventlog does not need to be used, as in this case the process is started automatically as part of the OS_Mon supervision tree.

OS messages are formatted as a tuple {Time, Category, Facility, Severity, Message}:

Time = {MegaSecs, Secs, MicroSecs} - A time stamp as returned by the BIF now/0.

Category = string() - Usually one of "System", "Application" or "Security". Note that the NT eventlog viewer has another notion of category, which in most cases is totally meaningless and therefore not imported into Erlang. What is called a category here is one of the main three types of events occurring in a normal NT system.

Facility = string() - The source of the message, usually the name of the application that generated it. This could be almost any string. When matching messages from certain applications, the version number of the application may have to be accounted for. This is what the NT event viewer calls "source".

Severity = string() - One of "Error", "Warning", "Informational", "Audit_Success", "Audit_Faulure" or, in case of a currently unknown Windows NT version "Severity_Unknown".

Message = string() - Formatted exactly as it would be in the NT eventlog viewer. Binary data is not imported into Erlang.

Configuration

os_sup_mfa = {Module, Function, Args} - The callback function to use. Module and Function are atoms and Args is a list of terms. When an OS message Msg is received, this function is called as apply(Module, Function, [Msg | Args]).

Default is {os_sup, error_report, [Tag]} which will send the event to the error logger using error_logger:error_report(Tag, Msg). Tag is the value of os_sup_errortag, see below.

os_sup_errortag = atom() - This parameter defines the error report type used when messages are sent to error logger using the default callback function. Default is std_error, which means the events are handled by the standard event handler.

os_sup_enable = bool() - Solaris only. Defines if the service should be enabled (and disabled) inside (true) or outside (false) os_sup. For backwards compatibility reasons, the default is true. The recommended value is false, as the Erlang emulator should normally not be run with root privileges, as is required for enabling the service.

os_sup_own = string() - Solaris only. Defines the directory which contains the backup copy and the Erlang specific configuration files for syslogd, and a named pipe to receive the messages from syslogd. Default is "/etc".

os_sup_syslogconf = string() - Solaris only. Defines the full name of the configuration file for syslogd. Default is "/etc/syslog.conf".

See also

error_logger, os_mon

syslogd(1M), syslog.conf(4) in the Solaris documentation.

Summary

Functions

disable()

Equivalent to disable("/etc", "/etc/syslog.conf").

disable(Dir, Conf)

Disables the os_sup service. Needed on Solaris only.

enable()

Equivalent to enable("/etc", "/etc/syslog.conf").

enable(Dir, Conf)

Enables the os_sup service. Needed on Solaris only.

Functions

disable()

-spec disable() -> ok | {error, Res} when Res :: string().

Equivalent to disable("/etc", "/etc/syslog.conf").

disable(Dir, Conf)

-spec disable(Dir, Conf) -> ok | {error, Res} when Dir :: string(), Conf :: string(), Res :: string().

Disables the os_sup service. Needed on Solaris only.

If the configuration parameter os_sup_enable is false, this function is called automatically by os_sup, using the same arguments as when enable/2 was called.

If os_sup_enable is true, this function must be called after OS_Mon/os_sup is stopped. Dir defines the directory which contains the backup copy and the Erlang specific configuration files for syslogd, and a named pipe to receive the messages from syslogd. Defaults to "/etc". Conf defines the full name of the configuration file for syslogd. Default is "/etc/syslog.conf".

Results in a OS call to:

<PRIVDIR>/bin/mod_syslog nootp Dir Conf

where <PRIVDIR> is the priv directory of OS_Mon, code:priv_dir(os_mon).

Returns ok if this yields the expected result "0", and {error, Res} if it yields anything else.

Note

This function requires root privileges to succeed.

enable()

-spec enable() -> ok | {error, Res} when Res :: string().

Equivalent to enable("/etc", "/etc/syslog.conf").

enable(Dir, Conf)

-spec enable(Dir, Conf) -> ok | {error, Res} when Dir :: string(), Conf :: string(), Res :: string().

Enables the os_sup service. Needed on Solaris only.

If the configuration parameter os_sup_enable is false, this function is called automatically by os_sup, using the values of os_sup_own and os_sup_syslogconf as arguments.

If os_sup_enable is true, this function must be called before OS_Mon/os_sup is started. Dir defines the directory which contains the backup copy and the Erlang specific configuration files for syslogd, and a named pipe to receive the messages from syslogd. Defaults to "/etc". Conf defines the full name of the configuration file for syslogd. Default is "/etc/syslog.conf".

Results in a OS call to:

<PRIVDIR>/bin/mod_syslog otp Dir Conf

where <PRIVDIR> is the priv directory of OS_Mon, code:priv_dir(os_mon).

Returns ok if this yields the expected result "0", and {error, Res} if it yields anything else.

Note

This function requires root privileges to succeed.