How to configure performance graphs

WAS THIS PAGE HELPFUL? Leave Feedback

Overview

This section reviews the procedures to create a new or modify an existing performance graph, and how to change the appearance of a graph.

Steps

Creating a New Entry

Select Configuration > Performance.
Select Create New Entry or select the Copy option to copy an existing service definition that come close to what you want. Continue with the steps below to enter or edit the service definition properties.
In most cases, you will want to graph either a number or a percent. The easiest way to do this is to make a copy of an existing configuration entry:
- Copy the GENERIC_NUMBER or GENERIC_PERCENT entry in the performance configuration database, then rename the service name to your entry.
- If performance data is already being generated, this is all you need to do to create the RRD.
- If performance data is not being generated, enter the status parsing regular expression to parse the number or percent from the output text.
- Specify either number_graph.cgi or percent_graph.cgi the CGI graphing program in the Configuration extended information service template. These graphing programs are installed with GroundWork Monitor. If you wish, you can also specify the graph.gif icon. You will need to commit the changes to Nagios in order for the service CGI to appear on the Nagios interface.

Definition Properties

Export File - The entry for this filed is the name of a file in the /tmp directory into which the exported performance config entry will be written. This is just the name of the file itself, not including any preceding path.
Graph Label - Enter a graph label to define the heading for this graph's window in Status viewer.
Service - Enter a service to define the service name for Performance Graphs. The service is a string or expression which must match the name of the service in order for this performance config entry to be applied during performance-data processing. Unless you are also specifying Use Service as a Regular Expression, enter the exact service name to which this entry applies. The service name is case-sensitive. If you have entries for both a specific literal service name and a regular expression that matches the service name, the entry for the specific service name will take precedence.
Use Service as a Regular Expression - If you want this performance config entry to match multiple service names (e.g., snmp_if_interface_1, snmp_if_interface_2, ...), check the "Use Service as a Regular Expression" option. You can then include regular-expression matching syntax in the Service field, and it will be used as a regular expression instead of a simple literal string for matching purposes. Except for service names that match a separate literal-string Service entry, all service names that match this entry's Service field will use this entry to create and update RRDs, and to produce graphs. Be careful with this; if a service name matches the Service field in more than one regular-expression performance-config entry, the system might pick the wrong one to use.
Host - Enter a host name. The host is either a simple literal hostname to match for this entry to be applicable to a service, or a single asterisk (*) character to match all hostnames. If you have an entry for both a specific hostname and a wildcarded (*) hostname for the same service-name matching, the entry for the specific hostname will take precedence.
Status Text Parsing Regular Expression | This field is used when you are working with a plugin that does not return properly formatted performance data. This field is used in conjunction with the next field Use Status Text Parsing instead of Performance Data to enable Perl regular-expression-based parsing of the plugin-output status text to find performance metrics of interest.
- For example, using the regular expression "(\d+) (\d+)" (without the enclosing quotes) will parse through the status text looking for the occurrence of two single- or multiple-digit numbers separated by a single space character. These numbers would be captured as $VALUE1$ and $VALUE2$ and could be passed to the RRD create and/or update commands using those variable names. The end result would be that numbers were extracted from the status text field of the plugin output and inserted into performance graphs despite the fact that the plugin returned no performance data in the standard plugin-output format for such data.
  Note: Parentheses in a regular expression are needed to specify that the string or value that matches the enclosed part of the regular expression is to be captured into a variable. In the example shown, those variables would be $VALUE1$ and $VALUE2$ .

Use Status Text Parsing instead of Performance Data - This field enables (1) or disables (0) the status text parsing function which is defined by the "Status Text Parsing Regular Expression" described above.
RRD Name - This field defines the absolute pathname of the RRD file that stores accumulated performance data, for each host-service that matches this entry. The following macros may be used as part of the path or filename, to make the RRD file unique to the host-service:
- $HOST$ Name of the host whose service output is being handled by the performance-data processor.
- $SERVICE$ Name of the service whose output is being handled by the performance-data processor.
  
  For example, the following string will create an RRD with the Host and Service name in the RRD file: /usr/local/groundwork/rrd/$HOST$_$SERVICE$.rrd
  The performance-data processor will automatically make certain adjustments to substituted values in order to guarantee that a valid filename is produced, so the final result might be slightly different from what you specify here.
RRD Create Command - Enter this command to define the RRD creation string. The command is used to create a new RRD file if performance data comes in for a host-service for which an RRD file does not already exist. You can reference the RRDtool documentation for RRD file creation options. The following macros may be used:
- $RRDTOOL$ RRDtool program, including file location.
- $RRDNAME$ Name of the RRD file, as defined in this configuration tool.
  Example of an RRD Create Command
  $RRDTOOL$ create $RRDNAME$ --step 300 --start n-1yr
  DS:number:GAUGE:900:U:U
  RRA:AVERAGE:0.5:1:2880 RRA:AVERAGE:0.5:5:4032 RRA:AVERAGE:0.5:15:5760 RRA:AVERAGE:0.5:60:8640

RRD Update Command - Enter this command to define the RRD update string. The RRD Update Command is used to insert a new set of performance-data values into the RRD file. The command must include an associated timestamp used to position the new data in the RRD file.
In each update, the timestamp value must always be larger than the timestamp given in any previous update, or an error will result. Such errors can therefore occur if a performance-data file is reprocessed, but in that case they can be ignored. See the RRDtool documentation for RRD file update options. In addition to the macros mentioned in the help messages for earlier items, the following macro may be used:
- $LASTCHECK$ Service-check time that the plugin executed, in UTC format (whole seconds since the system time epoch).
  Example of an RRD Update Command
  This example updates the RRD file with the first value from the performance data string or status text parse:
  $RRDTOOL$ update $RRDNAME$ $LASTCHECK$:$VALUE1$ 2>&1

Custom RRDtool Graph Command - This command defines how the graph for this service is drawn in the Status viewer. If no graph command is specified here, the graph command defined for the DEFAULT service will be used instead. This setting also affects graphing in the Reports > Performance View application. There are three host-view options in that application, namely "Expanded", "Consolidated by host", and "Consolidated". The Custom RRDtool Graph Command you specify here only affects the appearance of the RRD graph when using the Expanded view. To change the appearance of the graph, see the full documentation available through the Help button on this page, under Custom RRDtool Graph Command.
Enable - The Enable option, if checked, enables this performance-config entry. If disabled (unchecked), RRD creation and updating will not be executed for this entry.

Figure: Creating Performance Graphs

Customizing graphs

To change the appearance of the graph, paste in a command that produces a graph from the command line to the Custom RRD Graph Command field. Any valid command will work, and any RRD accessible will produce a graph, even for an unrelated RRD. However, this is probably not what is desired, so substitution of certain strings is used to produce the desired effect. This process is triggered if the command inserted contains the string "rrdtool graph".

Substitutions:

rrd_source is replaced by the rrd selected by the cgi for the host and service
ds_source_0 is replaced by the first DS
ds_source_N is replaced by the Nth DS in the RRD, where N is an integer

This allows a fair amount of flexibility in specifying what is to be graphed and how.

And there is more; if you place a $LISTSTART$ $LISTEND$ pair in the rrdtool graph command the following values will be substituted:

$DEFLABEL#$ will become the RRD:DS string, repeated in the supplied context as many times as there are DS in the RRD,
$CDEFLABEL#$ will be a short string, to be used to serialize the CDEFS. The strings are taken from the sequence a, b, c, ..., z, aa, ab, ac, ..., az, ba, bb, bc, ..., and so forth.
$DSLABEL#$ will be the DS name, repeated in context as above.
$COLORLABEL#$ will be a color selected from the @colors array, the same one used to select colors in the default graphs. Use it if you don't know (or don't care) what colors get shown.

What this means is that a custom command like this:

/usr/local/groundwork/common/bin/rrdtool graph - \
--imgformat=PNG \
--title="All Disk Partitions" \
--rigid \
--base=1000 \
--height=120 \
--width=500 \
--alt-autoscale-max \
--lower-limit=0 \
--vertical-label="Kilobytes" \
--slope-mode \
$LISTSTART$ \
DEF:$DEFLABEL#$:AVERAGE \
CDEF:cdef$CDEFLABEL#$=$CDEFLABEL#$ \
LINE:cdef$CDEFLABEL#$$COLORLABEL#$:"$DSLABEL#$" \
GPRINT:cdef$CDEFLABEL#$:LAST:" Current\:%8.2lf %s" \
GPRINT:cdef$CDEFLABEL#$:AVERAGE:" Average\:%8.2lf %s" \
GPRINT:cdef$CDEFLABEL#$:MAX:" Maximum\:%8.2lf %s" \
$LISTEND$

Ends up looking something like this:

/usr/local/groundwork/common/bin/rrdtool graph
/usr/local/groundwork/apache2/htdocs/performance/rrd_img/view_1193523936_localhost_All-Partitions_h_1.png
--imgformat=PNG --title="All Disk Partitions" --rigid --base=1000
--height=120 --width=500 --alt-autoscale-max --lower-limit=0
--vertical-label="Kilobytes" --slope-mode
DEF:a=/usr/local/groundwork/rrd/localhost_All_Partitions.rrd:_boot:AVERAGE
CDEF:cdefa=a,8,* LINE:cdefa#8DD9E0:"_boot" GPRINT:cdefa:LAST:"
Current\:%8.2lf %s" GPRINT:cdefa:AVERAGE:" Average\:%8.2lf %s"
GPRINT:cdefa:MAX:" Maximum\:%8.2lf %s"
DEF:b=/usr/local/groundwork/rrd/localhost_All_Partitions.rrd:_dev_shm:AVERAGE
CDEF:cdefb=b,8,* LINE:cdefb#64A2B8:"_dev_shm" GPRINT:cdefb:LAST:"
Current\:%8.2lf %s" GPRINT:cdefb:AVERAGE:" Average\:%8.2lf %s"
GPRINT:cdefb:MAX:" Maximum\:%8.2lf %s"
DEF:c=/usr/local/groundwork/rrd/localhost_All_Partitions.rrd:root:AVERAGE
CDEF:cdefc=c,8,* LINE:cdefc#D3DB00:"root" GPRINT:cdefc:LAST:"
Current\:%8.2lf %s" GPRINT:cdefc:AVERAGE:" Average\:%8.2lf %s"
GPRINT:cdefc:MAX:" Maximum\:%8.2lf %s" --start 1194999156 --end
1195002756 --height 200 --width 600