fbpx

opReports all you need to know

How to select Nodes (and Interfaces) for reporting

In opReports 3.0 the various methods for selecting what to report on have been consolidated and simplified.

Which selection mechanisms are supported by what report types?

Join Paul McClendon, an Opmantek Support Engineer, as he demonstrates quickly and easily you can generate reports using opReports.

Certain reports do have specific requirements which are shown in the table below.

In general, however, providing more precision than necessary is allowed.
For example, you can use a node and interfaces (and even types) list file for all reports; for reports where interfaces are not relevant, the extra information will simply be discarded and just the listed nodes will be used. Reports that don’t need the summary type will simply use the nodes (and possibly the interfaces).

On the other hand, providing insufficiently precise information to reports that require it will result in an error message (e.g. trying to run a summary report with just group=X).

Report Type Selection Mechanisms Notes
Node Single node only The node report supports a single node only.
If your selection contains more nodes, then the report is created for the first listed node.
Node Health All, interfaces irrelevant Interface selections are not relevant for this report.
Node Availability All, interfaces irrelevant Interface selections are not relevant for this report.
Grouped (Node) Availability All, interfaces irrelevant Interface selections are not relevant for this report.
WAN All It operates on all active or any selected interfaces of the selected nodes whose net type is “wan”.
WAN Utilisation Distribution and WAN Utilisation Distribution Summary All It operates on all active or any selected interfaces of the selected nodes whose net type is “wan”.
QoS All It operates on all active or any selected interfaces of the selected nodes, if QoS is configured for the interface.
Cos All For each selected node this report covers all active or any selected interfaces that have Class of Service configured.
Uptime All, interfaces irrelevant Interface selections are not relevant for this report.
Response Time All, interfaces irrelevant Interface selections are not relevant for this report.
Interface Capacity All
Grouped Interface Capacity All
Interface Utilisation All Interface selections are honored but the “type” component (in selections by node+interface+type) are ignored as not relevant.
Interface Unicast Packets All Interface selections are honored but the “type” component (in selections by node+interface+type) are ignored as not relevant.
CPU All, interfaces irrelevant Interface selections are not relevant for this report.
Free Memory All, interfaces irrelevant Interface selections are not relevant for this report.
Memory Pool All, interfaces irrelevant Interface selections are not relevant for this report.
Memory Buffer All, interfaces irrelevant Interface selections are not relevant for this report.
Monitored Services All, interfaces irrelevant Interface selections are not relevant for this report.
Traffic Usage All Interface selections are honored but the “type” component (in selections by node+interface+type) are ignored as not relevant.
Traffic Summary node+interface+type This report strictly requires this specific selection format
Traffic Snapshot opCharts Business Services, selected per page. This report type strictly requires lists of Business Services for each of its (multiple) page definitions.

Choosing the selection mechanism for scheduled reports

For scheduled reports your schedule must contain a property named sources, with one of the following values: “everything”, “group_each_regexp”, “group_regexp”, “node_regexp”, “node_group”, “nodes”, “node_list”, “node_intf_list”, “node_intf_type_list”, or “business_services” (in 3.0.14 an newer). Those mechanisms are described below.

If you use the opReports schedule editing GUI then this property will be managed on your behalf.

The Simplest Choice: Everything

If you do not make an explicit selection, then opReports will work on all active nodes (and all their active interfaces, for report types that handle interfaces).

In the GUI this choice is shown as “All Active Nodes”.

Nodes that belong to a specific group

In NMIS every node belongs to precisely one group, and this concept therefore applies to opReports as well.

With opreport-cli you have to give the argument group=. In a report schedule this is expressed using the property node_group. In the GUI this choice is presented as “by Group”.

There are two “wildcard” groups available:

  • Group “All” is equivalent to the default choice, all active nodes. This wildcard should not be used as we will likely retire it in a future version of opReports.
  • Group “Each” is available for scheduled reports only, excluding ‘once only’ scheduled reports, and causes the generation of a separate report for each of the known groups.

Nodes whose name matches a regular expression

In the GUI this choice is called “by Regular Expression for Nodes”, opreports-cli uses the command line argument node_regexp=, and for scheduled reports you’d specify this with the property node_regexp.
The node regular expression is evaluated at report creation time.

Nodes and Interfaces whose names/descriptions match regular expressions

Nodes must match the regular expression given for the node name, but interface descriptions must also match a separate regular expression.
Only those interfaces are selected where both regular expressions match.
However, for reports where interfaces are not relevant, interfaces are disregarded.

The regular expression for interfaces is applied to both the interface’s ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as “Name” or “Name (ifDescr)”. Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)

In the GUI this option is called “by Regular Expression for Nodes and Interfaces”.
opreports-cli requires that you supply both node_regexp= and node_intf_regexp= arguments.
The report schedules use the same property names as the opreports-cli parameters.

Both regular expressions are evaluated at report creation time.

Groups, Nodes and Interfaces whose names/descriptions match regular expressions

Groups must match the regular expression given for the group name AND
Nodes must match the regular expression given for the node name AND
Interface descriptions must also match a separate regular expression.

Only those interfaces are selected where all three regular expressions match.
However, for reports where interfaces are not relevant, interfaces are disregarded.

The regular expression for interfaces is applied to both the interface’s ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as “Name” or “Name (ifDescr)”. Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)

In the GUI this option is called “by Regular Expression for Groups Nodes and Interfaces”.
opreports-cli requires that you supply group_regexp= AND node_regexp= AND node_intf_regexp= arguments.
The report schedules use the same property names as the opreports-cli parameters.

All three regular expressions are evaluated at report creation time.

Groups, Nodes and Interfaces whose names/descriptions match regular expressions for separate report for each group

This option causes the generation of a separate report for each of the known groups.
This option is available for scheduled reports only, excluding ‘once only’ scheduled reports.

Groups must match the regular expression given for the group name AND
Nodes must match the regular expression given for the node name AND
Interface descriptions must also match a separate regular expression.

Only those interfaces are selected where all three regular expressions match.
However, for reports where interfaces are not relevant, interfaces are disregarded.

The regular expression for interfaces is applied to both the interface’s ifDescr and Description properties in parallel, and a match for either or both selects the interface.
(The NMIS GUI presents ifDescr as “Name” or “Name (ifDescr)”. Depending on the device and its modelling ifDescr may or may not be adjustable, but Description can be set easily within NMIS.)

In the GUI this option is called “by Regular Expression for a Nodes and Interfaces Report per Group”.
The report schedules requires that you supply group_each_regexp= AND node_regexp= AND node_intf_regexp=.

All three regular expressions are evaluated at report creation time.

Explicitly listed Nodes

In the GUI this choice is called “Pick from Node List”.

To use this mechanism with opreports-cli, you have to list each node you want in a separate nodes= argument.

In a report schedule the property nodes would have to be set to an array of node names, like in this example:

"nodes" : [
  "ASGARD",
  "midgard"
],

Nodes listed in a file

opReports expects a node list file to contain one node name per line. Whitespace before or after the node name is removed.

In the GUI this choice is called “from Node List File (Upload)”, and you need to select a suitable file for uploading.

For opreports-cli, the command line argument node_list= would be used. In that case the node list file must already reside on the opReports server.

In a report schedule definition, you’d use the property node_list, with the path to the list file as value:

node_list" : "/tmp/my_list_of_lotsa_nodes.txt

Nodes and specific Interfaces, listed in a file

Certain reports allow a more precise selection of nodes and just some of their interfaces. This is implemented using a list file.

In the GUI you’d select “from Node and Interfaces List File (Upload)” and upload the file of choice. For opreports-cli you use node_intf_list=, and for a scheduled report you would set the property node_intf_list with the value being the path to the list file.

The node and interface list can be in one of two formats, JSON or plain text:

JSON: it must be a valid JSON document, consisting of a hash of the node name as key, and the value being a list of the interfaces in question.

{ "testnode": [ "eth0" ], "othernode" : [ 1, 2, "Tunnel20" ] }

Plain Text: a text file, one entry per line.
Each entry must start with the node name, followed by one or more TAB characters, and one or more interfaces (again separated by TAB characters). If you list a node on multiple lines then all listed interfaces will be combined into a single list. Blank lines and lines starting with the “#” sign are treated as comments and are ignored.

testnode   2   14    eth0
othernode  Dialer1
testnode   17

For both JSON and Plain Text formats, interfaces can be identified by the numeric SNMP interface index, or by the SNMP ifDescr property.

Nodes, specific Interfaces and Types, listed in a file

Certain reports offer a refinement of the above, with the added notion of a “Type” for grouping of Node+Interface into particular reporting classes.
This is implemented again using a list file, but with a very specific format – which has a few inherent limitations.

The relevant GUI choice is called “from Node, Interfaces and Type List File (Upload)”, for opreports-cli the parameter is node_intf_type_list=, and in a report schedule the controlling property is node_intf_type_list (value again the path to the list file).

Plain Text Format

The list file format is plain text, and each line must consist of precisely one node name, one of its interfaces and a “type” declaration. The interface must be identified by its SNMP Interface Index.

Node name and interface must be separated by “_”, and this must be separated by the “type” by one or more spaces, like in the example below:

nodeA_1 groupA
nodeB_41 groupB
nodeC_41_eth0 groupB

The example also shows an optional format variant: the node+interface stanza may include a trailing “_”, but the interface description is not used for the selection logic: only the SNMP Interface Index is relevant. It is recommended that you do not use this flavour as it’s ambiguous: interface descriptions can (and often do) include both _ and space characters.

The “type” will be used to group all nodes and interfaces with the same type value into a group for summary reporting.

CSV Format

opReports now also supports CSV (with comma as the separator character) for this kind of input.
The lines in your file must contain at least the following four columns, in the following order:

The node name,
the SNMP Interface Index (must be present but may be empty if the Interface Description is given)
the Interface Description (must be present but is ignored if an SNMP Interface Index is given),
the “type” declaration.
Extra columns are ignored; files with fewer columns are rejected. Empty lines and comment lines (ie. lines starting with a “#” character) are ignored.

For extra convenience you may now also specify interfaces by their Interface Description instead of the Interface Index; both columns must be present in your input, but one of them may be blank.
The SNMP Interface Index is considered authoritative, if given. If it is not, then opReports looks for an interface with the given Interface Description. Nonexistent interfaces are skipped, and a warning message is logged.

Here is an example CSV file:

# comment, ignored. columns: nodename,interface index,interface description,type name
"some node","1","FastEthernet0/0","categoryA"
"not_the_greatest_name","10","Dialer1","catB"
"pleasefindme",,"Dialer1194","categoryA"
"iknowtheindex",12,,"catB"

Nodes and Interfaces that are part of an opCharts Business Services

If you have opReports version 3.0.14 and newer and opCharts is installed on the same system, then you can make use of Business Services to declare nodes and interfaces for reporting.

Configuration

The following three configuration options (in conf/opCommon.nmis) are vital for opReports accessing opCharts:

# base of opCharts server url, eg http://localhost or http://localhost:80 - no slash at the end
'opreports_opcharts_url_base' => "http://127.0.0.1:8042",
'opreports_opcharts_user' => "nmis", # opreports needs a user with readonly-access
'opreports_opcharts_password' => "nm1888",

If you’ve changed the password for the default nmis user (or disabled it altogether), then these configuration items need to be adjusted accordingly.
Once that’s done you need to restart the OMK webserver (using sudo service omkd restart) to activate the changed configuration.

Usage

In the GUI you will be presented with a list of known Business Service names, which supports multiple selections.

When using opreports-cli, the parameter is called business_services and you need to pass in each business service name separately, e.g. opreports-cli.pl type=health business_services=first_service business_services=second_service.

In a report schedule file, the property is called business_services and its value must be a list of business service names.

Business service memberships are expanded at report creation time.

opReports Report Descriptions

Node Report

The Node Report provides a detailed summary of one node.

Node Health Report

The Node Health report display health-related attributes for all selected nodes for a given period.

Configuration Summary Report

The Configuration Summary report displays an overview of one or more node's configuration items.

WAN Report

The WAN report displays the WAN Link performance for selected nodes.

WAN Utilisation Distribution Report

The WAN Utilisation Distribution Report displays the combined, input and output utilisation frequency distributions for configured distribution groups.

WAN Utilisation Distribution Summary Report

The WAN Utilisation Distribution Report displays the combined, input and output utilisation frequency distributions for configured distribution groups.

QoS Report

The QoS report is intended to provide an overview of (Cisco-type) Class-based Quality of Service configuration and utilisation of the selected nodes.

CoS Report

The new Class of Service report covers Quality/Class of Service as implemented by Juniper devices.

Uptime Report

The uptime repors provides an overview of recently restarted devices, as well as very long running ones.

Response Time Report

The Response Time report tabulates the selected nodes in descending order of their average response time.

Interface Utilisation Report

The interface utilisation report shows the interface utilisation statistics for one or more interfaces.

Interface Unicast Packets Report

The Interface Unicast Packets report displays the ifInUcastPkts and ifOutUcastPkts statistics for one or more interfaces.

CPU Report

This report shows the average CPU utilisation for Cisco devices, for both 1-minute and 5-minute averages.

Free Memory Report

This report shows the free memory statistics for Cisco devices.

Memory Pool Report

This report shows the memory pool statistics for Cisco devices.

Monitored Services Report

This report provides an overview of monitored services availability and downtime both for a given period and as a percentage of the given period.

Traffic Usage Report

This report displays the cumulative traffic usage figures for one or more interfaces.

Traffic Summary Report

The traffic summary report provides a specialized report of categorized and grouped traffic figures for any number of nodes and interfaces.

Node Availability Report

This report provides an overview of nodes' reachability and down time for a given period

Grouped Availability Report

The Grouped Availability Report computes reachability statistics similar to the Node Availability Report, but devices are then categorised based on their overall availability metric.

Interface Capacity Report

The interface capacity report displays a comparison between configured interface speeds and observed actual bandwidth figures.

Grouped Interface Capacity Report

The Grouped Interface Capacity Report displays a comparison between configured interface speeds and observed actual bandwidth figures.

Traffic Snapshot Report

The snapshot report type produces a table of interface utilisation versus interface capacity for one or more groups of interfaces.

UPS Configured Models Report

The UPS Configured Models Report displays UPS models configured under 'report_ups_configured_models' in opCommon.nmis configuration file.

Node Report

The Node Report provides a detailed summary of one node. Node details such as status, sysName, ip address, type, model, uptime, interfaces, location, contact, description, last update, vendor, object name, group role and net and the interface table are presented.Interfaces and storage items are details if present. Graphs are provided which details the following: reachability, availability and health, response time, CPU utilisation, number of routes, ip utilisation, IP fragmentation/reassembly (as a % of packets received), buffer utilisation.

Items of note:

  • This report cannot be created for more than one node. If your node selection contains more than one node, then the report is created for the first node in your list.
  • This report relies directly on NMIS for inline graphs, and therefore won’t work unless the configuration item nmis_host_base is correctly set (i.e. has the public web address of your NMIS server).
  • Business Hours reporting is not supported for this report.
  • This report cannot be generated in formats other than HTML.
  • While it can be saved it is not self-contained (the NMIS graphs are live and created on viewing!), therefore it’s primarily of use as an on-demand report for immediate consumption.

The screen shot below shows the Create On-Demand Report menu. From this menu you can create any of the reports that opReports has to offer.

Number Configuration Option Description
1 Report Description Description of the report.
2 Report Type The type of report to run.
3 Node Selection This selects the node that the report will be run on.
4 Start Date/Time The time and date the report starts adn how long it runs for.
5 From Hours The preferred hours the report gathers data.
6 WAN Report Level Default or Full Detail. Controls the amount of detail; given by the report.
7 Utilisation Threshold The desired interface utilisation threshold value (in percent), default: 80%.
8 Authorized Viewers What groups are allowed to view the report.

The screen shots below show examples of some of the details of a default Node report on a device.

Node Health Report

The Node Health report display health-related attributes for all selected nodes for a given period. Attributes displayed are: Status, Device, Availability, Interface Availability, %CPU, 95th% CPU, Max %CPU, CPU Exc., %Mem Free, 95th% Mem Used, Max %Mem Used, %Mem Util, %IO/VIR Mem Free, 95th% IO Mem Used, Max %IO Mem Used, %IO/VIR Mem Util. As of version 3.1.4 when this report is exported to XLSX and CSV formats the following columns of information are also displayed: Group, %IO Mem Free.

The report also includes two columns with the detected (abnormal) Conditions and the recommended Actions.

If you pass this report the option exceptions=true, then only nodes with exceptional conditions present are shown; the default is to show all nodes.

Below shows the outcome of a default Node Health Report or where exceptions=false.
To create a Node Health Report showing exceptions only, click the box that the arrow points to in the image below.
A Node Health Report using the same devices where exceptions=true looks similar to the image below.

The formulas used for calculation of the reporting conditions can be tuned and adjusted by the user:

The section opreports_rules (in conf/opCommon.nmis in opReports 3.x, or opReports.nmis in version 2.x) defines the threshold values for the following conditions:

Device Availability = Condition: “Device has LOW or VERY LOW availability”

Action: Investigate causes for low availability

Formula used for Calculation:

  • Very Low device availability less than 99.9
  • Low device availability less than 99.999
Interface Availability = Condition: “Device has LOW or VERY LOW interface availability”

Action: Investigate causes for low interface availability

Formula used for Calculation:

  • Very Low interface availability less than 80
  • Low interface availability less than 95
CPU Utilisation = Condition: “Device has VERY HIGH, HIGH or MODERATE CPU utilisation”

Action: Investigate causes for CPU utilisation

Formula used for Calculation:

  • Very High CPU utilisation: greater than 30%
  • High CPU utilisation: greater than 20%
  • Moderate CPU utilisation: greater than 12%

If the node has multiple CPUs then the utilisation measure is averaged over all CPUs.

CPU Exceptions

The count of times the CPU utilisation exceeded the “CPU Exception Threshold” of 20%. If the node has multiple CPUs then this is the sum of the exception counts of all CPUs.

Memory Utilisation = Condition: “Device has VERY LOW or LOW main memory free”

Action: Investigate causes for free low main memory

Formula used for Calculation:

  • Very Low free main memory less than 10
  • Low free main memory less than 25
IO or Virtual Memory Utilisation = Condition: “Device has VERY LOW or LOW IO or Virtual memory free”

Action: Investigate causes for low free IO or Virtual memory

Formula used for Calculation:

  • Very Low free main memory less than 10
  • Low free main memory less than 25

Configuration Summary Report

The Configuration Summary report displays an overview of one or more node’s configuration items, grouped into three categories:

  • The most essential polling-related options.
  • The services that are checked for the given node
  • And all monitored elements for said node. Monitored elements in this context means the elements that NMIS collects performance data for and for which an alert, custom alert (threshold rising/falling), or threshold do exist.
  • This report type is optimised for XLSX output, but HTML and CSV output types are available as well.

This report produces a snapshot of the status at report generation time; report start and end periods do not apply and are ignored.

Below are screenshots of the report and it is broken into three major sections:

  • The first category in the report displays an overview of the selected device(s).
  • The second row displays the services that are checked for the given node(s).
  • The last row shows all monitored elements for the node(s).

WAN Report

The WAN report displays the WAN Link performance for selected nodes. Node details displayed are: status, conditions, actions, device, availability and response time.

For each interface on the node, the following are displayed: interface, speed, average utilisation, maximum utilisation, average inbound errors (in %), average outbound errors (in %), average inbound discards (in %), average outbound discards (in %), average inbound utilisation (in %), average outbound utilisation (in %), maximum inbound utilisation (in %), maximum outbound utilisation (in %).
The WAN report health rules are configurable (section opreport_rules) and the report type supports customisable detail levels for the display.

Formula used for Calculation

Maximum and Average input and output utilisation is calculated for the interface. The larger of maximum and average input and output utilisation is used in formula.

Link Availability = Condition: “Router has LOW interface availability”
Action: Investigate carrier for interface problems
Interface availability less than 99.9%

Link Availability = Condition: “Router has VERY LOW interface availability”
Action: Investigate carrier for interface problems
Interface availability less than 95%

Over-utilised Links = Condition: “WAN link has VERY HIGH utilisation”
Action: Investigate WAN Upgrade Urgently
Average link utilisation is above 80% average utilisation

Over-utilised Links = Condition: “WAN link has HIGH utilisation”
Action: Investigate WAN Upgrade
Average link utilisation is above 65% average utilisation

Links Considered Normal = Condition: “WAN link has acceptable utilisation”
Action: WAN utilisation is OK
Average link utilisation is less than 65%

Input and/or Output Errors = Condition: “WAN link has input/output errors”
Action: Investigate cause of interface errors, likely transmission
Error rates higher than 1% of input or output packets

Input and/or Output Discards = Condition: “WAN link has input/output discards”
Action: Investigate cause of interface discards, likely related to QoS or buffer overruns.
Discard rates higher than 1% of input or output packets

WAN Utilisation Distribution Report

The WAN Utilisation Distribution Report displays the combined, input and output utilisation frequency distributions for configured distribution groups. The WAN Utilisation Distribution Summary Report displays only the combined utilisation frequency distribution for configured distribution groups.

Setup:
  • Choose the relevant WAN Utilisation Distribution Report option under Create New Report >> General >> Type
  • Choose whether to Show 95th Percentile and choose the desired WAN Utilisation Distribution Levels under Create New Report >> Layout
Customized WAN Utilisation Distribution Levels:

Two default configured distribution groups are provided: Default WAN Distribution Levels Descending and Default WAN Distribution Levels Ascending.

The default groupings for both of these default options are:

  • <=30%
  • >30% and <=70%
  • >70% and <=90%
  • 90%.

Customised groupings can be added to the opReports WAN Utilisation Distribution Levels displayed under Create New Report >> Layout described under Setup above, by adding distribution grouping in the correct format (as provided for either of the aforementioned default options) under the report_wan_distributions setting in /path/to/omk/config/opCommon.nmis.

Column order can be customised by setting appropriate group names: group names are sorted ascending: group1 will display before group2, group2 before group3, etc.

Here are the default configuration options as provided in opCommon.nmis:

'report_wan_distributions' => {
  'Default WAN Distribution Levels Descending' => {
    "group4" =>{
      "description" => "<=30%",
      "min" => 0,
      "max" => 30,
    },
    "group3" => {
      "description" => ">30% <=70%",
      "min" => 30,
      "max" => 70,
    },
    "group2" =>{
      "description" => ">70% <=90%",
      "min" => 70,
      "max" => 90,
    },
    "group1" => {
      "description" => ">90%",
      "min" => 90,
      "max" => 1000000,
    },
  },
  'Default WAN Distribution Levels Ascending' => {
    "group1" =>{
      "description" => "<=30%",
      "min" => 0,
      "max" => 30,
    },
    "group2" => {
      "description" => ">30% <=70%",
      "min" => 30,
      "max" => 70,
    },
    "group3" =>{
      "description" => ">70% <=90%",
      "min" => 70,
      "max" => 90,
    },
    "group4" => {
      "description" => ">90%",
      "min" => 90,
      "max" => 1000000,
    },
  },
}
Technical Notes:

% Util Max of In/Out Max column is calculated from the the maximum, not the average, of combined ‘in and out’ MAXIMUM utilisation.
95th Percentile Max % column is calculated from the the maximum, not the average, of combined ‘in and out’ 95th percentile utilisation.

Example:

Below is an example screenshot of a WAN Utilisation Distribution Summary Report with Show 95th Percentile selected and using the Default WAN Distribution Levels Descending default configured distribution group.

QoS Report

The QoS report is intended to provide an overview of the Quality of Service configuration and utilisation of the selected nodes.

Rules

To assist in the assimilation of the data, a few simple rules have been applied to the statistics to assist with highlighting some possible problem areas.

Queue Drop

/path/to/omk/conf/opCommon.nmis config option opreport_rules/qos_droppkt (default 1) applies:
This condition indicates that a QoS Policy is being exceeded and packets in this class have been dropped. It may or may not be impacting applications, depending on how they handle packet loss. For example, HTTP will generally handle packet loss with no problems, while voice and video do not suffer packet loss very well at all.

IF an interface utilisation is greater than 0% input and 0% output;
AND DropPkt is greater than opreport_rules/qos_droppkt (default 1) packet per second;
THEN this class is highlighted yellow.

Class Under Utilised

/path/to/omk/conf/opCommon.nmis config option opreport_rules/qos_lowutil (default 1) applies:
This condition indicates that the QoS class was configured to be used for traffic, and there are VERY low levels of traffic in that class. It might be possible to update the QoS policy allocating some of this bandwidth to other classes.

IF an interface utilisation is greater than 0% input and 0% output;
AND the Policy Percent is greater than 0 percent;
AND PrePolicyUtil is less than opreport_rules/qos_lowutil (default 1) percent;
THEN this class is highlighted yellow.

Class Utilisation Exceeding Policy

This condition indicates that QoS class was configured for a certain bandwidth and the traffic levels have exceeded the configured policy. This may not be a problem, depending on QoS configuration, traffic may be being forwarded or discarded, if necessary increase the bandwidth allocated to this class.

IF an interface utilisation is greater than 0% input and 0% output;
AND PrePolicyUtil exceeds the classes configured bandwidth Percent;
THEN this class is highlighted yellow.

CoS Report

The Class of Service report is intended to provide an overview of the Quality/Class of Service configuration and utilisation of the selected Juniper devices.

It presents for each selected Node, Interface and Class, the Policy/Interface Speed, the average Utilisation of the class, the 95th percentile of the class Utilisation, the percentage of dropped bytes and the cumulative Class Usage or traffic.

Level Coloring Options
The report offers configurable level coloring for the utilisation, 95th percentile and drop percentage columns (separately):
The named set of coloring rules is selected in the report scheduling GUI in the Layout tab, under “Level Color Scheme”.

opReports ships with one rule set called ‘default’, and you can configure further sets by editing conf/opCommon.nmis.

Here is an excerpt of the ‘default’ rule set:

'report_jcos_levels' => {
  'your ruleset name' => {
     'util' => {
            'ok' => { description =>  "<70%", threshold => -1, color => "" },
            'yellow' => { description => ">70%", threshold => 70, color => "#ffff00" },
...
     },
     'util95th' => {
...  },
     'dropped' => {
...  }
  },
},

The format is quite straightforward: The section named util sets the rules for coloring the Class Utilisation column, similar for util95th and dropped.
Each section consists of a number of named rules and properties:

  • The color property sets the HTML/CSS background color for the cell.

    Empty means no background color.
  • The description text is used for the color legend.
  • The threshold sets the minimum value for the rule to apply.

    The rule with the lowest threshold value that is equal to or greater than the measurement is the one that controls the coloring.
  • The rule name is used only for CSV output, where colors are not possible.

    For CSV outputs, the rule name is shown in a separate “Status” column.
Data Source Considerations

The Juniper CoS implementation does not support Class-level speeds; opReports therefore applies the configured interface speed as the Policy Speed. Any misconfigured interface speeds will badly affect the report output.

Class Utilisation is calculated based on the “Queued Bytes” measurement. The Dropped Bytes percentage is computed as the difference between “Queued” and “Transmitted” bytes relative to “Queued” bytes. Class Usage or total cumulative traffic is computed based on “Transmitted” bytes.

Uptime Report

The Uptime Report provides an overview of recently restarted devices, as well as very long running ones.

The configuration items uptime_shortest_days (default 7) and uptime_longest_days (default 365) define which nodes should be selected for display.

Response Time Report

The Response Time report tabulates the selected nodes in descending order of their average response time. Besides the average and maximum measurements, the report also shows the 95th percentile of the response time. These readings are in milliseconds.

Response Time Exceptions

This column shows the number of times a device’s response time has exceeded the exception threshold during the reporting period. This threshold is configurable (/usr/local/omk/conf/opCommon.nmis, property response_exception_threshold), and its default value is 10 ms.

Interface Utilisation Report

The interface utilisation report shows the interface utilisation statistics for one or more interfaces. By default it will display the averages for input, output, combined and higher-of-in-and-output bandwidth utilisation, as well as exception counts and cumulative exception period.

Exceptions are defined as any of the utilisation readings rising above option util_threshold (default: 80%). The exception period is defined as all the intervals with over-threshold readings. In addition to those raw readings, the labeling of an interface as in exceptional or normal state is controlled by option util_threshold_mincount (default: 1), which defines how many exceptions have to be observed before the interface is labelled “bad”.

This report can be further adjusted with these options:

  • Option show_threshold (default: true)

    If set to false, no thresholds are shown; instead the bandwidth, average traffic and average utilisation are presented (plus a shortened report period column).
  • Option show_only_util (default: false)

    If show_treshold is false, and if show_only_util is set to true, then only bandwidth and average utilisation are shown (i.e. average traffic is omitted).

Interface Unicast Packets Report

The Interface Unicast Packets report displays the ifInUcastPkts and ifOutUcastPkts statistics for one or more interfaces.

To Create this report choose Interface Unicast Packets Report under Create New Report >> General >> Type

Technical Notes:

In Packets / Sec column is average ifInUcastPkts packets per second.
Out Packets / Sec column is average ifOutUcastPkts packets per second.
95th Percentile In column is 95th percentile of average ifInUcastPkts packets per second.
95th Percentile Out column is 95th percentile of average ifOutUcastPkts packets per second.

CPU Report

This report shows the average CPU utilisation for Cisco devices, for both 1-minute and 5-minute averages.

The image shows a report on a few devices average CPU utilisation.

Free Memory Report

This report shows the free memory statistics for Cisco devices.
The example image shows the average free Memory Proc and the Average Free Memory IO.

Memory Pool Report

This report shows the memory pool statistics for Cisco devices.
The example image shows the average free Memory Proc and the Average Free Memory IO.

Monitored Services Report

The Monitored Services Report can only be configured via View >> Report Schedules >> Create New Report and cannot be run on-demand.

This report provides an overview of monitored services availability and downtime both for a given period (which may include business days and/or business hours filtering) and as a percentage of the given period.
For each selected monitored service the report shows the percentage of time the monitored service was up, down, or partially reachable (i.e. up but packet loss was encountered) as well as the cumulative response time as measured by NMIS while monitoring the service.

There is a configuration setting ‘opreports_ms_availability_strict’ in /path/to/omk/conf/opCommon.nmis which controls the behavior used in calculating availability in the report where NMIS does not contain a particular record for a monitored service.
The default setting is ‘opreports_ms_availability_strict’ => ‘false’ which can be interpreted as ‘monitored service is not down unless NMIS provides an explicit record indicating service was down’.
The setting ‘opreports_ms_availability_strict’ => ‘true’ can be interpreted as ‘monitored service is down where NMIS does not provide a record for the monitored service OR where NMIS provides an explicit record indicating service was down’.

Strict Availability Mode: 0|1 is written to the headings of the generated report to signify which ‘opreports_ms_availability_strict’ setting was used to generate the report.

This report offers optional embedded graphs of each monitored services availability and response time by default, and custom graphs as configured in the NMIS model file for the monitored service. The default choice is to include both the default graphs and custom graphs, but you can change that using the report options Include Embedded Graphs and Include Custom Graphs. The contents of the graph are not configurable, but the desired default size can be set using the configuration option opreports_embedded_graph_size_small (default: 300 pixels wide by 75 pixels high). The width of each graph is reduced dynamically starting from the default size when Custom Graphs are included in the report, but is never less than 50% of the default size. This behavior was implemented as reducing the width of the graphs dynamically by up to 50% was found to improve the viewability of all graphs with less chance of horizontal scrolling, and has minimal effect on interpreting the contents of each graph.

Traffic Usage Report"

This report displays the cumulative traffic usage figures for one or more interfaces. The measurements that are displayed include the node and the interface, and total traffic inbound, outbound and combined (all in Gigabytes), plus a shortened report period column.

Traffic Summary Report

The traffic summary report provides a specialized report of categorized and grouped traffic figures for any number of nodes and interfaces.

This report requires a node_intf_type input file that provides nodes, interfaces and “type” for grouping (see How to select Nodes (and Interfaces) for reporting).

The interfaces are grouped both by their “type” attribute and their average combined utilisation (into categories Low=<45%, Minor=<80%, and Major=>80%).

The report consists of

  • A summary table, which displays for each “type” category the number of interfaces in each utilisation category (and a total)
  • And a details table for each combination of “type” and utilisation categories.

    The details table shows the node and interface, the input and output interface speeds, the average combined traffic and the average combined utilisation, plus a shortened period column.

    For output formats HTML and CSV these tables are shown one after the other. For XLSX, the tables are put on separate worksheets (within a single spreadsheet file).

Node Availability Report

This report provides an overview of nodes’ reachability and down time for a given period (which may include business days and/or business hours filtering).
For each selected node the report shows the percentage of time the node was up, down, or partially reachable (i.e. up but packet loss was encountered), plus the percentage of time where NMIS couldn’t collect any reachability information whatsoever, as well as the cumulative periods for up, down and periods with missing data.

From version 3.0.10 on this report offers optional embedded graphs of each node’s availability. The default choice is to include graphs but you can change that using the report option embedgraphs. In the GUI this option is named “Include Embedded Graphs”. The contents of the graph are not configurable, but the desired size can be set using the configuration option opreports_embedded_graph_size (default: 600 pixels wide by 150 pixels high).

Configurable Graph Colours

It is possible to set different colors for the node state using hex notation using the following variable:

'report_node_availability_colors' =>
{
'down' => '#d9534f',
'unreachable' => '#e6e619',
'up' => '#59cf59',
'partially_reachable' =>'#288a28'
},
Further Configuration

‘opreports_availability_average_packetloss’ in /path/to/omk/conf/opCommon.nmis, controls whether the previous ‘Packet Loss %’ (now renamed ‘Count Packet Loss %’ ) or ‘Average Packet Loss %’ is displayed in this report.
‘opreports_availability_average_packetloss’ => ‘false’ , the default setting, causes ‘Count Packet Loss %’ to be displayed: This can be interpreted as ‘percentage of readings with some amount of packet loss (Count readings with any packet loss / Number of readings)’.
‘opreports_availability_average_packetloss’ => ‘true’ causes ‘Average Packet Loss %’ to be displayed: This can be interpreted as ”Average Packet Loss (Sum of packets lost / Number of readings).

Grouped Availability Report

The Grouped Availability Report computes reachability statistics similar to the Node Availability Report, but devices are then categorised based on their overall availability metric; the report shows these results spread over various summary table sections (for HTML output) or work sheets (for XLSX output). Both business days and business hour filtering are supported. The availability categories can be configured flexibly by adjusting thresholds and settings.

A combined total availability metric for all nodes is computed and presented in a summary section, and similar metrics and categorisation device counts for both grouping by Customer and Group (ie. NMIS configuration properties customer and group) are computed and presented. Finally the detailed availability stats are shown for all devices, in order of the devices’ group memberships. Instead of determining an individual devices availability as the Node Availability Report does, the Grouped Availability Report is based on the overall availability metric and gives a summary of the availability of all the devices within a specific group. The summary section displays the number of devices within that group, the number customers within the group, the number of groups and the overall availability of them. The summary section will display devices with availability of 100%, 99 < 100%, 98 < 99%, and < 98% to easily understand if any group of devices has had unexpected downtime. The Grouped Availability Report also displays the Down%, Packet Loss %, No Data %, Uptime, and Downtime for a quick look at overall network health. The Grouped Availability Report can be configured flexibly by adjusting the threshold settings of report_groupedavailability_levels in /usr/local/omk/conf/opCommon.nmis

'report_groupedavailability_levels' => {
      'default' => {
        'good' => {
          'color' => '',
          'description' => '100%',
          'threshold' => 100
        },
        'high' => {
          'color' => '#ffff00',
          'description' => '99 < 100%',
          'threshold' => 99
        },
        'low' => {
          'color' => '#ff8900',
          'description' => '98 < 99%',
          'threshold' => 98
        },
        'lowest' => {
          'color' => '#ff0000',
          'description' => '<98%',
          'threshold' => -1
        }
      }
    },

Interface Capacity Report

The interface capacity report displays a comparison between configured interface speeds and observed actual bandwidth figures.

For each selected interface, it shows the configured input and output speeds, the observed maxima of input and output bandwidth for the report period, and the 95th percentile of the interface utilisation.
Before version 3.0.14, the 95th percentile for combined interface utilisation was shown (Combined utilisation in this report means the set of averages of each input and output utilisation reading). From 3.0.14 onward, you can select from three options: the 95th of combined utilisation, two separate columns for 95th of input and output utilisation, or three separate columns for 95th of input, output and combined utilisation.

In the HTML output format all interface speed and bandwidth figures are auto-scaled and shown with the most appropriate unit, whereas CSV and XLSX outputs contain the unscaled data in bits per second.
From version 3.0.10 on this report offers optional embedded graphs of each interface’s capacity. These graphs show the observed input and output bandwidth (input in green, output in blue), and the higher of the configured in and out speeds as a red warning line. If the configured input and output speeds are identical, the 95th percentile of the combined interface utilisation is also shown as a dotted line.

The default choice is to include graphs but you can change that using the report option embedgraphs. In the GUI this option is named “Include Embedded Graphs”. The graph contents are not configurable, but the graph size can be adjusted using the configuration option opreports_embedded_graph_size (default: 600 x 150 pixels).

Grouped Interface Capacity Report

The Grouped Interface Capacity Report displays a comparison between configured interface speeds and observed actual bandwidth figures.

Statistics are shown for all devices in order of the devices’ Group Membership (ie. NMIS configuration property ‘group’).

To setup, choose Grouped Interface Capacity Report under Create New Report >> General >> Type

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.

Sample report and how to configure to the right

Number Configuration Option Description
1 Title Page title. Every page can have its own title; If not set, “Page ” is used.
2 Summary Title This title text is shown before the Summary Table. If not set it’s omitted.
3 Table Column Heading The heading is meant for the first column in the table, which enumerates the Business Services you’ve selected. If not set, then “Interfaces” is used.
4 Peak Type The “Peak Utilisation” can be the combined sum of utilisation figures across the group, or the utilisation of one “busiest” interface.
5 Capacity Type The “Capacity” can be the combined sum of capacities across the group, or the capacity of the one “slowest” interface.
6 Graph Order Graphs for the interfaces of a given Business Service can be grouped horizontally or vertically.
7 Graph For each interface, the named NMIS graph is generated.
8 Level Color Scheme Coloring scheme for utilisation levels

Report-Specific Settings

Multiple Pages for Traffic Snapshot Report

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 ” 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.
Value: either same_row or same_column. Optional; default is same_column, i.e. a vertical arrangement.
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 displayed 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.

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 combined or slowest. Default is combined.
Combined: The overall capacity for the interface group is defined as the sum of all involved interfaces’ configured capacity.
Slowest: The overall capacity is defined as the capacity of the slowest interface, ie. the one with the lowest configured capacity.

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"]
    }]
}

UPS Configured Models Report

The UPS Configured Models Report displays UPS models configured under ‘report_ups_configured_models’ in opCommon.nmis configuration file.

Setup:

Firstly edit /path/to/omk/conf/opCommon.nmis setting report_ups_configured_models.

This configuration setting need only be set once, as needed, to configure the UPS models to be returned in the report.
The following are the default settings:

'report_ups_configured_models' => {
    'POWERALERT-APC' => {
        'exclude_nodegraphs_in_this_report_type' => 'health,upspwr,upsbattemp'
    },
    'POWERALERT-ups' => {
        'exclude_nodegraphs_in_this_report_type' => 'health,upspwr,upsbattemp'
    }
},

Pin It on Pinterest