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/Makefile | 124 +++++++++ lib/os_mon/doc/src/book.xml | 45 ++++ lib/os_mon/doc/src/cpu_sup.xml | 281 ++++++++++++++++++++ lib/os_mon/doc/src/disksup.xml | 161 ++++++++++++ lib/os_mon/doc/src/fascicules.xml | 15 ++ lib/os_mon/doc/src/make.dep | 21 ++ lib/os_mon/doc/src/memsup.xml | 328 +++++++++++++++++++++++ lib/os_mon/doc/src/note.gif | Bin 0 -> 1539 bytes lib/os_mon/doc/src/notes.xml | 537 ++++++++++++++++++++++++++++++++++++++ lib/os_mon/doc/src/nteventlog.xml | 104 ++++++++ lib/os_mon/doc/src/os_mon_app.xml | 126 +++++++++ lib/os_mon/doc/src/os_mon_mib.xml | 70 +++++ lib/os_mon/doc/src/os_sup.xml | 241 +++++++++++++++++ lib/os_mon/doc/src/part_notes.xml | 36 +++ lib/os_mon/doc/src/ref_man.xml | 42 +++ lib/os_mon/doc/src/user_guide.gif | Bin 0 -> 1581 bytes lib/os_mon/doc/src/warning.gif | Bin 0 -> 1498 bytes 17 files changed, 2131 insertions(+) create mode 100644 lib/os_mon/doc/src/Makefile create mode 100644 lib/os_mon/doc/src/book.xml create mode 100644 lib/os_mon/doc/src/cpu_sup.xml create mode 100644 lib/os_mon/doc/src/disksup.xml create mode 100644 lib/os_mon/doc/src/fascicules.xml create mode 100644 lib/os_mon/doc/src/make.dep create mode 100644 lib/os_mon/doc/src/memsup.xml create mode 100644 lib/os_mon/doc/src/note.gif create mode 100644 lib/os_mon/doc/src/notes.xml create mode 100644 lib/os_mon/doc/src/nteventlog.xml create mode 100644 lib/os_mon/doc/src/os_mon_app.xml create mode 100644 lib/os_mon/doc/src/os_mon_mib.xml create mode 100644 lib/os_mon/doc/src/os_sup.xml create mode 100644 lib/os_mon/doc/src/part_notes.xml create mode 100644 lib/os_mon/doc/src/ref_man.xml create mode 100644 lib/os_mon/doc/src/user_guide.gif create mode 100644 lib/os_mon/doc/src/warning.gif (limited to 'lib/os_mon/doc/src') diff --git a/lib/os_mon/doc/src/Makefile b/lib/os_mon/doc/src/Makefile new file mode 100644 index 0000000000..c9765749c9 --- /dev/null +++ b/lib/os_mon/doc/src/Makefile @@ -0,0 +1,124 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 1997-2009. 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. +# +# %CopyrightEnd% +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(OS_MON_VSN) +APPLICATION=os_mon + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XML_APPLICATION_FILES = ref_man.xml +XML_REF3_FILES = cpu_sup.xml \ + disksup.xml \ + memsup.xml \ + os_mon_mib.xml \ + os_sup.xml \ + nteventlog.xml + +XML_REF6_FILES = os_mon_app.xml + +XML_PART_FILES = part_notes.xml +XML_CHAPTER_FILES = notes.xml + +BOOK_FILES = book.xml + +GIF_FILES = \ + note.gif \ + warning.gif + +XML_FILES = \ + $(BOOK_FILES) $(XML_CHAPTER_FILES) \ + $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_REF6_FILES) $(XML_APPLICATION_FILES) + +# ---------------------------------------------------- + +HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + +INFO_FILE = ../../info + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) + +MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +man: $(MAN3_FILES) $(MAN6_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +debug opt: + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + $(INSTALL_DIR) $(RELEASE_PATH)/man/man6 + $(INSTALL_DATA) $(MAN6DIR)/* $(RELEASE_PATH)/man/man6 + +release_spec: + diff --git a/lib/os_mon/doc/src/book.xml b/lib/os_mon/doc/src/book.xml new file mode 100644 index 0000000000..17645b81fd --- /dev/null +++ b/lib/os_mon/doc/src/book.xml @@ -0,0 +1,45 @@ + + + + +
+ + 19972009 + 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. + + + + OS_Mon + + + + +
+ + + OS_Mon + + + + + + + + + + + + + diff --git a/lib/os_mon/doc/src/cpu_sup.xml b/lib/os_mon/doc/src/cpu_sup.xml new file mode 100644 index 0000000000..7b28083fbc --- /dev/null +++ b/lib/os_mon/doc/src/cpu_sup.xml @@ -0,0 +1,281 @@ + + + + +
+ + 19972009 + 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. + + + + cpu_sup + + + + +
+ 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 and Linux.

+

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

+ + + + nprocs() -> UnixProcesses | {error, Reason} + Get the number of UNIX processes running on this host + + UnixProcesses = int() + Reason = term() + + +

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.

+ + + + avg1() -> SystemLoad | {error, Reason} + Get the system load average for the last minute + + SystemLoad = int() + Reason = term() + + +

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() -> SystemLoad | {error, Reason} + Get the system load average for the last five minutes + + SystemLoad = int() + Reason = term() + + +

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() -> SystemLoad | {error, Reason} + Get the system load average for the last fifteen minutes + + SystemLoad = int() + Reason = term() + + +

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.

+ + + + util() -> CpuUtil | {error, Reason} + Get the CPU utilization + + CpuUtil = float() + Reason = term() + + +

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

+ +

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 below) in average on all CPUs.

+

Returns 0 if cpu_sup is not available.

+ + + + util(Opts) -> UtilSpec | {error, Reason} + Get the CPU utilization + + Opts = [detailed | per_cpu] + UtilSpec = UtilDesc | [UtilDesc] +  UtilDesc = {Cpus, Busy, NonBusy, Misc} +   Cpus = all | int() | [int()]() +   Busy = NonBusy = {State, Share} | Share +    State = user | nice_user | kernel +     | wait | idle | atom() +    Share = float() +   Misc = [] + Reason = term() + + +

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

+ +

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.

+ + + +

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.

+ + + + +
+ See Also +

os_mon(3)

+
+ + diff --git a/lib/os_mon/doc/src/disksup.xml b/lib/os_mon/doc/src/disksup.xml new file mode 100644 index 0000000000..bfa3d3578f --- /dev/null +++ b/lib/os_mon/doc/src/disksup.xml @@ -0,0 +1,161 @@ + + + + +
+ + 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. + + + + disksup + + + + +
+ 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(3). + 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 = int()>0 + +

The time interval, in minutes, 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%).

+ + +

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

+
+ + + get_disk_data() -> [DiskData] + Get data for the disks in the system + + DiskData = {Id, KByte, Capacity} +  Id = string() +  KByte = int() +  Capacity = int() + + +

Returns the result of the latest disk check. Id is a + string that identifies the disk or partition. KByte is + the total size of the disk or partition in kbytes. + 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_check_interval() -> MS + Get time interval, in milliseconds, for the periodic disk space check + + MS = int() + + +

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

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

Changes the time interval, given in minutes, 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.

+ + + + get_almost_full_threshold() -> Percent + Get threshold, in percent, for disk space utilization + + Percent = int() + + +

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

+ + + + set_almost_full_threshold(Float) -> ok + Set threshold, as percentage represented by a float, for disk space utilization + + Float = float(), 0=<Float=<1 + + +

Changes the threshold, given as a float, 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.

+ + + + +
+ See Also +

alarm_handler(3), + os_mon(3)

+
+ + diff --git a/lib/os_mon/doc/src/fascicules.xml b/lib/os_mon/doc/src/fascicules.xml new file mode 100644 index 0000000000..43090b4aed --- /dev/null +++ b/lib/os_mon/doc/src/fascicules.xml @@ -0,0 +1,15 @@ + + + + + + Reference Manual + + + Release Notes + + + Off-Print + + + diff --git a/lib/os_mon/doc/src/make.dep b/lib/os_mon/doc/src/make.dep new file mode 100644 index 0000000000..b657f2e036 --- /dev/null +++ b/lib/os_mon/doc/src/make.dep @@ -0,0 +1,21 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex cpu_sup.tex disksup.tex memsup.tex \ + nteventlog.tex os_mon.tex os_mon_mib.tex os_sup.tex \ + ref_man.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.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)

+
+ + diff --git a/lib/os_mon/doc/src/note.gif b/lib/os_mon/doc/src/note.gif new file mode 100644 index 0000000000..6fffe30419 Binary files /dev/null and b/lib/os_mon/doc/src/note.gif differ diff --git a/lib/os_mon/doc/src/notes.xml b/lib/os_mon/doc/src/notes.xml new file mode 100644 index 0000000000..1a8551f57d --- /dev/null +++ b/lib/os_mon/doc/src/notes.xml @@ -0,0 +1,537 @@ + + + + +
+ + 20042009 + 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. + + + + OS_Mon Release Notes + otp_appnotes + nil + nil + nil + notes.xml +
+

This document describes the changes made to the OS_Mon application.

+ +
Os_Mon 2.2.4 + +
Fixed Bugs and Malfunctions + + +

+ Memsup did not read memory correctly on MaxOSX + 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 then 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.

+
+ + diff --git a/lib/os_mon/doc/src/nteventlog.xml b/lib/os_mon/doc/src/nteventlog.xml new file mode 100644 index 0000000000..1e3fad90cd --- /dev/null +++ b/lib/os_mon/doc/src/nteventlog.xml @@ -0,0 +1,104 @@ + + + + +
+ + 19982009 + 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. + + + + nteventlog + + + + +
+ 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(6). Available for + Windows versions where the event log is available. That is, not + for Windows 98 and some other older Windows versions, but for most + (all?) newer Windows versions.

+

This module is used as the Windows backend for os_sup, see + os_sup(3).

+

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. It however detects + this state and loses no records that are not overwritten.

+

The callback function works as described in os_sup(3).

+ + + + start(Identifier, MFA) -> Result + start_link(Identifier, MFA) -> Result + Start the NT eventlog server + + Identifier = string() | atom() + MFA = {Mod, Func, Args} +  Mod = 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() -> stopped + Stop the NT eventlog server + + Result = stopped + + +

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

+ + + + +
+ See Also +

os_mon(6), + os_sup(3)

+

Windows NT documentation

+
+ + diff --git a/lib/os_mon/doc/src/os_mon_app.xml b/lib/os_mon/doc/src/os_mon_app.xml new file mode 100644 index 0000000000..8b44b70c5f --- /dev/null +++ b/lib/os_mon/doc/src/os_mon_app.xml @@ -0,0 +1,126 @@ + + + + +
+ + 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. + + + + os_mon + + + + +
+ os_mon + OS Monitoring Application + +

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, VxWorks) + 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(4) for + information about how to change the value of configuration + parameters.

+
+ +
+ SNMP MIBs +

The following MIBs are defined in OS_Mon:

+ + OTP-OS-MON-MIB + +

This MIB contains objects for instrumentation of disk, + memory and CPU usage of the nodes in the system.

+ + +

The MIB is stored in the mibs directory. It is defined + in SNMPv2 SMI syntax. An SNMPv1 version of the MIB is delivered + in the mibs/v1 directory.

+

The compiled MIB is located under priv/mibs, and + the generated .hrl file under the include directory. + To compile a MIB that IMPORTS the OTP-OS-MON-MIB, give + the option {il, ["os_mon/priv/mibs"]} to the MIB compiler.

+

If the MIB should be used in a system, it should be loaded into + an agent with a call to os_mon_mib:load(Agent), where + Agent is the pid or registered name of an SNMP agent. Use + os_mon_mib:unload(Agent) to unload the MIB. + The implementation of this MIB uses Mnesia to store a cache with + data needed, which implicates that Mnesia must be up and running. + The MIB also use functions defined for the OTP-MIB, thus + that MIB must be loaded as well.

+
+ +
+ See Also +

cpu_sup(3), + disksup(3), + memsup(3), + os_sup(3), + nteventlog(3), + snmp(3).

+
+ + diff --git a/lib/os_mon/doc/src/os_mon_mib.xml b/lib/os_mon/doc/src/os_mon_mib.xml new file mode 100644 index 0000000000..220d6a4a22 --- /dev/null +++ b/lib/os_mon/doc/src/os_mon_mib.xml @@ -0,0 +1,70 @@ + + + + +
+ + 20042009 + 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. + + + + os_mon_mib + Ingela Andin + + + + +
+ os_mon_mib + Loading and Unloading of OTP-OS-MON-MIB + +

Functions for loading and unloading the OTP-OS-MON-MIB into/from + an SNMP agent. The instrumentation of the OTP-OS-MON-MIB uses + Mnesia, hence Mnesia must be started prior to loading + the OTP-OS-MON-MIB.

+ + + + load(Agent) -> ok | {error, Reason} + Load the OTP-OS-MON-MIB + + Agent = pid() | atom() + Reason = term() + + +

Loads the OTP-OS-MON-MIB.

+ + + + unload(Agent) -> ok | {error, Reason} + Unload the OTP-OS-MON-MIB + + Agent = pid() | atom() + Reason = term() + + +

Unloads the OTP-OS-MON-MIB.

+ + + + +
+ See Also +

os_mon(6), + snmp(3)

+
+ + diff --git a/lib/os_mon/doc/src/os_sup.xml b/lib/os_mon/doc/src/os_sup.xml new file mode 100644 index 0000000000..792d18ba14 --- /dev/null +++ b/lib/os_mon/doc/src/os_sup.xml @@ -0,0 +1,241 @@ + + + + +
+ + 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. + + + + os_sup + + + + +
+ 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(6). 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.

+ +

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(3). Note + that the start functions of nteventlog does not need to be + used, 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().

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

+ + +
+ + + enable() -> ok | {error, Res} + enable(Dir, Conf) -> ok | {error, Error} + Enable the service (Solaris only) + + Dir = Conf = 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:

+ /bin/mod_syslog otp Dir Conf + ]]> +

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

+ +

This function requires root privileges to succeed.

+ + + + + disable() -> ok | {error, Res} + disable(Dir, Conf) -> ok | {error, Error} + Disable the service (Solaris only) + + Dir = Conf = 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:

+ /bin/mod_syslog nootp Dir Conf + ]]> +

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

+ +

This function requires root privileges to succeed.

+ + + + + +
+ See also +

error_logger(3), + os_mon(3)

+

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

+

+
+ + diff --git a/lib/os_mon/doc/src/part_notes.xml b/lib/os_mon/doc/src/part_notes.xml new file mode 100644 index 0000000000..8fe226f53e --- /dev/null +++ b/lib/os_mon/doc/src/part_notes.xml @@ -0,0 +1,36 @@ + + + + +
+ + 20042009 + 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. + + + + OS_Mon Release Notes + + + + +
+ +

The operating system monitor, OS_Mon, provides services for + monitoring CPU load, disk usage, memory usage and OS messages.

+ + + + diff --git a/lib/os_mon/doc/src/ref_man.xml b/lib/os_mon/doc/src/ref_man.xml new file mode 100644 index 0000000000..5a50c122fd --- /dev/null +++ b/lib/os_mon/doc/src/ref_man.xml @@ -0,0 +1,42 @@ + + + + +
+ + 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. + + + + OS_Mon Reference Manual + + + + +
+ +

The operating system monitor, OS_Mon, provides services for + monitoring CPU load, disk usage, memory usage and OS messages.

+ + + + + + + + + + diff --git a/lib/os_mon/doc/src/user_guide.gif b/lib/os_mon/doc/src/user_guide.gif new file mode 100644 index 0000000000..e6275a803d Binary files /dev/null and b/lib/os_mon/doc/src/user_guide.gif differ diff --git a/lib/os_mon/doc/src/warning.gif b/lib/os_mon/doc/src/warning.gif new file mode 100644 index 0000000000..96af52360e Binary files /dev/null and b/lib/os_mon/doc/src/warning.gif differ -- cgit v1.2.3