aboutsummaryrefslogtreecommitdiffstats
path: root/lib/os_mon/doc/src/memsup.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/os_mon/doc/src/memsup.xml')
-rw-r--r--lib/os_mon/doc/src/memsup.xml328
1 files changed, 328 insertions, 0 deletions
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 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ 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.
+
+ </legalnotice>
+
+ <title>memsup</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>memsup</module>
+ <modulesummary>A Memory Supervisor Process</modulesummary>
+ <description>
+ <p><c>memsup</c> is a process which supervises the memory usage for
+ the system and for individual processes. It is part of the OS_Mon
+ application, see <seealso marker="os_mon_app">os_mon(6)</seealso>.
+ Available for Unix, Windows and VxWorks.</p>
+ <p>Periodically performs a memory check:</p>
+ <list type="bulleted">
+ <item>
+ <p>If more than a certain amount of available system memory is
+ allocated, as reported by the underlying operating system,
+ the alarm <c>{system_memory_high_watermark, []}</c> is set.</p>
+ </item>
+ <item>
+ <p>If any Erlang process <c>Pid</c> in the system has allocated
+ more than a certain amount of total system memory, the alarm
+ <c>{process_memory_high_watermark, Pid}</c> is set.</p>
+ </item>
+ </list>
+ <p>Alarms are reported to the SASL alarm handler, see
+ <seealso marker="sasl:alarm_handler">alarm_handler(3)</seealso>.
+ To set an alarm, <c>alarm_handler:set_alarm(Alarm)</c> is called
+ where <c>Alarm</c> is either of the alarms specified above.</p>
+ <p>The alarms are cleared automatically when the alarm cause is no
+ longer valid.</p>
+ <p>The function
+ <seealso marker="#get_memory_data/0">get_memory_data()</seealso>
+ can be used to retrieve the result of the latest periodic memory
+ check.</p>
+ <p>There is also a interface to system dependent memory data,
+ <seealso marker="#get_system_memory_data/0">get_system_memory_data()</seealso>.
+ 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.</p>
+ <p>A call to <c>get_system_memory_data/0</c> is more costly
+ than a call to <c>get_memory_data/0</c> as data is collected
+ synchronously when this function is called.</p>
+ <p>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.</p>
+ </description>
+
+ <section>
+ <marker id="config"></marker>
+ <title>Configuration</title>
+ <p>The following configuration parameters can be used to change
+ the default values for time intervals and thresholds:</p>
+ <taglist>
+ <tag><c>memory_check_interval = int()>0</c></tag>
+ <item>
+ <p>The time interval, in minutes, for the periodic memory check.
+ The default is one minute.</p>
+ </item>
+ <tag><c>system_memory_high_watermark = float()</c></tag>
+ <item>
+ <p>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%).</p>
+ </item>
+ <tag><c>process_memory_high_watermark = float()</c></tag>
+ <item>
+ <p>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%).</p>
+ </item>
+ <tag><c>memsup_helper_timeout = int()>0</c></tag>
+ <item>
+ <p>A timeout, in seconds, for how long the <c>memsup</c>
+ process should wait for a result from a memory check. If
+ the timeout expires, a warning message <c>"OS_MON (memsup) timeout"</c> is issued via <c>error_logger</c> 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.</p>
+ <p>The default is 30 seconds. </p>
+ </item>
+ <tag><c>memsup_system_only = bool()</c></tag>
+ <item>
+ <p>Specifies whether the <c>memsup</c> process should only
+ check system memory usage (<c>true</c>) or not. The default is
+ <c>false</c>, meaning that information regarding both system
+ memory usage and Erlang process memory usage is collected.</p>
+ <p>It is recommended to set this parameter to <c>false</c> on
+ systems with many concurrent processes, as each process memory
+ check makes a traversal of the entire list of processes.</p>
+ </item>
+ </taglist>
+ <p>See <seealso marker="kernel:config">config(4)</seealso> for
+ information about how to change the value of configuration
+ parameters.</p>
+ </section>
+ <funcs>
+ <func>
+ <name>get_memory_data() -> {Total,Allocated,Worst}</name>
+ <fsummary>Get data for the memory in the system</fsummary>
+ <type>
+ <v>Total = Allocated = int()</v>
+ <v>Worst = {Pid, PidAllocated} | undefined</v>
+ <v>&nbsp;Pid = pid()</v>
+ <v>&nbsp;PidAllocated = int()</v>
+ </type>
+ <desc>
+ <p>Returns the result of the latest memory check, where
+ <c>Total</c> is the total memory size and <c>Allocated</c>
+ the allocated memory size, in bytes.</p>
+ <p><c>Worst</c> is the pid and number of allocated bytes of
+ the largest Erlang process on the node. If <c>memsup</c>
+ should not collect process data, that is if the configuration
+ parameter <c>memsup_system_only</c> was set to <c>true</c>,
+ <c>Worst</c> is <c>undefined</c>.</p>
+ <p>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.</p>
+ <p>Returns <c>{0,0,{pid(),0}}</c> or <c>{0,0,undefined}</c> if
+ <c>memsup</c> is not available, or if all memory checks so far
+ have timed out.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_system_memory_data() -> MemDataList</name>
+ <fsummary>Get system dependent memory data</fsummary>
+ <type>
+ <v>MemDataList = [{Tag, Size}]</v>
+ <v>&nbsp;Tag = atom()</v>
+ <v>&nbsp;Size = int()</v>
+ </type>
+ <desc>
+ <p>Invokes a memory check and returns the resulting, system
+ dependent, data as a list of tagged tuples, where <c>Tag</c>
+ can be one of the following:</p>
+ <taglist>
+ <tag><c>total_memory</c></tag>
+ <item>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.</item>
+ <tag><c>free_memory</c></tag>
+ <item>The amount of free memory available to the Erlang emulator
+ for allocation.</item>
+ <tag><c>system_total_memory</c></tag>
+ <item>The amount of memory available to the whole operating
+ system. This may well be equal to <c>total_memory</c> but
+ not necessarily.</item>
+ <tag><c>largest_free</c></tag>
+ <item>The size of the largest contiguous free memory block
+ available to the Erlang emulator.</item>
+ <tag><c>number_of_free</c></tag>
+ <item>The number of free blocks available to the Erlang runtime
+ system. This gives a fair indication of how fragmented
+ the memory is.</item>
+ <tag><c>buffered_memory</c></tag>
+ <item>
+ The amount of memory the system uses for temporary storing raw disk blocks.
+ </item>
+ <tag><c>cached_memory</c></tag>
+ <item>
+ The amount of memory the system uses for cached files read from disk.
+ </item>
+ <tag><c>total_swap</c></tag>
+ <item>
+ The amount of total amount of memory the system has available
+ for disk swap.
+ </item>
+ <tag><c>free_swap</c></tag>
+ <item>
+ The amount of memory the system has available for disk swap.
+ </item>
+
+ </taglist>
+ <p>All memory sizes are presented as number of <em>bytes</em>.</p>
+ <p>The <c>largest_free</c> and <c>number_of_free</c> tags are
+ currently only returned on a VxWorks system.</p>
+ <p>Returns the empty list [] if <c>memsup</c> is not available,
+ or if the memory check times out.</p>
+ <note><p>
+ On linux the memory available to the emulator is <c>cached_memory</c> and <c>buffered_memory</c> in addition to
+ <c>free_memory</c>.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>get_os_wordsize() -> Wordsize</name>
+ <fsummary>Get the wordsize of running os.</fsummary>
+ <type>
+ <v>Wordsize = 32 | 64 | unsupported_os</v>
+ </type>
+ <desc>
+ <p>Returns the wordsize of the current running operating system. </p>
+ </desc>
+ </func>
+ <func>
+ <name>get_check_interval() -> MS</name>
+ <fsummary>Get time interval, in milliseconds, for the periodic memory check</fsummary>
+ <type>
+ <v>MS = int()</v>
+ </type>
+ <desc>
+ <p>Returns the time interval, in milliseconds, for the periodic
+ memory check.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_check_interval(Minutes) -> ok</name>
+ <fsummary>Set time interval, in minutes, for the periodic memory check</fsummary>
+ <type>
+ <v>Minutes = int()>0</v>
+ </type>
+ <desc>
+ <p>Changes the time interval, given in minutes, for the periodic
+ memory check.</p>
+ <p>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
+ <seealso marker="#config">Configuration</seealso> above.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_procmem_high_watermark() -> int()</name>
+ <fsummary>Get threshold, in percent, for process memory allocation</fsummary>
+ <desc>
+ <p>Returns the threshold, in percent, for process memory
+ allocation.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_procmem_high_watermark(Float) -> ok</name>
+ <fsummary>Set threshold, as percentage represented by a float, for process memory allocation</fsummary>
+ <desc>
+ <p>Changes the threshold, given as a float, for process memory
+ allocation.</p>
+ <p>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 <seealso marker="#config">Configuration</seealso>
+ above.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_sysmem_high_watermark() -> int()</name>
+ <fsummary>Get threshold, in percent, for system memory allocation</fsummary>
+ <desc>
+ <p>Returns the threshold, in percent, for system memory
+ allocation.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_sysmem_high_watermark(Float) -> ok</name>
+ <fsummary>Set threshold, given as a float, for system memory allocation</fsummary>
+ <desc>
+ <p>Changes the threshold, given as a float, for system memory
+ allocation.</p>
+ <p>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 <seealso marker="#config">Configuration</seealso>
+ above.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_helper_timeout() -> Seconds</name>
+ <fsummary>Get the timeout value, in seconds, for memory checks</fsummary>
+ <type>
+ <v>Seconds = int()</v>
+ </type>
+ <desc>
+ <p>Returns the timeout value, in seconds, for memory checks.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_helper_timeout(Seconds) -> ok</name>
+ <fsummary>Set the timeout value, in seconds, for memory checks</fsummary>
+ <type>
+ <v>Seconds = int() (>= 1)</v>
+ </type>
+ <desc>
+ <p>Changes the timeout value, given in seconds, for memory
+ checks.</p>
+ <p>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
+ <seealso marker="#config">Configuration</seealso> above.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>See Also</title>
+ <p><seealso marker="sasl:alarm_handler">alarm_handler(3)</seealso>,
+ <seealso marker="os_mon_app">os_mon(3)</seealso></p>
+ </section>
+</erlref>
+