.. _silence_script:

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

This script is part of the Python package `nsgcli` that you can install using pip::

    Usage:

    .. code-block:: none

        $ silence --help

    This script can add, update and list alert silences

    Usage:

        silence <command> --base-url=url [--token=token] (-n|--network)=netid [-h|--help] (--id=NN) \
                            --start=TIME --expiration=time (--var_name=name) (--dev_id=id) (--dev_name=name) \
                            (--index=idx) (--tags=tags_string) (-reason=reason_text)

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

           --base-url:     server access URL without the path, for example 'http://nsg.domain.com:9100'
                           --base-url must be provided.
           --network:      NetSpyGlass network id (a number, default: 1)
           --id:           silence id, if known (only for the command 'update')
           --start:        silence should start on this date and time. Various input formats are supported,
                           examples: '2020-03-20 10:00:00' (no time zone) or 'March 20 2020 10:00:00 -0700' (with
                           time zone). See Python module `dateutil` for the detailed list of supported formats.
                           You can set the time zone, but if it is not specified, the time is assumed to be in local
                           time zone. If this parameter is not provided, the start time of the silence is "now". If
                           specified, the start time can be both in the future and in the past.
           --expiration:   silence expiration time, minutes. The silence stops at the time calculated as
                           the start time plus expiration time.
           --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.
           --reason:       argument is a text string that describes the reason this silence is being added
           -h --help:      print this usage summary

        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 silences that have started but not expired yet, and those with start time
               in the future. All time columns are presented in local time zone.
        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. You can change any parameter of the silence, including
               its start time and expiration.

        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

        specify start time with time zone:
            silence.py add --start='2020-04-01 00:00:00 -0800' --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