Grafana

From OpenNMS
Jump to: navigation, 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 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

Getting Started

Prerequisites

  • An instance of OpenNMS Horizon v16.x or greater
    • If your persisting data to .rrd files (as opposed to .jrb files) you'll need to be using rrdtool >= 1.4.0
      • Centos 6 users can install it from repoforge[1]
  • A RPM based or Debian based distribution on which to install the Grafana server

Setup Grafana and the OpenNMS plugin

Follow the instructions on the "Installation" tab of [2]

Note that Grafana 3.0 or higher is required to use our plugin.

Configure the OpenNMS data source

Note that the following instructions are based on Grafana v3.0.0 and may differ when using another version.

From the main page, access the the Data Sources configuration page by clicking the Grafana icon (a.k.a side menubar toggle) in the top left and then selecting Data Sources.

From the Data Sources page, click the Add data source button and set the following:

  • Type: OpenNMS
  • URL: http://hostname:8980/opennms
  • Access: proxy
  • Basic Auth - Enable: Yes
  • Basic Auth - User: username
  • Basic Auth - Password: pa$$word

Modify the URL and username/password fields appropriately. The user in question must be assigned to either the 'user', 'admin' or 'rest' roles within OpenNMS in order to be able to access the required REST APIs.

Click Add when complete.

Create your first Graph

Once the OpenNMS data source has been configured, you can proceed to setting up your first graph.

Start by adding a row, and then a graph panel to one of the dashboard. Consult Grafana's Getting Started Guide if your having trouble here.

Click on the title of the newly created graph panel, click edit and select the Metrics tab.

From the Metrics tab, select the data source created in the previous step at the bottom right.

Now click on the Node label with the tree icon. This should open up a modal dialog with a list of nodes. If the list is empty, or an error occurs, there may an issue communicating with the OpenNMS instance. See #Troubleshooting for next steps if you get stuck here.

If your node doesn't appear in the list, you can try searching by name, foreign source, foreign id, sysName or IP address.

Once you have found the desired node, click on its label and then click Select.

Next, click on the Resource label with the leaf icon. Again, this will open a modal dialog with a list of resources for the select node. Select the appropriate resource.

Next, click on the Attribute' label with the tag icon and select the appropriate attribute.

At this point you should see some points on the graph, if you don't then try another node/resource/attribute combination for which you know there are measurements available.

Once you have some points on the graph, you can either return to the dashboard or add more queries, or modify the graph's style.

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

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.