Basic Walk-Through

Overview

This guide demonstrates how to create a simple dashboard with HELM by doing the following:

The tutorial 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 mode nodes being monitored by OpenNMS

If you are already using the OpenNMS Data Source plugin with Grafana, see Migrating from the OpenNMS Data Source plugin to migrate to using HELM to interface with OpenNMS.

Application Setup

In this section, you will enable the HELM application in Grafana and create Custom Actions.

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

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

    Plugins

  3. Search for the OpenNMS Helm application and click on it.

    If the OpenNMS Helm application is not listed on the Plugins tab, try restarting the Grafana server. If the issue persists, make sure the application is installed correctly.

  4. Enable the application by clicking the Enable button.

    If you see a Disable button, then the application is already enabled and you can 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 can help users obtain a deeper diagnosis of 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 the available properties.

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

If a variable can’t be matched against the row, the action will not appear in the context menu.

Variables will be URL-encoded when they are 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 Confg tab, click +Add Custom Action:

    Custom Action

  5. Specify a label and enter a URL.

    1. In most cases the URL will be your OpenNMS instance, e.g., 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 creating 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, 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 on Add data source.

  4. In the search field enter OpenNMS Entities.

  5. Beside the OpenNMS Entities datasource, click Select:

    select data

    The settings screen appears:

    data config

  6. In the URL field, enter the URL to your OpenNMS instance, i.e., http://localhost:8980/opennms.

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

  7. Click the toggle switch next to Basic Auth.

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

  9. Click Save & Test.

    Data source is working

If the datasource is configured correctly a message indicating that the Data source is working appears. If the message indicates a failure, review the information you entered and click Save & Test to test the datasource again.

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 chooosing Create>Dashboard.

    New Dashboard

  2. To add an alarm table, in the top right, click the Add panel icon:

    Add Panel

  3. Click Add Query. A screen similar to the following appears. The lower half of the screen is where you configure your panel:

    Configure Panel

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

  5. Select Alarms in the SELECT drop-down.

    1. Configure addtional information and add filters as desired.

  6. In the left menu, click the visualization icon.

  7. In the Visualization drop-down, select Graph.

  8. Click Alarm Table. The graph appears in the top of the panel.

    1. You can further customize the graph by specifying information in the bottom half of the panel.

  9. In the left menu, click the General icon to change the name of the panel and specify additional information.

  10. In the top-right menu, click the Save dashboard icon.

That’s it! Now, you have your first dashboard. Try changing the time range at the top right of the screen, or try performing actions against the alarms by right clicking on any of the alarm rows. You can also display other data by creating more panels, or import an existing dashboard to learn more about how to design your own.

Creating a Panel

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

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

  2. Click Add Query.

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

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

  5. In the left menu, click the visualization icon.

  6. In the Visualization drop-down, select Graph.

  7. Select a graph type. The graph appears in the top of the panel.

    1. You can further customize the graph by specifying information in the bottom half of the panel.

  8. In the left menu, click the General icon to change the name of the panel and specify additional information.

  9. In the top-right menu, click the Save dashboard icon.

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

  2. Click Add Query.

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

  4. From SELECT, choose Alarms.

  5. 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-downs.

    Alarm table
    Sample alarm table configuration

  6. In the left menu, click the visualization icon.

  7. In the Visualization drop-down, select Graph.

  8. Select an 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 specifying information in the bottom half of the screen.

  9. In the left menu, click the General icon to change the name of the panel and specify additional information.

  10. In the top-right menu, click the Save dashboard icon.