From OpenNMS

This file contains definitions of the graphs that are available (if the right data has been collected for a node or interface) in the Reports section of the web application, either in Resource Graphs or KSC Reports. Each graph definition describes how to extract collected data values from the round robin database (RRD or JRobin) for the time period being looked at, perform calculations on those values if required (e.g. multiplying bits per second by 8 to get bytes per second), and then display them in a graphical form as a line graph, area graph, or various other options.

Historically (i.e. for reasons lost in the mists of time, but probably to do with what was around at the time) this file was for defining graphs of data values collected by SNMP, stored in RRD files, and graphed using rrdtool. This may help explain the name of the file, and some of the syntax and concepts used. However, OpenNMS has come a long way, and the graphs can be generated from any values collected and stored by OpenNMS, not just via SNMP. Further, these days the data is usually stored in JRobin (JRB) files, and graphed using the JRobin library, rather than by a call out to rrdtool.

The format is a standard Java "Properties" file, with all the quoting and escaping rules that implies. See [1] for a description of those rules (does anyone have a link to a canonical document from Oracle/Sun about this?)

Contents 1 Reloading behaviour 2 Configuration properties 2.1 command.prefix 2.2 info.command 2.3 default.report 2.4 output.mime 2.5 reports 2.5.1 Report definition 2.5.1.1 Command 2.5.2 Options supported by JRobin in OpenNMS 2.5.3 Graph/text elements supported by JRobin in OpenNMS 2.6 include.directory 2.7 include.directory.rescan

Reloading behaviour

OpenNMS will automatically reload this file if there are any changes made to it that cause the modified timestamp to increase. If there are problems during the reload (errors in the file), the reloading will stop and you should be left with the graph definitions as they were prior to the reload. However, the only notification of that failure will be in the webapp/web.log log file. So it pays to be careful and pay attention when editing this file. The webapp does not ever re-write this file.

See #include.directory for details of reloads of files from included directories

Configuration properties

The specific properties that are used are as follows:

command.prefix

The initial prefix of all graphing commands, as used to invoke rrdtool. Only used in installations that are still using RRD files for storing data points, which hasn't been the default since 1.3.2. The string {startTime} and {endTime} will be replaced at graph generation time by the epoch-based timestamps of the timespan the graph should display. You probably don't need to mess with this. Ever.

info.command

Also related only to RRD-based installations. No longer used

default.report

If you ask for a graph and don't specify a report (why would you do this?) this is the name of the graph that you'll get.

output.mime

Not used anymore; image/png is assumed and required to be generated by rrdtool or JRobin. The webapp will always send image/png as the mime type.

reports

A comma separated list of the report identifiers of reports defined directly in this file. Whitespace around the identifiers is ignored, so you should use at least a space after each comma, for readability, as shown in the default shipped file. Two important notes:

1. If a report is in this file but is not included in the reports property, it will not be loaded.
2. If a report is mentioned in this list, but is not correctly defined further on in this file, that will cause an error during reload.
   • Prior to version 1.11.0, an undefined or incorrectly defined report listed in reports will interrupt the entire (re)loading process. If this is at startup, the entire web-application will fail to load.
   • From version 1.11.0 and later, an individual mis-defined report will simply be ignored; all other reports should be (re)loaded correctly.

Report definition

Each report defined in snmp-graph.properties requires it's own set of properties. The property names have the form:

report.<report.identifier>.<key>

where <report.identifier> is one of the ids specified in the #reports property earlier in this file. Each report has a number of required keys that need to be defined, and some additional optional ones:

Key	Meaning/Value	Comment	Required?
name	A distinct name for this graph.	Not used by the webapp any more, but can be used to help identify the graph when looking through the file. Still required to be defined	Yes
columns	A comma separated list of the data values used by this graph. These names will be checked against the values collected for a given resource to decide if this graph is available for that resource. The strings '{rrdX}' in the command used to generate will be substituted with the X'th item in this list	These are the names exactly as stored in the round robin (RRD or JRB) data files, and must match.	Yes
type	interfaceSnmp or nodeSnmp	Whether the graph is of data collected at a node-level, or an interface-level	Yes
command	The RRDTool-style command/definition of the graph.	Even JRB-based installations use this command format; internally it is converted to a set of JRobin calls. Is almost inevitably multiline. Details of the format of this value follow below	Yes
width/height	If using a non-default width/height in your graph, specify the width and height here, to enable correct zooming in the web interface	Integers. Must be kept the same as the width/height defined in the command, otherwise interesting behaviour will occur in the webapp when displaying the graph.	No
externalValues	Some graphs require data/values that is obtained from other than the normal data collection. This is a comma separated list of such values	In practice, the only available one is ifSpeed (the speed of an interface	No
propertiesValues	String values that have been collected and stored in the "string.properties" file for each resource (node/interface)	Most useful in titles, for example the hrStorageDesc property collected on the hrStorage table.	No
suppress	This is a comma separated of graph names. If all the data values required to display this graph area available for the resource (node or interface) being looked at, the named graphs will be "suppressed", or hidden and will not be available.	The best example of this is mib2.HCbits which supresses the mib2.bits graph. If the High Speed Counter (64-big) interface values have been collected, the HCbits graph is a much better graph to use than mib2.bits, as it will have less issues with integer overflow of the collected values.	No.

A brief example of a simple graph:

report.mib2.bits.name=Bits In/Out
report.mib2.bits.columns=ifInOctets,ifOutOctets
report.mib2.bits.type=interfaceSnmp
report.mib2.bits.command=--title="Bits In/Out" \
--vertical-label="Bits per second" \
 DEF:octIn={rrd1}:ifInOctets:AVERAGE \
 DEF:minOctIn={rrd1}:ifInOctets:MIN \
 DEF:maxOctIn={rrd1}:ifInOctets:MAX \
 DEF:octOut={rrd2}:ifOutOctets:AVERAGE \
 DEF:minOctOut={rrd2}:ifOutOctets:MIN \
 DEF:maxOctOut={rrd2}:ifOutOctets:MAX \
...REST OF THE GRAPH DEFINITION...

Command

The command is where the guts of the graph definition occurs. The RRDTool graph documentation is frankly the best description of how to define graphs, and when using RRDs and RRDTool for graphing, all of the options available to the version of rrdtool you have installed are available in the graph commands. The JRobin graphing implementation is not as advanced as recent RRDTool functionality, and OpenNMS must currently convert from the RRDTool command line to the JRobin configuration, so only the following graphing options and functionality is supported when using JRobin with OpenNMS:

Options supported by JRobin in OpenNMS

• title
• vertical-label
• height
• width
• units-exponent
• lower-limit
• upper-limit
• base
• rigid
• color. "tags" that can be used:
  • BACK
  • CANVAS
  • SHADEA
  • SHADEB
  • GRID
  • MGRID
  • FONT
  • FRAME
  • ARROW

Graph/text elements supported by JRobin in OpenNMS

• DEF - only the basic DEF:<vname>=<rrdfile>:<ds-name>:<CF> definition; the optional step, start, and end overrides are ignored
• CDEF - As per RRDTool
• VDEF - As per RRDTool, just a consolidation function or a percentile calculation
• LINE[123] - Only supports the basic LINE[width]:value[#color][:[legend] definition. The STACK and dashes configuration options are ignored. Use the STACK element if required
• AREA - Only supports the basic AREA:value[#color][:[legend] definition. The STACK option is ignored (use the STACK element instead)
• STACK - As per RRDTool
• GPRINT - Only supports the (RRDTool deprecated) GPRINT:vname:CF:format definition.
• PRINT - Only supports the (RRDTool deprecated) PRINT:vname:CF:format definition.
• COMMENT - As per RRDTool

include.directory

This is a new property added in 1.10.0 and later. If specified, this defines a directory which will be looked in for files named with the .properties suffix, each defining one or more graphs. If the path doesn't start with a /, it will be considered relative to the directory where snmp-graph.properties is (usually $OPENNMS_HOME/etc/), and the default is therefore $OPENNMS_HOME/etc/snmp-graph.properties.d. Otherwise it is an absolute path. It is recommended to use the default.

This property can only be defined once (you cannot include more than one directory)

Each of the included files can contain either a single graph, or multiple graphs.

• If it includes multiple graphs, it uses the same format as snmp-graph.properties file, e.g. a "reports" property listing the comma separated graph identifiers, and each graph is defined with a set of 'report.<graphname>.<key>' properties. You do not need to, and should not, include the non-report specific properties (like command.prefix) in these files; if you do, the values will be ignored.
• If the included file contains just a single graph, you may (and should) use a short format. In this format an additional key "report.id" defines the internal identifier of the graph, and all the other properties no longer require that identifier in the key. For example, such a single-graph file would look like this:

report.id=mib2.bits
report.name=Bits In/Out
report.columns=ifInOctets,ifOutOctets
report.type=interfaceSnmp
report.command=--title="Bits In/Out" \
 --vertical-label="Bits per second" \
...REST OF THE GRAPH DEFINITION...

The name of the included files does not matter, other than that they must end in '.properties' to be picked up. However, for single-graph files, it is recommended to use the graph identifier in the filename, for ease of finding it later.

A graph defined in an included file with the same identifier as one in the main snmp-graph.properties file will override the one from the main file. Therefore, for best results, it is recommended to leave snmp-graph.properties as supplied by the OpenNMS installation, and to define any graphs you want in the snmp-graph.properties.d directory. If you need to modify one of the base supplied graphs, simply redefine it in an included file using the same identifier. When you next upgrade, your customisation will remain intact, and you can evaluate whether you wish to revert to the supplied graph (if it has been modified since the previous release).

Defining the same two graphs with the same identifier in two separate files will result in undefined behaviour. One of them will override the other, but it's not defined which one will win. It might be alphabetical based on the filename, but that's really up to the Java Runtime Environment's implementation of the File class (i.e. we cannot know for certain). Don't do that; you'll not be pleased with the results.

As with snmp-graph.properties, an included file (that has been successfully loaded once) will be automatically reloaded if the file changes. If the file is found to be malformed and cannot be read successfully, the graphs previously defined in it will remain defined and the malformed graphs will be ignored.

include.directory.rescan

This is a new property added in 1.10.0, and only makes sense if include.directory is specified. This property defines the minimum interval at which the include directory will be rescanned for new .properties files, in milliseconds. The default is 300000, or 5 minutes. When a graph is requested, if it's been more than this time since the last scan of the include directory, a rescan is initiated to look for new files.

If a new .properties file is malformed (either a single graph file with no valid graphs, or a multi-graph file with one or more invalid graphs), then that will be noted. The file will be re-loaded when it's timestamp next changes and you will not have to wait for the rescan interval to pass.