Grafana

From OpenNMS
Jump to navigation Jump to search

OpenNMS is now on Grafana.net

Grafana 3.0.0 introduced a plugin architecture which allows 3rd party developers (like us) to publish custom extensions. Moving forward we will be using the grafana.net platform to distribute our extensions instead of maintaining system packages.

See OpenNMS Helm Datasource

Overview

Grafana is an open source application for visualizing large-scale measurement data.

OpenNMS maintains a plugin for Grafana that exposes all of the collected metrics i.e. values from .rrd or .jrb files. These metrics are retrieve using the Measurements API via REST.

Metrics from multiple nodes or even multiple instances can be grouped together along with mathematical expressions to form custom charts and dashboards.

Grafana-dashboard-screenshot.png

Grafana Dashboard definition json

Getting Started

See the instructions in the OpenNMS Helm documentation.

Using the data source

The OpenNMS data source provides support for two types of queries: attribute or expression.

Both query types support custom label names, which will appear the in graphs legends, and the option to toggle their visibility (by clicking the eye on the left).

Attribute queries

Attribute queries are used to query a collected attributes.

The node field can take either of the following forms:

  • $nodeId
    • i.e. 5
  • $foreignSource:$foreignId
    • i.e. NODES:N1

The resource field must specify the resource id, without the leading node[] or nodeSource[] components.

i.e. nodeSnmp[]

The attribute field must specify the attribute name. This will be equivalent to the alias set in the datacollection/*.xml files.

Expression queries

Expression queries can be used to perform arbitrary expressions against other queries. The results of an expression query can be referenced by subsequent expressions query (order matters).

The expression field must be a valid JEXL expression that returns a value which can be casted to a double.

The JEXL context includes the result of other queries, with their labels as names.

Here some examples of valid expressions, assuming that there is two other queries with labels 'ifInOctets' and 'ifOutOctets':

  • Linear combinations
    • (ifOutOctets + ifInOctets) * 8
  • Conditionals
    • ifInOctets > ifOutOctets ? 0 : 1
  • Trigonometric expressions
    • math:sin(ifInOctets) * math:cos(ifInOctets)
  • Powers
    • math:pow(ifInOctets, 2)
  • Accessing the timestamp
    • ifOutOctets / timestamp

Template variables

The Grafana system allows you to define a "template variable" that can allow the end user to select custom values for changing the dashboard on the fly. There are two queries that can be customized:

  • To select select specific node(s), modify the filter string based on the filters available.
    • nodeFilter(NODEFILTERSTRING)
  • To select specific resource(s) on a node. See the Attribute queries section above on how to specify a node. This can be the result of another variable with a nodeFilter.
    • nodeResources(NODEID)


Example

Here is an example chart displaying the load averages on a system (via Net-SNMP). Expressions are used to divide the collected gauges by 100.

Grafana-loadavg-expression-example.png

Upgrading to v3.0.0 from a previous version

  1. Upgrade the grafana package to >= 3.0.0
  2. Remove the grafana-opennms-plugin package
  3. Install the datasource plugin using
    sudo grafana-cli plugins install opennms-datasource
  4. Restart Grafana

Now edit your existing datasource definitions, it will probably complain about the (previous) plugin not being found, and set the type to "OpenNMS".

You can now go back to using your existing dashboards on Grafana v3.0.0.

Troubleshooting

  • Verify the URL, username and password in the data source configuration:
    • Append '/rest/nodes' to the URL and try accessing it via curl from the Grafana server with curl -u '$username:$password' $url/rest/nodes to verify.
  • Set access to proxy in the data source configuration:
    • Requests to the OpenNMS instance will be routed through the Grafana server, protecting the credentials from the dashboard users. Setting access to direct requires that CORS be enabled on your instance. See Enabling CORS support for details.