.. _silence_script:

Script silence.py
=================

Usage:

.. code-block:: none

    $ /opt/netspyglass/current/bin/silence.py

    This script can add, update and list alert silences

    Usage:

        silence.py command (--server=host) (--port=port) (-n|--network)=netid [-h|--help] (--id=NN) --expiration=time (--var_name=name) (--dev_id=id) (--dev_name=name) (--index=idx) (--tags=tags_string)

           command:        Can be "add", "update" or "list"

           --server:       NetSpyGlass UI backend server host name or address
           --port:         port number used by NetSpyGlass UI backend (default: 9100)
           --network:      NetSpyGlass network id (a number, default: 1)
           --id:           silence id, if known (only for the command "update")
           --expiration:   silence expiration time, minutes
           --key:          alert key to match
           --var_name:     variable name to match
           --dev_id:       device Id to match
           --dev_name:     device name
           --index:        component index to match
           --tags:         a string that represents comma-separated list of tags to match. Tag can be defined either
                           as "Facet.word" or just "Facet". The latter is equivalent to matching "Facet.*". Tag
                           can be prepended with "!" to indicate negation - alert matches if it does not have corresponding
                           tag.
           -h --help:      print this usage summary

        Parameters --server and --port are optional. If they are not provided, the script tries to find script "nsgc.sh"
        in the same directory it was started from and runs it to read server url from NetSpyGlass configuration file.

        Variable (--var_name) and device name (--dev_name) match supports regular expressions. The whole string
        must match regular expression, that is, we use "match" rather than "search"

    Commands:

        list   lists all active (that is, not expired yet) silences
        add    add new silence to the system. Parameter --expiration is mandatory and has no default value
        update this command allows the user to update existing silence. Parameter --id is mandatory, the value appears
               in the output of the "list" command

        To delete existing silence that hasn't expired yet set its expiration time to a small but non-zero value,
        such as 1 min or less. The server expires silences every minute, so this silence will appear in the output
        of the "list" command until server expires it.

    Examples:

        the following command adds silence for alert "busyCpuAlert" for device with id 212, any component and any tags:
            silence.py add --var_name='busyCpuAlert' --dev_id=212

        match alert by name and tag, for example silence all alerts for servers that belong to hbase cluster "hbase0"
        except those marked "important":
            silence.py add --var_name='busyCpuAlert' --tags="Explicit.hbase0, !Explicit.important"

        use this command to list active silences:
            silence.py list

        The output looks like this:
             id  | exp.time, min  |         created          |         updated          |                  match
            ------------------------------------------------------------------------------------------------------------------------
             8   |      60.0      | Mon Jun  8 19:50:15 2015 | Mon Jun  8 19:50:15 2015 | {u'varName': u'busyCpuAlert', u'tags': [], u'deviceId': 131, u'index': 0}

        use this command to update expiration time on the existing silence (use silence Id returned by the "list" command):
            silence.py update --id=8 --expiration=120

        use the following command to add silence that matches all alerts regardgess of their name, device,
        component and tags (a "catch all" silence):
            silence.py add --var_name='.*'

        use the following command to add silence that matches all alerts for given device
            silence.py add --var_name='.*' --dev_id=212

        the following command adds silence that matches variable "busyCpyAlert" for all devices with names that
        match regular expression "sjc1-rtr-.*"
            silence.py add --var_name='busyCpuAlert' --dev_name='sjc1-rtr-.*'

        override server address and port number settings
            silence.py list --server=10.1.1.1 --port=9101