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

NAME

6       memsup - A Memory Supervisor Process
7

DESCRIPTION

9       memsup  is  a  process which supervises the memory usage for the system
10       and for individual processes. It is part of the OS_Mon application, see
11       os_mon(6). Available for Unix, Windows and VxWorks.
12
13       Periodically performs a memory check:
14
15         * If  more  than a certain amount of available system memory is allo‐
16           cated, as reported by the underlying operating  system,  the  alarm
17           {system_memory_high_watermark, []} is set.
18
19         * If  any  Erlang process Pid in the system has allocated more than a
20           certain amount of total  system  memory,  the  alarm  {process_mem‐
21           ory_high_watermark, Pid} is set.
22
23       Alarms are reported to the SASL alarm handler, see alarm_handler(3). To
24       set an alarm, alarm_handler:set_alarm(Alarm) is called where  Alarm  is
25       either of the alarms specified above.
26
27       The  alarms are cleared automatically when the alarm cause is no longer
28       valid.
29
30       The function get_memory_data() can be used to retrieve  the  result  of
31       the latest periodic memory check.
32
33       There  is  also  a  interface to system dependent memory data, get_sys‐
34       tem_memory_data(). The result is highly  dependent  on  the  underlying
35       operating  system  and  the interface is targeted primarily for systems
36       without virtual memory (e.g. VxWorks). The output on other  systems  is
37       however still valid, although sparse.
38
39       A  call  to  get_system_memory_data/0  is  more  costly  than a call to
40       get_memory_data/0 as data is collected synchronously when this function
41       is called.
42
43       The  total  system memory reported under UNIX is the number of physical
44       pages of memory times the page size, and the available  memory  is  the
45       number  of available physical pages times the page size. This is a rea‐
46       sonable measure as swapping should be avoided anyway, but the  task  of
47       defining total memory and available memory is difficult because of vir‐
48       tual memory and swapping.
49

CONFIGURATION

51       The following configuration  parameters  can  be  used  to  change  the
52       default values for time intervals and thresholds:
53
54         memory_check_interval = int()>0:
55           The  time  interval, in minutes, for the periodic memory check. The
56           default is one minute.
57
58         system_memory_high_watermark = float():
59           The threshold, as percentage of system memory, for how much  system
60           memory  can be allocated before the corresponding alarm is set. The
61           default is 0.80 (80%).
62
63         process_memory_high_watermark = float():
64           The threshold, as percentage of system memory, for how much  system
65           memory  can  be  allocated  by one Erlang process before the corre‐
66           sponding alarm is set. The default is 0.05 (5%).
67
68         memsup_helper_timeout = int()>0:
69           A timeout, in seconds, for how long the memsup process should  wait
70           for a result from a memory check. If the timeout expires, a warning
71           message "OS_MON (memsup) timeout" is issued  via  error_logger  and
72           any  pending,  synchronous  client calls will return a dummy value.
73           Normally, this situation should not occur. There have been cases on
74           Linux,  however,  where  the  pseudo file from which system data is
75           read is temporarily unavailable when the system is heavily loaded.
76
77           The default is 30 seconds.
78
79         memsup_system_only = bool():
80           Specifies whether the memsup process should only check system  mem‐
81           ory  usage (true) or not. The default is false, meaning that infor‐
82           mation regarding both system memory usage and Erlang process memory
83           usage is collected.
84
85           It  is  recommended  to set this parameter to false on systems with
86           many concurrent processes, as each process  memory  check  makes  a
87           traversal of the entire list of processes.
88
89       See config(4) for information about how to change the value of configu‐
90       ration parameters.
91

EXPORTS

93       get_memory_data() -> {Total,Allocated,Worst}
94
95              Types:
96
97                 Total = Allocated = int()
98                 Worst = {Pid, PidAllocated} | undefined
99                  Pid = pid()
100                  PidAllocated = int()
101
102              Returns the result of the latest memory check,  where  Total  is
103              the  total  memory size and Allocated the allocated memory size,
104              in bytes.
105
106              Worst is the pid and number of allocated bytes  of  the  largest
107              Erlang process on the node. If memsup should not collect process
108              data, that is if the configuration parameter  memsup_system_only
109              was set to true, Worst is undefined.
110
111              The  function is normally asynchronous in the sense that it does
112              not invoke a memory check,  but  returns  the  latest  available
113              value.  The  one exception if is the function is called before a
114              first memory check is finished, in which case it does not return
115              a value until the memory check is finished.
116
117              Returns  {0,0,{pid(),0}}  or  {0,0,undefined}  if  memsup is not
118              available, or if all memory checks so far have timed out.
119
120       get_system_memory_data() -> MemDataList
121
122              Types:
123
124                 MemDataList = [{Tag, Size}]
125                  Tag = atom()
126                  Size = int()
127
128              Invokes a memory check and returns the resulting, system  depen‐
129              dent,  data  as a list of tagged tuples, where Tag can be one of
130              the following:
131
132                total_memory:
133                  The total amount of memory available to the Erlang emulator,
134                  allocated and free. May or may not be equal to the amount of
135                  memory configured in the system.
136
137                free_memory:
138                  The amount of free memory available to the  Erlang  emulator
139                  for allocation.
140
141                system_total_memory:
142                  The  amount  of memory available to the whole operating sys‐
143                  tem. This may well be equal to total_memory but  not  neces‐
144                  sarily.
145
146                largest_free:
147                  The  size of the largest contiguous free memory block avail‐
148                  able to the Erlang emulator.
149
150                number_of_free:
151                  The number of free blocks available to  the  Erlang  runtime
152                  system.  This  gives a fair indication of how fragmented the
153                  memory is.
154
155                buffered_memory:
156                   The amount of memory the system uses for temporary  storing
157                  raw disk blocks.
158
159                cached_memory:
160                   The  amount of memory the system uses for cached files read
161                  from disk.
162
163                total_swap:
164                   The amount of total amount of memory the system has  avail‐
165                  able for disk swap.
166
167                free_swap:
168                   The  amount  of  memory  the  system has available for disk
169                  swap.
170
171              All memory sizes are presented as number of bytes.
172
173              The largest_free and  number_of_free  tags  are  currently  only
174              returned on a VxWorks system.
175
176              Returns  the empty list [] if memsup is not available, or if the
177              memory check times out.
178
179          Note:
180              On linux the memory available to the emulator  is  cached_memory
181              and buffered_memory in addition to free_memory.
182
183
184       get_os_wordsize() -> Wordsize
185
186              Types:
187
188                 Wordsize = 32 | 64 | unsupported_os
189
190              Returns the wordsize of the current running operating system.
191
192       get_check_interval() -> MS
193
194              Types:
195
196                 MS = int()
197
198              Returns  the  time  interval,  in milliseconds, for the periodic
199              memory check.
200
201       set_check_interval(Minutes) -> ok
202
203              Types:
204
205                 Minutes = int()>0
206
207              Changes the time interval, given in minutes,  for  the  periodic
208              memory check.
209
210              The  change  will take effect after the next memory check and is
211              non-persistent. That is, in case  of  a  process  restart,  this
212              value  is forgotten and the default value will be used. See Con‐
213              figuration above.
214
215       get_procmem_high_watermark() -> int()
216
217              Returns the threshold, in percent, for  process  memory  alloca‐
218              tion.
219
220       set_procmem_high_watermark(Float) -> ok
221
222              Changes  the  threshold,  given  as  a float, for process memory
223              allocation.
224
225              The change will take effect  during  the  next  periodic  memory
226              check  and  is  non-persistent.  That  is,  in case of a process
227              restart, this value is forgotten and the default value  will  be
228              used. See Configuration above.
229
230       get_sysmem_high_watermark() -> int()
231
232              Returns the threshold, in percent, for system memory allocation.
233
234       set_sysmem_high_watermark(Float) -> ok
235
236              Changes the threshold, given as a float, for system memory allo‐
237              cation.
238
239              The change will take effect  during  the  next  periodic  memory
240              check  and  is  non-persistent.  That  is,  in case of a process
241              restart, this value is forgotten and the default value  will  be
242              used. See Configuration above.
243
244       get_helper_timeout() -> Seconds
245
246              Types:
247
248                 Seconds = int()
249
250              Returns the timeout value, in seconds, for memory checks.
251
252       set_helper_timeout(Seconds) -> ok
253
254              Types:
255
256                 Seconds = int() (>= 1)
257
258              Changes the timeout value, given in seconds, for memory checks.
259
260              The  change  will  take  effect for the next memory check and is
261              non-persistent. That is, in the case of a process restart,  this
262              value  is forgotten and the default value will be used. See Con‐
263              figuration above.
264

SEE ALSO

266       alarm_handler(3), os_mon(3)
267
268
269
270Ericsson AB                      os_mon 2.4.7                        memsup(3)
Impressum