Table of Contents |
---|
Introduction
Historically opReports has relied solely on being run on demand via the GUI (deprecated in opReports 4.3.1) 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.
...
As of version 3.0.2 using the GUI schedule editor is the most convenient method for managing report schedules. The GUI schedule editor is a front-end that handles schedule files, so the technical details given in the next section remain applicable.
Version 3.14 Traffic Snapshot Report can be defined in the Gui. When this report type is selected you can add and delete snapshot pages under (Sources)
Using Schedule Files
For ease of automated deployment and scriptability opReports provides access to all job schedule options using schedule files.
...
A job file must consist of one "hash" datastructure, with the following properties:
Property | Example | Description |
---|---|---|
type | "util" "wan" | The report type to generate. Required. See the opReports Report Descriptions for a list of available types. |
active | "true" or "false" | Whether this schedule is active or not. Only active schedules can create new reports, inactive schedules are consulted only for pruning of old report data. If active is not specified, then the schedule is inactive. |
description | "some text" | A free-form description of the scheduled job. Optional. |
frequency | "daily", "weekly", "monthly" or "yearly" | Not present for one-off reports. |
start | "1-14-2015 20:00:00", "mon 10:30", various others depending on the frequency | The date + time the report collection is to start at. Required. |
end |
The date + time the report collection is to end at. Same format as start . | ||
from | 13 or any integer between 0 and 24 | Start of Business Hours reporting. Optional. Default: 0. See the Formats for Report Periods and Frequencies page for details. |
to |
End of Business Hours reporting. Optional. Default: 24. | ||
exclude | "fri-sun", "sat-mon" | Business week selection. Optional, supported in opReports 3.0.8 and newer. |
node_intf_list | /some/where/some.file | The file describing the nodes and interfaces to collect. See section below for format. |
util_threshold | 80 | The desired interface utilisation threshold value (in percent), default: 80 (percent). |
util_threshold_mincount | 1 | The desired minimum number of threshold exceedences for flagging the interface as over-limit, default: 1. |
format |
a hash with the keys "html", "csv" and "xlsx", and values true/false or 1/0. e.g. { "html":0, "csv": true, "xlsx": false} | The formats the report should be saved in. | |
outputdir | /some/where/ | Where the report should be saved. This has to be a full path pointing to a directory. GUI-scheduled reports will always use one of the configured directories (see opreports_output_dirs in opCommon.nmis), and it is recommended that you use only these even if editing schedule files by hand.Every report schedule can use a different output directory. |
naming | "simple" or "precise" | What naming scheme should be used for the output files. Default is "simple". Mainly important if you plan to manually work with saved report files. See the section on Output File Naming below for details. |
sources and (at most) one of group_regexp, node_list, node_regexp, node_group, node_intf_list or node_intf_type_list | "everything" | See How to select Nodes (and Interfaces) for details. |
keep_for | 47 | How many days to keep an old report instance. If set to zero, the report is not expired. If not set, then the defaults for the report type are applied (configuration entry "default_report_keep_for "). |
options | { "title" : "My Custom ReportTitle" } |
Optional settings. Some are specific to particular report types. See the section on Optional Settings below. | ||
control_nmis | "true" or "false" | Whether NMIS should be "remote controlled" or left in peace. See section on Remote Controlling NMIS below. Only relevant for one-off reports. |
nmis_options | "mthread=true maxthreads=15" | Options to be given to |
target_audience_group | "HQ" | If present and a known NMIS group name, then the generated report can be viewed only by users who are members of this group (and the administrator). If not present then report viewing is not limited to particular groups. |
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>".)
...
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 hour5 minutes for recurring reports and every minute for one-off reports.
Recurring Schedules
Recurring jobs are processed repeatedly, as soon as the scheduler determines that the end of the report period for that schedule is past.
One-Off Reports ( One-Off Reports are generated using the Create one-off Report button in opReports 4.3.1 and newer )
A one-off job is normally processed exactly once, as soon as the report period has passed. The job is then marked completed
and will not be (re)generated.
...
The options
property can hold sub-properties that fine-tune opReports' behaviourbehavior. 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 todisplay_name
, the NMIS propertydisplay_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 onwardsonward. - Option
interface_naming
lets you change how interface names are displayed.
If not set or set to the default valueDescription
, the interface's Description property is used (in NMIS that corresponds to theifDescr
orifAlias
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 onwardsonward.
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 Utilisation report recognizes the following four options:
Option | Description |
---|---|
show_threshold | Default: true. If this is false, then no over threshold counts and exceptions are shown. Instead the interface bandwidths, traffic, utilisation and short report period are shown. |
show_only_util | Default: false. Ignored if show_threshold isn't false. If this is set to true, then opReports omits the bandwidth and traffic columns and shows only the utilisation (and short period). |
util_threshold | Default: 80 (%). Defines the level of utilisation above which it counts as exception. |
util_threshold_mincount | Default: 1. How often the interface utilisation has to be above the threshold value for the interface to be flagged as in exceptional state. |
The Traffic Snapshot report recognizes the following two options: global options, and numerous report-specific settings.
Option | Description |
---|---|
peak_type | One of combined , busiest_bits or busiest_util . Default is combined .Combined: The peak utilisation for the interface group is defined as the sum of all involved interfaces' traffic. Busiest by Bits: The peak utilisation is sourced from the one interface with the highest traffic figure. Busiest by Utilisation: The peak utilisation is sourced from the one interface with the highest ratio of traffic to configured interface capacity. |
capacity_type | One of |
Report-Specific Settings
...
For Traffic Snapshot
...
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:
Property | Description |
---|---|
business_services | A list of business service names that should be shown on this page. Required. Ordering is relevant. |
options | A hash sub-structure with report options that are specific to this one page. |
The options
structure supports the following settings:
Per-Page Options Property | Description |
---|---|
title | The title for this report page. Optional; if not present "Page <N>" is used. |
summary_title | The summary title is shown above the utilisation summary table. Optional; if not present "Utilisation Summary" is used. |
column_heading | The value of this property is used as table column heading for the business service column in the summary table. Optional; if not present, "Interfaces" is used. |
graph | The name of the NMIS graph to produce for each selected interface. Required. Note that the "short name" of the graph is to be used, e.g. "autil", not "Interface Utilisation including Availability". |
graph_order | The graphs for all members of one business service group will be arranged in the selected order. |
levels | A hash sub-structure that describes the desired coloring scheme for this page, based on utilisation level. Optional; if not present, then the levels from the global configuration option report_summary_levels are used. |
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:
Level Property | Description |
---|---|
description | The displayed label for this level. |
threshold | A number. The lowest level with a utilisation figure (strictly) higher than the threshold 'wins'. The lowest defined level should have a negative threshold. |
color | A color name or a "#RRGGBB" HTML-style color specification. This color is used for the cell background of the 'Peak' column. The color name must be one of the ones that XLSX supports; RGB is more robust. |
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:
...
reports, please check the Traffic Snapshot Report detail page.
Output File Naming
We recommend that you let opReports manage output files completely, and that you make use of the automatic report emailing feature or the Zip button in the GUI to access report instance files.
If that is not feasible for you, the following description of of how opReports generates file names may come handy.
Please do note that the behaviour of all naming options except "simple" may change between opReports versions.
- The file name auto-generation logic only affects the basename of the file; extensions are always set to
.json
for the report metadata file and.html
,.csv
and.xlsx
for the different output formats. - Please note that any graph files associated with a report are not subject to this naming scheme; those names are completely dynamic and can be determined only by analysing the report metadata file.
- On-demand reports generated from the GUI allow the user to supply the 'report name', and if that is present then it'll be used for the file names (but subject to de-clashing as outlined below).
If no report name is supplied, then On-demand reports are treated like scheduled non-recurring/one-off reports. - All file names may be amended with a number if a clashing file already exists, e.g. "some_report.3.xlsx" and "some_report.4.xlsx" may be generated.
- All file names are adjusted to replace certain characters: all spaces and ":" are replaced by "_".
- Depending on the report frequency, the following components are used to build the file name:
Frequency | Simple Naming | Precise Naming |
---|---|---|
any | first the report type, then a "_" | same as simple |
any | n/a | if the report schedule selects nodes by group: the group name and a "_" |
one-off | the start and end times in ISO8601 format, separated by "_" and followed by a "_" | same as simple |
daily | 'daily_', then the start and end times in the original format, separated by "-", | same as simple |
weekly | the abbreviated start date's month name suffixed with the day of month, a "-", | 'weekly_', the start and end date/times in the original format separated by hyphen (e.g. Tue_00-Fri_14_45 after space removal), a "_", |
monthly | the abbreviated month name of the end date, a "_", then the four-digit year | 'monthly_', the start and end dates/times in the original format separated |
yearly | 'yearly_', the start and end dates in the original format separated by hyphen | same as simple |