4.5. Data Display

The second part of the configuration related to the monitoring data is the set of rules that define display of the data in the UI. These rules are defined in one of the configuration files. Here is how it looks like:

variables {

    ifInRate: {
        category: Interface,
        group: Utilization,
        column: In,
        description: "Inbound traffic through interface",
        unit: "bit/sec",
        significantFigures: 3,
        range: [0, auto],
        scale: auto,
        prefix: auto
    },

    ifOutRate: {
        category: Interface,
        group: Utilization,
        column: Out,
        description: "Outbound traffic through interface",
        unit: "bit/sec",
        significantFigures: 3,
        range: [0, auto],
        scale: auto,
        prefix: auto
    },

Variables ifInRate and ifOutRate are part of the standard set of variables so the configuration shown here is also part of the standard NSG installation. It is shown here only for illustration purposes.

First, all variable definitions are located inside of the configuration section variables. Data display parameters for each variable are grouped in a dictionary that can have the following set of keys:

category, group and column

Monitoring variables are organized in a three-level hierarchy, built using parameters category, group and column. Device Details panel uses these three levels as follows:

  • categories are used for tabs “Interface”, “CPU”, “Temperature” etc
  • groups are used for the top level column headers
  • columns are used for the second level column headers.

For example, interface utilization variables ifInRate and ifOutRate have category “Interface”, group “Utilization” and column “In” and “Out”. This means they appear in the tab “Interface” in columns with headers “In” and “Out” and the top level header that spans both columns and says “Utilization”.

Graphing workbench uses only “Category” attribute to group variables by category.

description

This parameter allows you to provide description of the variable. Description appears in the Graphing Workbench when you select a variable.

unit

Measurement unit for the variable.

Note the difference between unit “byte” and “B”. If the unit is “B” and scale is set to “auto”, NetSpyGlass computes scaling factor assuming the value of the variable assuming one “kilobyte” is equal to 1024 bytes. This only works if the unit is exactly equal to “B” and is typically only used for variables that monitor amount of system memory or swap. In all other cases automatic scaling algorithm assumes “kilo-” means “1000”.

significantFigures

Values can be rounded to the fixed number of significant figures specified by this parameter. Note that this is different from rounding to the fixed number of decimal places.

accuracy

Values can be rounder to fixed number of digits to the right of the decimal point. If accuracy > 0, it is used. Otherwise significantFigures is used.

range

the range of values for this variable. Range is used to configure Y axis in graphs. This parameter is defined as a list of two items, each can be either a number or word ‘auto’. If either side of the range is ‘auto’, NetSpyGlass will compute minimum or maximum (or both) of values of the variable within graph’s time interval and use this for the Y axis.

Interface-related variables can also use word ‘speed’ for the maximum side of the range, in which case Y axis will be scaled to interface speed.

Example of setting Y axis range to ‘auto’ for the inbound interface utilization:

ifInRate: {
    category: Interface,
    group: Utilization,
    column: In,
    unit: "bit/sec",
    range: [0, auto],
},

Setting Y axis range to interface speed for the inbound interface utilization:

ifInRate: {
    category: Interface,
    group: Utilization,
    column: In,
    unit: "bit/sec",
    range: [0, speed],
},

Here is how we can make the range fixed for the variable where it makes sense:

cpuUtil: {
    category: CPU,
    column: "CPU utilization",
    group: CPU,
    description: "CPU utilization",
    unit: %,
    range: [0, 100.0],
},

scale

A number or word ‘auto’. This parameter tells NetSpyGlass if it should try to scale the value of the variable before the display to make it more human-friendly. If the parameter is set to ‘auto’, the program will try to pick most appropriate scaling factor to make scaled value compact. For example, 1000000 bits/sec will be converted to 1 Mbit/sec by choosing scaling factor 10E-6.

If scale is set to 1.0 or any other number, automatic scaling is not done but values are just multiplied by this number before the display.

prefix

This parameter can be either a string or word ‘auto’. It works in combination with scale when both scale and prefix are set to ‘auto’. When NetSpyGlass chooses scaling factor, it also assigns corresponding prefix to the parameter ‘prefix’. In the example above value 1000000 bit/sec can be converted to 1 Mbit/sec by choosing scaling factor 10E-6. When this happens, prefix is assigned value of ‘M’. Prefix is used in combination with unit, making the result ‘Mbit/sec’ when unit is ‘bit/sec’.

zeroThreshold

If > 0.0, then it is interpreted as fraction of the maximum range of values of the variable and all values below this threshold are rounded down to zero. For interface traffic-related variable the maximum value of the range is interface speed, therefore zeroThreshold defines fraction of the speed. Absolute value of the threshold is then equal to speed * zeroThreshold. If zeroThreshold is equal to “1E-5” and interface is a Gigabit Ethernet (speed = 1E9 bits/sec), then the value of the threshold is equal to 1E9 * 1E-5 = 1E4 or 10 kbit/sec. Any values lower than this will be rounded down to zero. User with caution because this distorts actual measured values when they are displayed and makes it impossible to compare very small levels of traffic across interfaces. Default value of zeroThreshold is “0.0”, therefore it is not used.

The main use case for the parameter zeroThreshold is to display very low levels of traffic going through high-bandwidth network interface as zero. Use with caution because with this parameter activated, two variables may appear to have the same value of zero, while in reality they may have different very small values. By default this parameter is turned off. This parameter does not affect values shown in graphs.

Here is an example:

# Change some defaults
variables {

    ifInRate.range = [0, auto]
    ifInRate.accuracy = 2
    ifInRate.zeroThreshold = 1E-4

    ifOutRate.range = [0, auto]
    ifOutRate.accuracy = 2
    ifOutRate.zeroThreshold = 1E-4
}

4.5.1. How to change or add data display rules

To change default data display rules or add your own just add corresponding section to your variables.conf file and override corresponding parameters. Here is an example:

# Change some defaults

variables = ${variables} {

    ifInRate.range = [0, auto]
    ifInRate.accuracy = 2

    ifOutRate.range = [0, auto]
    ifOutRate.accuracy = 2

    bgpPeerInUpdatesRate.unit = "prefixes/sec"
    bgpPeerInUpdatesRate.accuracy = 2
    bgpPeerInUpdatesRate.scale = 1.0
    bgpPeerInUpdatesRate.prefix = ""
}

This can be added anywhere in the variables.conf as long as it is at the top level of the hierarchy (that is, it won’t work if you put this inside of the “network” section). If you just want to override one or two parameters, you can use this syntax:

variables.ifInRate.range = [0, speed]
variables.ifOutRate.range = [0, speed]

4.5.2. How to make new variable appear in Graphing Workbench

if your data processing script creates new monitoring variable that is given a name that does not match any of the existing ones, then you need to add some configuration to make it appear in NetSpyGlass UI (this includes Graphing Workbench, maps, and device details panel).

First, add a dictionary inside of variables as shown in the previous chapter to describe the variable itself. You can add this at the bottom of the configuration file variables.conf. Suppose you new variable has name newVar, then this might look like this:

variables.newVar.category = Interface
variables.newVar.group = Counters
variables.newVar.column = Input
variables.newVar.description = "My new input counter"
variables.newVar.unit = ""
variables.newVar.significantFigures = 3
variables.newVar.range = [0, auto]
variables.newVar.scale = auto
variables.newVar.prefix = auto

What we have done so far describes the new variable, but to add it to GW, you also need to define the following:

graphingWorkbench.variables += newVar

This adds new variable to the list of variables that appear in GW.