.. highlight:: rst

.. _scalert:

#######
scalert
#######

**Real time alert template.**


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

This module executes custom scripts upon arrival of objects or updates.
It provides as template for custom modification and is not a replacement for :ref:`scvoice`.

There are four possible trigger mechanisms for calling scripts:

* Event creation/update,
* Amplitude creation,
* Origin creation (with status = preliminary),
* Pick creation with filter for phase hint.

.. note ::

   People started modifying :ref:`scvoice` to send emails or
   other alert messages. Then, the name *scvoice* is then just wrong.
   If you want to customize :ref:`scvoice`, use scalert instead.


.. _scalert_configuration:

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

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

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



.. confval:: firstNew

   Default: ``false``

   Type: *boolean*

   Treat an event as new event when it is seen the first time.


.. confval:: agencyIDs

   Type: *list:string*

   List of agency IDs to consider picks and origins. The agency ID
   is extracted from the pick or the preferred origin of the event
   and compared with the configured IDs.
   
   unset \(\=\): use agencyID defined in global, default
   
   empty list \(\=\"\"\): all agencies are allowed


.. confval:: authors

   Type: *list:string*

   List of authors to consider picks and origins. The author
   is extracted from the pick or the preferred origin of the event
   and compared with the configured authors.
   empty list \(\=\"\"\): all authors are allowed


.. confval:: poi.message

   Type: *string*

   The default message string for the event\-script is
   \"earthquake, [HOURS] hours [MINS] minutes ago, [DESC],
   magnitude [MAG], depth [DEP] kilometers\" whereas [DESC]
   is the string given in the event.description attribute. This
   string can be overwritten using one of the following options.
   There are three placeholders that can be used: \@region\@,
   \@dist\@ and \@poi\@.
   Example: \"\@region\@, \@dist\@ kilometers from \@poi\@
   away\".


.. confval:: poi.maxDist

   Default: ``20``

   Type: *double*

   Unit: *deg*

   When using the nearest point of interest \(city\) as part of
   the message string, specify the maximum distance in degrees
   from the event. Any point of interest farther away will be
   ignored.


.. confval:: poi.minPopulation

   Default: ``50000``

   Type: *double*

   Minimum population for a city to become a point of interest.


.. confval:: scripts.pick

   Type: *string*

   The script to be called when a pick
   arrives. Network\-, station code, pick publicID are passed
   as parameters \$1, \$2, \$3.


.. confval:: scripts.amplitude

   Type: *string*

   The script to be called when an amplitude
   arrives. Network\-, station code, amplitude and amplitude
   public ID are passed as parameters \$1, \$2, \$3, \$4.


.. confval:: scripts.alert

   Type: *string*

   The script to be called when a preliminary
   origin arrives. Latitude and longitude are passed as
   parameters \$1 and \$2.


.. confval:: scripts.event

   Type: *string*

   The script to be called when an event has been
   declared. The message string, a flag \(1\=new event,
   0\=update event\), the EventID, the arrival count and the
   magnitude \(optional when set\) are passed as parameters
   \$1, \$2, \$3, \$4 and \$5.


.. note::
   **constraints.\***
   *Constraints for executing scripts*



.. confval:: constraints.phaseHints

   Default: ``P,S``

   Type: *list::string*

   Start the pick script only when the phaseHint of the
   received pick has one of the value\(s\).


.. confval:: constraints.phaseStreams

   Type: *list::string*

   Start the pick script only when the stream \(NET.STA.LOC.CHA\)
   of the received pick belongs to the list of stream IDs. If empty,
   all picks are accepted, otherwise only the ones whose stream ID
   matches one of the entry of this comma separated list. Each entry
   must follow the NET.STA.LOC.CHA format, but the special
   characters ? \* \| \( \) are also accepeted.
   E.g. \"CH.\*,GR.STA??.\*,\*.\*.\*.HH?,\*.\*.\*.??\(Z\|1\)\"


.. confval:: constraints.phaseNumber

   Default: ``1``

   Type: *int*

   Start the pick script only when a minimum number of phases
   'phaseNumber' is received within 'phaseInterval'.


.. confval:: constraints.phaseInterval

   Default: ``1``

   Type: *int*

   Unit: *s*

   Start the pick script only when a minimum number of phases
   'phaseNumber' is received within 'phaseInterval'.



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

.. program:: scalert

:program:`scalert [options]`


Generic
-------

.. option:: -h, --help

   Show help message.

.. option:: -V, --version

   Show version information.

.. option:: --config-file arg

   Use alternative configuration file. When this option is
   used the loading of all stages is disabled. Only the
   given configuration file is parsed and used. To use
   another name for the configuration create a symbolic
   link of the application or copy it. Example:
   scautopick \-> scautopick2.

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

.. option:: --first-new

   Overrides configuration parameter :confval:`firstNew`.


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, eg. \-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`.

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

   Set sending of a start and a stop message.


Database
--------

.. option:: --db-driver-list

   List all supported database drivers.

.. option:: -d, --database arg

   The database connection string, format:
   service:\/\/user:pwd\@host\/database.
   \"service\" is the name of the database driver which
   can be queried with \"\-\-db\-driver\-list\".

.. option:: --config-module arg

   The config module to use.

.. option:: --inventory-db arg

   Load the inventory from the given database or file, format:
   [service:\/\/]location .

.. option:: --db-disable

   Do not use the database at all


Alert
-----

.. option:: --amp-type arg

   Specify the amplitude type to listen to.

.. option:: --amp-script arg

   Overrides configuration parameter :confval:`scripts.amplitude`.

.. option:: --alert-script arg

   Overrides configuration parameter :confval:`scripts.alert`.

.. option:: --event-script arg

   Overrides configuration parameter :confval:`scripts.event`.


Cities
------

.. option:: --max-dist arg

   Overrides configuration parameter :confval:`poi.maxDist`.

.. option:: --min-population arg

   Overrides configuration parameter :confval:`poi.minPopulation`.


Debug
-----

.. option:: -E, --eventid arg

   Specify event ID that is used for testing. After running the
   alert scripts scvoice will exit.

