Create a Dashboard

This section demonstrates how to create a simple dashboard using the OpenNMS Plugin for Grafana.

You must have the following set up to create a dashboard:

  • An instance of Grafana with the plugin installed.

  • An instance of OpenNMS that is reachable from your Grafana instance.

  • One or more nodes being monitored by OpenNMS.

If you already use the OpenNMS Data Source plugin with Grafana, see Migrate from OpenNMS Data Source Plugin for information on how to switch to the OpenNMS Plugin for Grafana.

Set up the plugin

First, you must enable the plugin in Grafana and create custom actions to help with alarm diagnosis:

  1. Navigate to the home page of your Grafana instance.

  2. In the left navigation menu, select Configuration  Plugins:

    Grafana menu displaying navigation options. The Plugins option is highlighted.

  3. Select OpenNMS Plugin for Grafana.

    • If the plugin is not listed, try restarting your Grafana server.

    • If the issue persists, make sure the plugin’s files are in the Grafana plugins directory (default: var/lib/grafana/plugins).

  4. Click Config  Enable.

    The Disable option indicates that the plugin is already enabled. You can also choose Update to download the latest version of the plugin.

Create custom actions

A custom action is a user-defined operation (for example, a link to a node detail page or a knowledge base article) that might help users diagnose an alarm. Once created, custom actions are displayed when you right-click an alarm in an alarms table:

Alarms table with three alarms. The context menu is displayed, listing three custom actions.

You can create a custom action on the plugin’s Config page. Each custom action includes a label and a URL; the URL may contain $variables that reference OpenNMS alarm properties. Note that variables are URL-encoded when injected into a URL. See the OpenNMS.js documentation for a list of available properties.

As a special case, you can access an alarm’s event parameters either by index ($parameters[1]) or by name ($parameters[reason]).

If a variable cannot be matched against the appropriate row, the action does not appear in the context menu.

Two examples of custom action URLs with embedded variables.
Figure 1. Sample custom action URLs with parameters

To create a custom action, follow these steps:

  1. Navigate to the home page of your Grafana instance.

  2. In the left navigation menu, select Configuration  Plugins.

  3. Select OpenNMS Plugin for Grafana.

  4. On the Config tab, click Add Custom Action.

  5. Specify a label and enter a URL.

    • In most cases, the URL should point to your OpenNMS instance (for example, http://localhost:8980/opennms/, appended with a $variable that references an alarm property).

  6. Click Update.

The action should be displayed in the context menu when you right-click an entry in an alarms table.

Create a datasource

The type of data that you can display in a dashboard depends on the datasource that you select.

Before you create a dashboard, you must set up the datasource (performance, flow, or entity). For this walk-through, we will configure an entity datasource. Note that you can follow the same process to configure a flow or performance datasource.

You need to configure only the URL, Basic Auth, and Basic Auth Details (username and password) fields. See the official Grafana documentation for information on configuring other fields.

Follow these steps to set up a datasource:

  1. Navigate to the home page of your Grafana instance.

  2. In the left navigation menu, select Configuration  Data Sources:

    Grafana menu displaying navigation options. The Data Sources option is highlighted.

  3. Select Add Data Source.

  4. In the Search box, type OpenNMS Entities.

  5. Select the OpenNMS Entities datasource. The settings dialog is displayed:

    OpenNMS Entities datasource settings dialog displaying sample settings.

  6. Type the URL that directs to your OpenNMS instance (for example, http://localhost:8980/opennms). In most cases, this URL should end with /opennms.

  7. Under Auth, toggle Basic Auth on.

  8. Enter the credentials for an OpenNMS user in the User and Password boxes.

  9. Click Save & Test. A success message should be displayed.

    • If the message indicates a failure, review the information that you entered and click Save & Test to retest the settings.

Create a dashboard

For this walk-through, we will create a dashboard with an alarms table. For information on displaying other data in a dashboard, see Create a panel.

  1. In the left navigation menu, click the plus symbol (+), and choose Dashboard.

  2. Click Add Panel  Add an Empty Panel.

  3. Configure its settings in the lower half of the page:

    An example dashboard displaying its configuration settings. The settings are highlighted with a green box.

  4. Select the datasource that you created in Create a datasource from the Query list.

  5. In the Select list, choose Alarms.

    • (Optional) Configure additional information and add filters.

    • (Optional) Click + Query to add a query to the dashboard.

  6. Under Panel Options, type the dashboard’s name in the Title box.

  7. Under Visualization, select Alarm Table.

    • (Optional) Customize the graph by specifying settings under Panel Options.

  8. Click the Save symbol at the top-right of the dashboard.

  9. Type a name for the dashboard, and click Save.

Your dashboard should now be displayed. To test it, you can change the time range at the top-right of the page, or right-click an alarm to perform custom actions against it.

You can create more panels to display other data, or import an existing dashboard for design examples.

Create a panel

A panel is a component of a dashboard; it displays your specified fault and performance management data.

Before you add a panel to your dashboard, determine the type of data that you want to visualize (performance, metrics, alarms or nodes, and so on), and make sure that you have set up a datasource. Default graph types in Grafana work only with their appropriate datasource (for example, an alarm table visualization will not display data if a flow datasource is specified).

The plugin includes the following custom panels:

  • Alarm histogram

  • Alarm table

  • Filter panel

  • Flow histogram

For more information about custom panel types, see Default custom panels.

Follow the steps below to create a new panel in your existing dashboard:

  1. Navigate to your dashboard and click the Add Panel symbol.

  2. Click Add New Panel.

  3. Select a datasource from the Query list.

    • (Optional) Configure additional settings. Options are dependent on the type of datasource selected.

  4. Navigate to the Panel tab.

  5. Under Visualization, click the Visualization symbol.

  6. Click Graph. The graph is displayed at the top of the panel.

    • (Optional) Configure settings in the bottom half of the panel to customize the graph.

  7. Specify the panel’s Name.

  8. Click Save at the top-right of the panel.

Create an alarm panel

An alarm panel displays alarms from an entities datasource. Normally, visualization of the information in an entities datasource is done with tables.

Follow these steps to create a new alarm panel in your existing dashboard:

  1. Navigate to your dashboard and click the Add Panel symbol.

  2. Click Add New Panel.

  3. Select an entity datasource from the Query list.

  4. Choose Alarms from the Select list.

  5. Set filters and conditions to specify the nodes and alarms to visualize.

    • Note that you can use nested "and/or" logic for the filters and conditions.

    • You can order alarms by ascending (oldest alarms first) or descending (most recent alarms first).

    • You can limit the number of alarms displayed.

    • You can toggle Featured Attributes on to display select attributes. Toggle it off to display all attributes in the drop-down lists.

      Example settings for a new alarm table panel.

  6. Navigate to the Panel tab.

  7. Under Visualization, click the Visualization symbol.

  8. Select Alarm Table. The graph is displayed at the top of the panel.

    You can choose a table or a histogram graph for alarms. For nodes, you can configure only a table graph.

    • (Optional) Configure the settings in the bottom half of the panel to customize the graph.

  9. Update the panel’s Name.

  10. Click Save at the top-right of the panel.