Basic walk-through

This section demonstrates how to create a simple dashboard with HELM:

The walk-through assumes that you have:

  • an instance of Grafana with the HELM application installed

  • an instance of OpenNMS that is reachable from the Grafana instance above

  • one or more nodes being monitored by OpenNMS

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

Setup plugin

In this section, you will enable the HELM 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 menu, click the Configuration icon, and click Plugins:

    Plugins
  3. Search for the OpenNMS Helm plugin and click on it.

    If the OpenNMS Helm plugin is not listed, try restarting the Grafana server. If the issue persists, make sure the plugin is in the grafana plugins directory (default is var/lib/grafana/plugins).

  4. In the Config tab, click Enable.

    A Disable button indicates the plugin is already enabled. Skip to the next step (creating Custom actions). You may also choose Update for the latest version of HELM.

Custom actions

A custom action is a user-defined operation, such as a link to a node detail page or a Wiki knowledgebase article, that might help users better diagnosis an alarm. Once created, custom actions appear when you right-click an alarm in an alarms table:

Custom Actions

Created in the Helm Config tab, a custom action includes a label and URL. Custom action URLs may contain $variables that reference properties of an OpenNMS alarm. See OpenNMS.js documentation for a list of available properties.

Special case: you can access event parameters on the alarm either by index ($parameters[1]) or by name ($parameters[reason]).

If a variable cannot be matched against the row, the action will not appear in the context menu. Variables are URL-encoded when injected into the URL.

Custom Actions
Action URLs using parameters

To create a custom action, follow these steps:

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

  2. In the left menu, click on the Configuration icon and click Plugins:

  3. Select OpenNMS Helm.

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

  5. Specify a label and enter a URL.

    1. In most cases the URL will be your OpenNMS instance, for example, http://localhost:8980/opennms/, appended with the $variable that references a property of an OpenNMS alarm.

  6. Repeat for each custom action you want to create.

  7. Click Update.

Datasource setup

The type of data you can display in your dashboard depends on the datasource you select. Before you create a dashboard, you need to set up the datasource. OpenNMS datasources include performance, flow, and entity. For more information on OpenNMS datasources, see Datasources.

In this section, you will configure the Entity datasource. Follow the same process to configure a Flow or Performance datasource. The only fields you need to configure are the following: URL, Basic auth, and Basic Auth Details (user and password). Refer to Grafana’s documentation for information on configuring the other fields.

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

  2. In the left menu, click on the Configuration icon, and click Data Sources:

    Data Sources
  3. Click Add data source.

  4. In the search field enter OpenNMS Entities.

  5. Beside the OpenNMS Entities datasource, click Select.

    The settings screen appears:

settings screen
  1. In the URL field, enter the URL to your OpenNMS instance, for example http://localhost:8980/opennms.

    The URL to your OpenNMS instance should normally end with /opennms.

  2. In the Auth area, click the toggle next to Basic Auth.

  3. Enter the credentials for an OpenNMS user in the User and Password fields.

  4. Click Save & Test.

    A success message should appear. If the message indicates a failure, review the information you entered and click Save & Test to retest the datasource.

Dashboard Setup

This section describes how to create a dashboard with an alarm table. For information on displaying additional or different types of data, see creating a panel.

  1. Create a new dashboard by clicking the + sign in the left menu and choosing Create>Dashboard.

  2. Click Add new panel.

    A screen similar to the following appears. Configure the panel in the lower half of the screen:

    Configure Panel
  3. In the Query drop-down, select the datasource we previously created in Datasource Setup.

  4. Select Alarms in the SELECT drop-down.

    1. Configure additional information and add filters as desired (click +Query to add queries).

  5. In the Panel tab, under the Settings>Panel title add a name for the panel.

  6. Under Visualization, select Alarm Table. The graph appears in the top of the panel.

    1. You can further customize the graph by specifying information in the Panel tab.

  7. In the top-right menu, click Save.

  8. Enter a name for the dashboard and click Save.

That’s it! Now, you have your first dashboard.

Try changing the time range at the top right of the screen, or right click on an alarm row to perform actions against an alarm.

Create more panels to display other data, or import an existing dashboard to learn more about how to design your own.

Create a Panel

A panel is the part of your dashboard that displays the fault and performance management data you specify. Before you add a panel, determine the type of data you want to display (performance, metrics, alarms/nodes), and make sure that you have set up the associated datasource. Default graph types in Grafana work only with the appropriate data source (for example, an alarm table visualization will not display data if a flow datasource is specified.)

  1. In your dashboard, click the Add panel icon and Add new panel.

  2. In the Query drop-down, select the datasource.

  3. Configure additional information as appropriate. Options are dependent on the type of datasource selected.

  4. In the Visualization area of the panel tab, click the visualization icon.

  5. Click Graph or select another type of visualization (Stat, Gauge, Bar gauge).

    The graph appears in the top of the panel.

    1. Specify information in the bottom half of the panel to customize the graph.

  6. In Panel tab, change the name of the panel and specify additional information.

  7. In the top-right, click the Save.

Create an Alarm Panel

An alarm panel displays alarms from an entities datasource. Visualization of entity datasource information (currently nodes and alarms) is normally done in tables.

This procedure creates an alarm panel using an alarm table visualization.

  1. In your dashboard, click the Add panel icon icon and Add new panel.

  2. In the Query drop-down, select an entity datasource.

  3. From SELECT, choose Alarms.

  4. Create filters and conditions to specify the nodes/alarms to display:

    1. Note that you can use nested "and/or" logic.

    2. You can order by ascending (oldest alarms first) or descending (most recent alarms) and limit the number of alarms displayed.

    3. Toggle featured attributes on to display select attributes. Toggle it off to display all attributes in the drop-down lists.

    Alarm table
    Sample alarm table configuration
  5. In the Visualization area of the panel tab, click the visualization icon.

  6. Select and Alarm Table graph.

    1. With alarms, you can also choose Table or Alarm histogram; with nodes, choose Table

    2. The graph appears in the top of the panel.

    3. You can further customize the graph by (including alarm severity theme colors) in the bottom half of the screen and in other sections of the Panel tab.

  7. Change the name of the panel.

  8. In the top-right menu, click Save.