.. _configuration:

Configuration
=============


Configuration parameter `monitor.rules` is a dot-separated path of Python
class used to process monitoring data. The path should include directories
and module name. The system assumes path starts in the same directory
where configuration file is located. For example::

    monitor.rules = "rules.Rules"

In this case interpreter loads class Rules from file `rules.py` that
is expected to be located in the same directory where configuration file
`nw2.conf` is.

Default configuration loads class `Nw2Rules` from module `nw2rules.py`
that ships as part of the internal Java resources. You can find a copy
of this module in the directory `doc` in the distribution tar archive. This
copy is not actually used by the program, it is provided so you can inspect it
and consult its source code when you extend and modify data processing rules.

.. note::
    The script should be written assuming particular monitoring variables may
    not exist when it runs. Presence of certain monitoring variable or certain
    instance depends on the state of the network, because variables are created
    using information we collect during discovery. For example, parts of
    the script may try to process variable `tempSensor`, however if the script
    runs on the network built with devices that have no sensors, corresponding
    monitoring variable will be empty (that is, has no instances).



.. py:class:: Nw2Rules(log)

    Python class :class:`Nw2Rules` is used to process data NetSpyGlass collects when it
    polls devices. NetSpyGlass calls function :meth:`execute()` of an instance of
    this class at the completion of each monitoring cycle. Note that new instance of
    this class is created every time it is used to process collected data.

    :param log: Java logger. To add log record, call it like this: `self.log.info("Log record")`

    .. py:method:: execute()

        Java environment calls this function to execute data processing rules.


To modify default data processing rules, you need to create your own Python
class that derives from :class:`nw2rules.Nw2Rules`. Here is an example::

    import nw2rules

    class UserRules(nw2rules.Nw2Rules):
        def __init__(self, log):
            super(UserRules, self).__init__(log)

        def execute(self):
            self.log.info("#### UserRules.execute() starts")
            super(UserRules, self).execute()


Assuming this class is saved in file `rules.py`, configuration parameter
`monitor.rules` should look like this::

    monitor.rules = "rules.UserRules"


Function :meth:`execute()` in this class should call the same function in the base
class and then can perform its own calculation. See below for more information
on what it can do.

.. note::
    You can turn rule processing off completely by using string ``none``
    as a value of the parameter `network.monitor.rules`. This can be useful
    when NetSpyGlass runs in a cluster configuration where all computations
    are performed by a dedicated "compute" secondary server. Example::

        monitor.rules = "none"