Reporting Framework
*******************

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

Reporting framework supports generation of reports on schedule. Reports are
generated by Python hook scripts that have access to complete set of
monitoring variables, so they can perform various calculations that can be used
to generate reports.

Reports are configured in the `network.monitor.reports` section of the main
configuration file. Configuration for a report includes definition of the Python
class, corresponding schedule, html template, output file name and number of
copies we should keep while rotating generated report files. It is possible to
configure multiple reports, each one using its own set of parameters::


    network {
        monitor {

            # Python hooks to generate reports
            # Specification of the cron-like syntax of the "schedule" variable
            # http://www.quartz-scheduler.org/documentation/quartz-2.2.2/tutorials/tutorial-lesson-06.html
            # "nw2report.Nw2Report" is the default report included with the distribution
            reports = [
                {
                    class: "interface_report.Report",
                    schedule: "10 0 * * * ?",
                    template: "iface_report.vm",
                    output: "interfaces-0.html",
                    keep: 5
                },
                
                {
                    class: "bgpreport.BgpReport",
                    schedule: "10 0 0 * * ?"
                },
            ]

This configuration example describes two reports. 

The first is a report on interface errors and up/down status. It uses Python 
class `Report` defined in the module `interface_report.py`, runs every minute 
at 10 sec after the minute, uses html template file `iface_report.vm`, the output 
is saved in the file with name `interfaces-0.html`. Finally, parameter `keep` means
the system will keep no more than 5 reports with numbers 0,1,2,3,4.

Python script used to run the report should be placed in NetSpyGlass home
directory (defined by the configuration parameter `home`). 

Template files are located in the directory `etc` inside of NetSpyGlass home. 
NetSpyGlass uses Velocity templating engine for reports, see the documentation 
on Velocity project web site for the description:

http://velocity.apache.org/engine/devel/user-guide.html

Generated reports are placed in the output directory `reports/$network_name/output` 
inside of NetSpyGlass home.

The newest report always has number "0". Before creating new report file,
the engine rotates existing reports by renaming them so that `report-3.html` 
becomes `report-4.html`. The oldest report with the number exceeding value 
of the parameter `keep` is deleted and new report is created with the name 
`report-0.html`.

NetSpyGlass comes with the preconfigured default report, its configuration
looks like this::
 
    {
        class: "nw2report.Nw2Report",
        schedule: "10 0 * * * ?",
        template: "default_report.vm",
        output: "report-0.html",
        keep: 5
    },

This report uses Python class `Nw2Report` defined in the module `nw2report.py`.
It runs on schedule every minute at 10 sec after the minute (that is, 
00:10, 01:10, 02:10 and so on). Report uses template in the file 
`$home/etc/default_report.vm`, generated text will be saved in the output 
file with name `$home/reports/$network_name/output/report-0.html`.

Python script `nw2report.py` used to run this report is part of the distribution
JAR file and can not be modified. However, we provide a copy of this file in
the directory `doc/`. You can study this script and use it as a prototype for
your own reports.

If you want to just change the template used with the default report, do not
modify file `$home/etc/default_report.vm` because your changes will be overwritten
next time you upgrade NetSpyGlass. Instead, make a copy under different name
and edit it, then add configuration clause like this to your configuration
file::

    reports = [
        {
            class: "nw2report.Nw2Report",
            schedule: "10 0 * * * ?",
            template: "your_modified_template.vm",
            output: "report-0.html",
            keep: 5
        },
    ]

That is, you use built-in report script and class but provide your own template.
You can change other parameters, such as its schedule, too.

Configuration of the second report in the example above looks like this::

    {
        class: "bgpreport.BgpReport",
        schedule: "10 0 0 * * ?"
    },

This report does not use template and does not specify output file name. In 
this case, report class is expected to write files directly to the file system
or do other things with the data it generates. This script could, for example,
upload the file to a server or use network APIs to push the data somewhere.

Template name, output name and rotation parameter `keep` are optional.

.. note::
   you can configure reports that use the same python class but different
   Velocity templates. The combination of the Python class path, template
   file name and output file name must be unique.


How to Access Reports via NetSpyGlass UI
========================================

to access reports stored in the standard output directory for reports
`$home/reports/$network_name/output`, click second button from the right in
the upper right corner of the UI


Report Scripts
==============

Report Python script should define a class with function `execute` defined as
follows::

    class Nw2Report(object):
        """
        this class is used to generate reports.
    
        :param log: Java logger object, can be used to write to the same log file
         used by the UI server (logs/info.log or logs/error.log, depending on the level).
        """
    
        def __init__(self, log):
            self.result = {}
            self.log = log
            self.config = {}
            self.context = None
    
        def execute(self, config, vars, template_context):
            """
            Generate some useful reports.
    
            :param config:  a dictionary with subset of the configuration information.
                            Currently it includes the following items:
                            "home"               : NSG "home" directory
                            "pollingIntervalSec" : polling interval, sec
                            "network.name"       : the name of the network
                            "devices"            : list of instances of Python class Device. This is
                                                   the same object used to pass to the Python hook
                                                   that matches devices to views
            :param vars: a dictionary where the key is monitoring variable name and
                         value is MonitoringVariable object
            :param template_context:  Velocity template context
            """
            self.log.info('===  Reports')
            self.config = config
            self.context = template_context
            #
            # Generate report using variables in `vars` and Velocity template
            # context `context`


This is a minimal class that will work with reporting framework. When class 
is created, NetSpyGlass passes parameter `log` to its constructor. Calling 
`log.info()` or `log.error()` on this object will make log records in 
NetSpyGlass log files. Function `execute()` is called with parameters that 
pass parts of the system configuration in parameter `config`, dictionary
of monitoring variables in `vars` and Velocity template context in 
`template_context`. If your report uses template, it should set values
inside of the context using data it generates. See Velocity documentation
for more details on how to do it. Our default report script `nw2report.py`
also demonstrates this method (you can find copy of this script in the directory
`doc` in the distribution package). If your report does not use templates,
it should just write to files in a format you choose. Use items with keys
"home" and "network.name" to construct path to the output directory for
reports to put them in the standard place to make sure NetSpyGlass UI can
find them.

Python script can import functions from module `nw2functions`. This module 
is also used in the Python hook script that processes monitoring variables,
see documentation file `rules.md` for more details.