Basic Walk-Through

This section demonstrates how to create a simple dashboard in HELM. The process includes the following steps:

This walk-through assumes that you have the following:

  • An instance of Grafana with the HELM 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 the OpenNMS data source plugin for information on how to switch to HELM.

Set up 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 symbol, 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 that the plugin is already enabled. You may also choose Update to download the latest version of the HELM plugin.

Custom actions

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

Custom Actions

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

As a 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 point to your OpenNMS instance (for example, http://localhost:8980/opennms/, appended with the $variable that references an OpenNMS alarm property).

  6. 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 URL, Basic Auth, and Basic Auth Details (user and password) fields. Refer to Grafana’s documentation for information on configuring 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 boxes.

  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 alarms table. For information on displaying other data in a dashboard, see creating a panel.

  1. In the left menu, click the + symbol and choose Dashboard to create a new dashboard.

  2. Click Add Panel > Add an Empty Panel and configure its settings in the lower half of the screen:

    Configure Panel

  3. Select the datasource that you created in Datasource Setup from the Query list.

  4. Select Alarms from the Select list.

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

  5. Under Panel Options, type the panel’s name in the Title box.

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

    • You can further customize the graph by specifying information under Panel Options.

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

  8. Type 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 to perform actions against it.

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 that you specify.

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

HELM 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.

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

  5. In the Visualization area of the Panel tab, click the Visualization icon.

  6. 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.

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

  8. In the top-right, click Save.

Create an alarm panel

An alarm panel displays alarms from an entities datasource. Visualization of entity datasource information (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 and select Add New Panel.

  2. Select an entity datasource from the Query list.

  3. Choose Alarms from the Select list.

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

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

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

    3. You can limit the number of alarms displayed.

    4. 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 an Alarm Table graph. The graph appears in the top of the panel.

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

    2. You can further customize the graph (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.