.. highlight:: rst

.. _scm:

###
scm
###

**Process monitor.**


Description
===========

scm monitors client activity. scm connects to a certain master and periodically
processes the status messages sent by the clients.

Each client status if forwarded to the plugins loaded by scm. By default
the :ref:`mncursesplugin <scm_ncurses>` is loaded which presents an interface
similar to the gnu program top.

Filters
=======

Plugins might support filtering client status information. To configure filters
each plugin supports a configuration value :confval:`$name.filter`. This filter
is a string which can be constructed from available status info tags and logical
and numerical operators.

List of tags:

.. code-block:: sh

   time
   privategroup
   hostname
   clientname
   ips
   programname
   pid
   cpuusage
   totalmemory
   clientmemoryusage
   memoryusage
   sentmessages
   receivedmessages
   messagequeuesize
   summedmessagequeuesize
   averagemessagequeuesize
   summedmessagesize
   averagemessagesize
   objectcount
   uptime
   responsetime

A filter might look like this:

.. code-block:: sh

   memailplugin.filter = "(cpuusage>100 || totalmemory>1000) && hostname==proc-machine"


Numerical operators
-------------------

Numerical operators are applied to a tag name and a constant value.

========  =================
Operator  Description
========  =================
==        equal
!=        not equal
<         less than
>         greater than
<=        less or equal
>=        greater or equal
========  =================


Logical operators
-----------------

Logical operators are applied to a group (might be enclosed in brackets) or
numerical expressions.

========  =================
Operator  Description
========  =================
!         not
&&        and
||        or
========  =================


Multiple instances
==================

To monitor different clients sets with different criteria and different plugins
it is common practice to create aliases of scm and to configure each instance
separately

.. code-block:: sh

   seiscomp alias create scm_level1 scm
   seiscomp alias create scm_level2 scm

where :program:`scm_level1` could monitor all mandatory clients whereas
:program:`scm_level2` monitors all clients which are not crucial for operation.



Plugins
=======

* :ref:`text <scm_text>`

  Text output plugin for scm.
* :ref:`email <scm_email>`

  Email plugin for scm which sends emails based on client status.
* :ref:`ncurses <scm_ncurses>`

  Ncurses output plugin for scm which presents an interactive table of processes.

.. _scm_configuration:

Module Configuration
====================

| :file:`etc/defaults/global.cfg`
| :file:`etc/defaults/scm.cfg`
| :file:`etc/global.cfg`
| :file:`etc/scm.cfg`
| :file:`~/.seiscomp/global.cfg`
| :file:`~/.seiscomp/scm.cfg`

scm inherits :ref:`global options<global-configuration>`.



.. _scm/text:


text extension
--------------

Text output plugin for scm.


.. confval:: mtextplugin.outputDir

   Default: ``@LOGDIR@/scm/``

   Type: *string*

   Output directory where [client].txt is written to. Additionally
   an file description.txt will be created to show the order of
   tags used in the client status file.


.. _scm/email:


email extension
---------------

Email plugin for scm which sends emails based on client status.


.. confval:: memailplugin.recipients

   Type: *list:string*

   Defines a comma separated list of email addresses to send
   notifications to.


.. confval:: memailplugin.template

   Type: *string*

   Configures a custom message text that is appended to each message
   when clients passed the filter.


.. confval:: memailplugin.filter

   Type: *string*

   Defines the filter for each client status. A filter is an expression
   that can be constructed with all available status tags \(scm \-\-print\-tags\)
   and logical and numerical operators. See scm for more information.


.. confval:: memailplugin.requiredClients

   Type: *list:string*

   *No description available*

.. confval:: memailplugin.reportSilentClients

   Default: ``true``

   Type: *boolean*

   *No description available*

.. confval:: memailplugin.reportSilentClientsTimeSpan

   Default: ``1``

   Type: *double*

   Unit: *min*

   *No description available*

.. confval:: memailplugin.reportRequiredClients

   Default: ``10``

   Type: *double*

   Unit: *min*

   *No description available*

.. confval:: memailplugin.filterMeanInterval

   Default: ``10``

   Type: *double*

   Unit: *min*

   *No description available*

.. confval:: memailplugin.sendEmail

   Default: ``false``

   Type: *boolean*

   Enables sending of emails using mailx shell command.



Command-Line Options
====================

.. program:: scm

:program:`scm [options]`


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file file

   The alternative module configuration file. When this option
   is used, the module configuration is only read from the
   given file and no other configuration stage is considered.
   Therefore, all configuration including the definition of
   plugins must be contained in that file or given along with
   other command\-line options such as \-\-plugins.

.. option:: --plugins arg

   Load given plugins.

.. option:: -D, --daemon

   Run as daemon. This means the application will fork itself
   and doesn't need to be started with \&.

.. option:: --auto-shutdown arg

   Enable\/disable self\-shutdown because a master module shutdown.
   This only works when messaging is enabled and the master
   module sends a shutdown message \(enabled with
   \-\-start\-stop\-msg for the master module\).

.. option:: --shutdown-master-module arg

   Set the name of the master\-module used for auto\-shutdown.
   This is the application name of the module actually
   started. If symlinks are used, then it is the name of
   the symlinked application.

.. option:: --shutdown-master-username arg

   Set the name of the master\-username of the messaging
   used for auto\-shutdown. If \"shutdown\-master\-module\" is
   given as well, this parameter is ignored.


Verbosity
---------

.. option:: --verbosity arg

   Verbosity level [0..4]. 0:quiet, 1:error, 2:warning, 3:info,
   4:debug.

.. option:: -v, --v

   Increase verbosity level \(may be repeated, e.g., \-vv\).

.. option:: -q, --quiet

   Quiet mode: no logging output.

.. option:: --component arg

   Limit the logging to a certain component. This option can
   be given more than once.

.. option:: -s, --syslog

   Use syslog logging backend. The output usually goes to
   \/var\/lib\/messages.

.. option:: -l, --lockfile arg

   Path to lock file.

.. option:: --console arg

   Send log output to stdout.

.. option:: --debug

   Execute in debug mode.
   Equivalent to \-\-verbosity\=4 \-\-console\=1 .

.. option:: --log-file arg

   Use alternative log file.


Messaging
---------

.. option:: -u, --user arg

   Overrides configuration parameter :confval:`connection.username`.


.. option:: -H, --host arg

   Overrides configuration parameter :confval:`connection.server`.


.. option:: -t, --timeout arg

   Overrides configuration parameter :confval:`connection.timeout`.


.. option:: -g, --primary-group arg

   Overrides configuration parameter :confval:`connection.primaryGroup`.


.. option:: -S, --subscribe-group arg

   A group to subscribe to.
   This option can be given more than once.

.. option:: --content-type arg

   Overrides configuration parameter :confval:`connection.contentType`.

   Default: ``binary``


.. option:: --start-stop-msg arg

   Default: ``0``

   Set sending of a start and a stop message.


Monitor
-------

.. option:: -c, --clients list

   Comma separated list of clients to monitor.

.. option:: --print-tags

   Print available keys for accessing client info data and to
   build filter configurations.

.. option:: --no-output-plugins

   Do not use output plugins such as mncursesplugin.

