Gadgets

General Information

Gadgets are small programs which generate images from information which is provided by NagVis. The main idea is to provide the performance data of Nagios to these programs for visualizing it as nice graphs or fancy speedometers, thermometers etc.
share/userfiles/gadgets/ contains some examples, others can be found at Nagvis Exchange[1].

The gadgets can be written in any language which can be interpreted by your webserver. Some options can be PHP, Perl,...

Gadgets are only supported for service objects. An object can be turned into a gadget by setting view_type="gadget" and a valid gadget_url.

NagVis supports gadgets since version 1.4.[1]

NagVis 1.4 std_speedometer gadget with label and hover menu

 NagVis 1.4 std_speedometer gadget on test map with enabled label.

Parameters

The gadgets get their information via a HTTP-Get call from NagVis (if you include share/userfiles/gadgets/gadgets_core.php it will be placed in two arrays. For more information take a look at the description there).

The following parameters are being passed to the gadgets:

Parameter Example value Description Variable
name1 localhost The name of the host $aOpts['name1']
name2 Current Load The service description of the object $aOpts['name2']
scale 100 The scale of the gadget $aOpts['scale']
state OK The string which represents the current state (OK, WARNING, CRITICAL, UNKNOWN) $aOpts['state']
stateType HARD The type of the current state. Can be HARD or SOFT $aOpts['stateType']
ack 0 Is set to 1 if the represented object state has been acknowledged (New in 1.5.4) $aOpts['ack']
downtime 0 Is set to 1 if the represented object state is in a downtime (New in 1.5.4) $aOpts['downtime']
perfdata load1=0.960;5.000;10.000;0; load5=0.570;4.000;6.000;0; load15=0.540;3.000;4.000;0; The current performance data information provided by Nagios. It's important to have valid performance data here. $aPerfdata[<index>][<tag>]

A valid http get on the std_speedometer.php looks like this:

std_speedometer.php?name1=localhost&name2=Current%20Load&state=OK&stateType=HARD&perfdata=load1=0.450;5.000;10.000;0;%20load5=0.260;4.000;6.000;0;%20load15=0.750;3.000;4.000;0;

How to configure?

Please check the parameters view_type, gadget_url and gadget_opts of the service object in the map configuration format description. This is an example of a definition in your map file:

define service {
   host_name=localhost
   service_description=root-volume
   x=50
   y=50
   view_type=gadget
   gadget_url=std_bar.php     // name of the file in share/userfiles/gadgets/
   // gadget_url=[http://localhost/nagvis/userfiles/gadgets/std_bar.php]     // valid as well
   // gadget_scale=200        // default is 100 (percent)
   // gadget_opts=columns=3 label=1    // gadget dependent
}

How to create a custom gadget

Using the code shown included in gadgets_core.php two arrays are filled. $aPerfdata contains the performance data. $aOpts contains the options set in gadget_opts.

The best thing is to take a look at the code of the standard gadgets and adapt the core things from there.

You should set a sample perfdata string in the gadget code by writing it to the variable $sDummyPerfdata. This makes it possible to show the gadget with dummy data in the WUI. It's much easier to design the maps in the WUI when the gadgets are shown there.
Important: The variable needs to be set before the gadgets_core.php is included.

A second example can be found in std_speedometer2.php. In contrast to std_speedometer.php it supports output produced by check_multi. The background will be set to yellow or red if the performance data indicates such a state. The service state is not taken into account. Several options set via gadget_opts influence the behaviour of the gadget:
ParameterExample valueDescription
label11 = Show host name / service description in the upper left corner of the graph; 0 = don't show the information (default)
current11 = Show the current performance data value (default); 0 = don't show the information
columns5Graphs can be arranged in columns. The number of rows is calculated based on the maximum number of performance data items. Default is 3
stringpctThe performance data label has to contain the string to be displayed. In case of check_multi output only the last part is examined. Default is an empty string
NagVis 1.5 std_speedometer2 gadget

 NagVis 1.5 std_speedometer2 gadget in normal, warning and critical state

A third example is based on an idea found on Nagvis Exchange. Performance data is shown as a horizontal bar. The last quarter of the graph changes to yellow or red if the performance data indicates a warning or critical value. The status is not the state of the service! That is due to the fact that the data might contain multiple data sources. In many cases not all data sources of a service are found to be in a warning or critical state so you don't want to get false alarms (new in 1.5.7 or git newer than 2010.12.12).

ParameterExample valueDescription
label11 = Show host name / service description label in the last quarter of the graph (default); 0 = don't show the information
current11 = Show the current performance data value (default); 0 = don't show the information
columns5Graphs can be arranged in columns. The number of rows is calculated based on the maximum number of performance data items. Default is 3
stringpctThe performance data label has to contain the string to be displayed. In case of check_multi output only the last part is examined. Default is an empty string
thresholdvalueDetermines if the warning and critical thresholds are shown in percent (default) or integer values
NagVis 1.5 std_bar gadget

 NagVis 1.5 std_bar gadget in normal, warning and critical state

Note: This gadget uses a TrueType font whose name and location is hard coded within the code (variables $fontDir and $fontName). In case the file isn't found the gadget uses a builtin font. The value of $fontDir changes between distributions so if the font doesn't scale properly please check the setting (it defaults to OpenSuSE, other settings are commented out).

[1] The directory structure changed between NagVis 1.4.x and NagVis 1.5. Gadgets were stored in nagvis/nagvis/gadgets and are now stored in share/userfiles/gadgets. Gadgets found on NagVis Exchange might use the former structure so you might have to move the files to the new location (e.g. cp -pr <source>/nagvis/nagvis/gadgets/<gadget> <target>/share/userfiles/gadgets/).