.. _how_to_access_mvars:

How to access monitoring variables
==================================

At the end of each polling cycle NetSpyGlass loads the module and creates
an instance of the class defined by the `module.rules` parameter and calls
its function :func:`execute()` to process collected data.

To access monitoring variable, this function should call :func:`nw2functions.import_var`
defined in the module :mod:`nw2functions`::

    import nw2rules
    from nw2functions import *

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

        def execute(self):
            super(UserRules, self).execute()

            in_octets = import_var('ifHCInOctets')

Call to :func:`import_var` returns a generator of
:class:`MonitoringVariable` objects. Each object collects monitoring data
for particular variable of one network interface or hardware component of
one device. This can be inbound interface utilization, outbound interface
errors, CPU utilization, reading of particular temperature sensor etc. Information
collected by one instance of monitoring variable is
obtained by making SNMP request with one OID and the name of the
monitoring variable usually matches the name of the OID. This is true for
the variables that collect "raw" or "original" data as it comes from the device.
Very often this data must be processed to make it usable, for example,
interface utilization comes in the form of a byte counter, which needs to be
converted to the rate in bits/sec for representation in the system. This is done
in the Python script by calling built-in functions to compute the rate and
multiply it by 8. Result of this calculation can be stored in a new variable
named ifInRate , this can be done using the following lines of Python code::


    in_octets = import_var('ifHCInOctets')
    in_rate = mul(rate(in_octets), 8)
    export_var('ifInRate', in_rate)

In this example, `in_octets` is a generator that yields objects of class
:class:`MonitoringVariable` that hold values of the corresponding counters
collected from all interfaces of all devices by snmp collector. This generator
can produce thousands of items, where each item corresponds to one interface
of one device.

Here we create new Python variable :py:obj:`in_rate` which is also a generator
of :class:`MonitoringVariable` objects. To make them available to NetSpyGlass
so they can appear in the UI and stored in the database, you need to "export"
them by calling :func:`export_var`.