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 and Windows.
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 op‐
35       erating  system  and  the  interface  is targeted primarily for systems
36       without virtual memory. However, the output on other systems  is  still
37       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  de‐
52       fault 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 currently can
130              be one of 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                available_memory:
138                  Informs about the amount memory that is  available  for  in‐
139                  creased  usage  if  there  is an increased memory need. This
140                  value is not based on a calculation of  the  other  provided
141                  values  and should give a better value of the amount of mem‐
142                  ory that actually is  available  than  calculating  a  value
143                  based  on the other values reported. This value is currently
144                  only present on newer Linux kernels. If this  value  is  not
145                  available  on  Linux,  you can use the sum of cached_memory,
146                  buffered_memory, and free_memory as an approximation.
147
148                free_memory:
149                  The amount of free memory available to the  Erlang  emulator
150                  for allocation.
151
152                system_total_memory:
153                  The  amount  of memory available to the whole operating sys‐
154                  tem. This may well be equal to total_memory but  not  neces‐
155                  sarily.
156
157                buffered_memory:
158                   The  amount of memory the system uses for temporary storing
159                  raw disk blocks.
160
161                cached_memory:
162                   The amount of memory the system uses for cached files  read
163                  from  disk.  On  Linux, also memory marked as reclaimable in
164                  the kernel slab allocator will be added to this value.
165
166                total_swap:
167                   The amount of total amount of memory the system has  avail‐
168                  able for disk swap.
169
170                free_swap:
171                   The  amount  of  memory  the  system has available for disk
172                  swap.
173
174          Note:
175              Note that new tagged tuples may be introduced in the  result  at
176              any time without prior notice
177
178
179              Note that the order of the tuples in the resulting list is unde‐
180              fined and may change at any time.
181
182              All memory sizes are presented as number of bytes.
183
184              Returns the empty list [] if memsup is not available, or if  the
185              memory check times out.
186
187       get_os_wordsize() -> Wordsize
188
189              Types:
190
191                 Wordsize = 32 | 64 | unsupported_os
192
193              Returns the wordsize of the current running operating system.
194
195       get_check_interval() -> MS
196
197              Types:
198
199                 MS = int()
200
201              Returns  the  time  interval,  in milliseconds, for the periodic
202              memory check.
203
204       set_check_interval(Minutes) -> ok
205
206              Types:
207
208                 Minutes = int()>0
209
210              Changes the time interval, given in minutes,  for  the  periodic
211              memory check.
212
213              The  change  will take effect after the next memory check and is
214              non-persistent. That is, in case  of  a  process  restart,  this
215              value  is forgotten and the default value will be used. See Con‐
216              figuration above.
217
218       get_procmem_high_watermark() -> int()
219
220              Returns the threshold, in percent, for  process  memory  alloca‐
221              tion.
222
223       set_procmem_high_watermark(Float) -> ok
224
225              Changes  the threshold, given as a float, for process memory al‐
226              location.
227
228              The change will take effect  during  the  next  periodic  memory
229              check  and  is  non-persistent.  That  is,  in case of a process
230              restart, this value is forgotten and the default value  will  be
231              used. See Configuration above.
232
233       get_sysmem_high_watermark() -> int()
234
235              Returns the threshold, in percent, for system memory allocation.
236
237       set_sysmem_high_watermark(Float) -> ok
238
239              Changes the threshold, given as a float, for system memory allo‐
240              cation.
241
242              The change will take effect  during  the  next  periodic  memory
243              check  and  is  non-persistent.  That  is,  in case of a process
244              restart, this value is forgotten and the default value  will  be
245              used. See Configuration above.
246
247       get_helper_timeout() -> Seconds
248
249              Types:
250
251                 Seconds = int()
252
253              Returns the timeout value, in seconds, for memory checks.
254
255       set_helper_timeout(Seconds) -> ok
256
257              Types:
258
259                 Seconds = int() (>= 1)
260
261              Changes the timeout value, given in seconds, for memory checks.
262
263              The  change  will  take  effect for the next memory check and is
264              non-persistent. That is, in the case of a process restart,  this
265              value  is forgotten and the default value will be used. See Con‐
266              figuration above.
267

SEE ALSO

269       alarm_handler(3), os_mon(3)
270
271
272
273Ericsson AB                      os_mon 2.8.2                        memsup(3)
Impressum