Introduction

Historically opReports has relied solely on being run on demand via the GUI or command line (or periodically with cron). In version 3.0 we've added another feature that extends these capabilities: the opReports Scheduler. The scheduler is meant to act a bit like a combination of "cron" and "at" (a venerable but not especially well known Unix tool, companion of cron)  for opReports.

The basic idea is that you control the scheduler by defining opReports "jobs" to be taken care of (once, at a particular time in the future, or recurring with specific frequencies and start/end times/dates).

How to define Report Schedules

Each scheduled job is defined by a separate JSON file. The scheduler expects these files in /usr/local/omk/conf/schedule (but this is configurable - see <omk_schedule> in conf/opCommon.nmis). As of version 3.0 schedule files must be managed using an external editor, but support for editing schedules from the GUI is already planned.

All job files must be called <something>.json, and only letters, digits, dot, underscore and hyphen are allowed in the file name. All other files are silently ignored. You can thus disable a job by naming it something like !disabled_job.json. opReports ships with a number of example schedule files (all set to be inactive) and a brief README file in the conf/schedule directory.

A job file must consist of one "hash" datastructure, with the following properties:

Besides these user-definable properties, the scheduler also manages certain others for internal use, and you should not modify these! (Currently these include the properties "uuid", "in_progress", "completed" and all properties named "actual_<something>".)

Scheduler Operation

When the scheduler starts it looks for jobs that are in need of actions (ie. the wanted reporting period has just passed and the relevant report hasn't been created yet) and handles them sequentially. When the scheduled job is finished, the job file is not removed and remains behind (regardless of whether this is a one-off or recurring schedule). After that all known saved reports are checked for pruning: if the report was created with a non-zero keep_for property, and is older than this cutoff then it is removed. This affects only report instances, not the job schedules.

The opReports scheduler is not a long-lived daemon process, but  rather meant to be run suitably frequently from cron. The scheduler does log to opReports.log, but also prints error messages of higher urgency to STDERR, where cron will pick them up and mail them to root (or whatever recipient you have set up). By default opReports creates an /etc/cron.d/opreports which triggers the scheduler once every hour.

Remote-Controlling NMIS

This experimental feature is primarily meant for Interface Utilisation Reports at this time and works only for one-off jobs. If your job has control_nmis true AND a node_intf_list file, then the following actions are taken:

• When the job starts, NMIS is reconfigured with global_collect true and with ONLY the wanted nodes and interfaces (identified by the node_intf_list file) set to collect true. All other interface collection activity is disabled with global_nocollect_ifDescr. An nmis.pl type=update run  will then be performed, and the NMIS data collection commences as normal.
• When the job  completes, NMIS is disabled, with global_collect set to false.
• This clearly interferes with recurring schedules and should therefore only be used in isolation.

As of version 3.0.2 some limitations apply for this feature:

• The NMIS remote control feature is not supported for recurring report schedules, only for one-off reports.
• The only possible extra action to take at the beginning of a job is enabling NMIS and setting the listed interfaces and nodes for collection.

Optional Settings

The options property can hold sub-properties that fine-tune opReports' behaviour. There are a few common options that are shared by all reports:

• Option title lets you specify a custom title for the report. The value must be a string.
• Option homelink lets you specify a custom banner, to be displayed only for a standalone HTML report and above the actual report (title and body).
  The value of this option must be a string that contains the raw HTML to be shown.
• Option email lets you specify one or more recipients for report delivery by email. The value must be a comma separated list of email addresses. opReports will email the report to all listed email addresses, with all selected output formats as attachments.
• Option node_naming lets you change how node names are displayed.
  If not set (the default), nodes are displayed with their plain node name.
  If set to display_name, the NMIS property display_name will be used if it's present for a node; if not, the plain node name is used.
  This is supported in opReports 3.0.8 and NMIS 8.6 onwards.
• Option interface_naming lets you change how interface names are displayed.
  If not set or set to the default value Description, the interface's Description property is used (in NMIS that corresponds to the ifDescr or ifAlias property).
  If set to a different interface property name, that property's value is used.
  This is supported in opReports 3.0.10 and NMIS 8.6 onwards.

The Node Availability and Interface Capacity reports support option embedgraphs (value true or false), which controls whether graphs are embedded into the graph. The Report Descriptions page describes this feature in more detail.

The WAN report supports option wan_report_level, whose value selects which report detail level should be chosen. This can be given either as the index of the  level or as its name. The page about WAN report detail levels describes this feature in detail.

The Node Health report has option exceptions, which when set to true, changes the report to only display health exceptions and suppress nodes with ok health values.

The Utilisation report recognizes the following four options:

The Traffic Snapshot report recognizes the following two options:

Report-Specific Settings

Multiple Pages for Traffic Snapshot Report

The Traffic Snapshot report  requires a deep structure to describe each of its multiple pages.

Each page covers the (interface) members of one or more opCharts Business Services; utilisation data is computed and shown for all members of a business service combined, but graphs are presented  for each interface separately.

In a schedule file this structure is known as pages, and it is passed to opreports-cli serialised in dot-notation form.

The pages structure must contain a list of page definitions, each with the following  properties:

The options structure supports the following settings:

Level Color Schemes

The coloring rules must be set separately for each page.
To simplify reuse the schedule editing GUI will let you pick only from existing schemes that are defined in opCommon.nmis: the color level schemes must be attached to the configuration item report_snapshot_levels, and each scheme must have its own key. opReports ships with two example schemes to illustrate this setup.

In both cases (for editing a schedule by hand, or for preparing reusable color schemes in the config), the levels structure must be a deep hash structure, key being the level 'name', each value being a structure with the following properties:

How levels and peak/capacity types interact

The utilisation summary table contains three columns:

• the name of the  Business Service for this group
• the "Peak Utilisation" for the whole group, in bits/second (formatted with suitable unit suffix),
• and the "Capacity" for the whole group, in bits/second.

The "Peak Utilisation" can be the combined sum of utilisation figures across the group, or the utilisation of one "busiest" interface.
The "Capacity" can be the combined sum of capacities across the group, or the capacity of the one "slowest" interface.

Please note that depending on your configuration choices, the displaed Peak can be higher than Capacity (by some orders of magnitude).
For coloring, the utilisation ratio is computed as peak divided by capacity; this can be above 1.0 (or 100%) as per the caveat above.

The peak and capacity options other than combined are mainly meant for business services that represent identical pairs of interfaces each, one active, one standby; in all other case the caveat above applies.

The Peak Utilisation column is colored according to the levels option: the first level whose threshold is strictly lower than the utilisation ratio is the one setting the color.
E.g. with a ratio 0.0 or 0% (an idle interface group) and level thresholds -1, 25 and 75, the level with threshold -1 will be controlling the color. If the ratio was 0.74 or 74%, the middle level would win, and only if the ratio was above 0.75 or 75% would the last level be involved in coloring.

Here is an  complete example Snapshot Report Schedule in JSON form:

{
  "active" : false,
    "description": "an example weekly snapshot report",
    "type": "snapshot",
    "outputdir" : "/usr/local/omk/var/reports",
  "start" : "mon 00:00",
    "end" : "sun: 24:00",
    "frequency" : "weekly",
    
  "formats" : {
      "csv" : true,
      "xlsx" : true,
      "html" : true
  },
    "options": {
        "peak_type": "combined",
        "capacity_type": "combined"
    },
    
  "pages" : [
    {
      "business_services" : [
        "first service", "second service"
      ],
      "options" : {
        "title" : "this is page one",
        "graph_order" : "same_row",
        "graph" : "abits",
        "summary_title" : "this is summary one",
        "column_heading" : "Links on page one",
                "levels" :  { "low": { "color": "green", "description" : "low util", "threshold": -1 },
                                            "high" : { "color": "red", "description" : "high util", "threshold": 50 }
                                        }
      }
    },
    {
      "options" : {
        "graph" : "autil",
        "summary_title" : "this is summary two",
        "column_heading" : "Other Intfs",
        "title" : "page two",
        "graph_order" : "same_column",
        "levels" : {
          "boring" : {
            "color" : "#00ff00",
            "description" : "30-60%",
            "threshold" : 30
          },
          "third" : {
            "description" : "1-30%",
            "color" : "#008000",
            "threshold" : 1
          },
          "attic" : {
            "color" : "#ffa31a",
            "description" : "above 80%",
            "threshold" : 80
          },
          "ground" : {
            "color" : "#004d00",
            "description" : "under 1%",
            "threshold" : -1
          },
          "balcony" : {
            "threshold" : 60,
            "color" : "#c6ff1a",
            "description" : "60-80%"
          }
        }
      },
      "business_services" : [
        "another business service" ,
        "and one more with more intfs",
                "and maybe a last one, too"
      ]
    }
  ]
}