From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/os_mon/doc/src/memsup.xml | 328 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 lib/os_mon/doc/src/memsup.xml (limited to 'lib/os_mon/doc/src/memsup.xml') diff --git a/lib/os_mon/doc/src/memsup.xml b/lib/os_mon/doc/src/memsup.xml new file mode 100644 index 0000000000..67d617375e --- /dev/null +++ b/lib/os_mon/doc/src/memsup.xml @@ -0,0 +1,328 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + memsup + + + + +
+ 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(6). + Available for Unix, Windows and VxWorks.

+

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.

+ + +

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(3). + 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 (e.g. VxWorks). The output on other + systems is however 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 false on + systems with many concurrent processes, as each process memory + check makes a traversal of the entire list of processes.

+ + +

See config(4) for + information about how to change the value of configuration + parameters.

+
+ + + get_memory_data() -> {Total,Allocated,Worst} + Get data for the memory in the system + + Total = Allocated = int() + Worst = {Pid, PidAllocated} | undefined +  Pid = pid() +  PidAllocated = int() + + +

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_system_memory_data() -> MemDataList + Get system dependent memory data + + MemDataList = [{Tag, Size}] +  Tag = atom() +  Size = int() + + +

Invokes a memory check and returns the resulting, system + dependent, data as a list of tagged tuples, where Tag + 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. + 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. + largest_free + The size of the largest contiguous free memory block + available to the Erlang emulator. + number_of_free + The number of free blocks available to the Erlang runtime + system. This gives a fair indication of how fragmented + the memory is. + 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. + + 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. + + + +

All memory sizes are presented as number of bytes.

+

The largest_free and number_of_free tags are + currently only returned on a VxWorks system.

+

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

+

+ On linux the memory available to the emulator is cached_memory and buffered_memory in addition to + free_memory.

+ + + + + get_os_wordsize() -> Wordsize + Get the wordsize of running os. + + Wordsize = 32 | 64 | unsupported_os + + +

Returns the wordsize of the current running operating system.

+ + + + get_check_interval() -> MS + Get time interval, in milliseconds, for the periodic memory check + + MS = int() + + +

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

+ + + + set_check_interval(Minutes) -> ok + Set time interval, in minutes, for the periodic memory check + + Minutes = int()>0 + + +

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

+ + + + get_procmem_high_watermark() -> int() + Get threshold, in percent, for process memory allocation + +

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

+ + + + set_procmem_high_watermark(Float) -> ok + Set threshold, as percentage represented by a float, for process memory allocation + +

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

+ + + + get_sysmem_high_watermark() -> int() + Get threshold, in percent, for system memory allocation + +

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

+ + + + set_sysmem_high_watermark(Float) -> ok + Set threshold, given as a float, for system memory allocation + +

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.

+ + + + get_helper_timeout() -> Seconds + Get the timeout value, in seconds, for memory checks + + Seconds = int() + + +

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

+ + + + set_helper_timeout(Seconds) -> ok + Set the timeout value, in seconds, for memory checks + + Seconds = int() (>= 1) + + +

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.

+ + + + +
+ See Also +

alarm_handler(3), + os_mon(3)

+
+ + -- cgit v1.2.3