9. Reporting Framework

9.1. 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://quartz-scheduler.org/documentation/quartz-2.2.x/tutorials/tutorial-lesson-06
        # "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.

9.2. 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

9.3. 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.