Create Grafana dashboards

Overview

Grafana is an open source analytics and monitoring tool which can be used to visualise data from Gateway Hub and create alerts. If you have existing Grafana installs, you can seamlessly integrate data from Gateway Hub into your current dashboards.

Prerequisites

You should already have Grafana installed and configured. For more information consult the Grafana getting started documentation.

You should be familiar with the use of Grafana from the web interface. To learn more about using Grafana see the Grafana getting started guide.

Gateway Hub must have Transport Layer Security (TLS) enabled. For more information about configuring TLS, see Configure transport layer security.

Install the ITRS data source for Grafana

Grafana plug-ins allow you to add new data sources from external applications. To install the ITRS Geneos Gateway Hub Datasource:

  1. Download the grafana-geneos-datasource.<version>.tgz from ITRS Downloads
  2. Navigate to the Grafana plugins directory. The default location is /var/lib/grafana/plugins.
  3. Create a new subdirectory here, for example /itrs-geneos-gateway-hub-datasource.
  4. Extract the plugin file into the subdirectory.

You can also use the grafana-cli tool to install plugins.

For more information on installing Grafana plugins see grafana.com.

Note: The ITRS Geneos Gateway Hub Datasource is only compatible with the Gateway Hub of the same version.

Connecting to Gateway Hub

To fetch data from Gateway Hub, the Grafana host must be able to communicate with your Gateway Hub installation.

To allow this, you must:

Display data from Gateway Hub

Add Gateway Hub as a data source

To add a new data source:

  1. Navigate to your Home Dashboard.
  2. Select Configuration > Data Sources from the sidebar.
  3. Click Add data source.
  4. Select the ITRSGeneosGateway HubDatasource.
  5. Specify the following options:
    1. Name — name for the datasource in Grafana.
    2. URLREST API endpoint of the Gateway Hub in the form https://<hostname>:<port>/<API version>/.
    3. API Version — API version used when communicating with Gateway Hub.
    4. Key — unique key used to identify an application to Gateway Hub.
    5. Secret — secret used to authenticate the identity of an application.
    6. Skip TLS Verify — checked.

    All other options can be left at their default value.

  6. Click Save & Test. You should see a notification to indicate that the data source is correctly configured.

Visualise data from Gateway Hub

To visualise data from Gateway Hub you can create a new panel in a new or existing Grafana dashboard.

To display data from Gateway Hub:

  1. Open a dashboard or create a new dashboard.
  2. Click the Add Panel button.
  3. Click Add Query.
  4. Set the Query to the Gateway HubDatasource using the name you specified above.
  5. Configure the Query using the following options:
    1. Filter— a filter specified in the entity filter syntax, see Entity filter syntax.
    2. Endpoint type — API endpoint used to perform query. Choose from Metric Query, Events, or Entities.

  6. If the Endpoint type is Metric Query, specify:
    1. Group By — attributes included in the Query.
    2. Metrics — metric and aggregations used in the Query.
  7. If the Endpoint type is Events, specify:
    1. Events — event types used in the Query.
    2. Duration — duration bucket size used in the Query.
  8. If the Endpoint type is Entities, specify:
    1. Group By — attributes included in the Query.
  9. Click Visualisation.
  10. Configure the graphical representation of your data.
  11. Click General.
  12. Configure the Panel information.
  13. Click Save Dashboard.

Note: Grafana will validate your dashboard's configuration before saving and alert you to any errors.

Organise data using variables

You can define variables in Grafana that allow you to dynamically change the data displayed on your dashboards. You can use the ITRS Geneos Gateway Hub Datasource to populate variables.

For more information about variables, see the Grafana website.

To create a new variable using data from Gateway Hub:

  1. Open the Dashboard settings menu.
  2. Click Variables.
  3. Click New.
  4. Configure the variable using the following options:
    1. Name — name of the variable.
    2. Type — type of data source used for the variable. Choose Query.
    3. Data source — data source used to provide the variable data. Choose Gateway HubDatasource.
    4. Query — a query specified in the entity filter syntax, see Entity filter syntax.

  5. Click Add.

Once you have created a variable, you can use it to adjust the information displayed in a dashboard by selecting from the possible values of a variable using a drop-down list.

You can use variables defined in Grafana when writing queries to populate visualisations. A panel will show the results of the query corresponding to the values of the variables you have set from the drop-down lists.

In the example below, there are two variables defined: Department and Entity. Variables are nested so that setting that value of Department to Engineering will restrict the contents of the Entity drop-down to show only entities that belong to the Engineering department.

Annotate data

You can automatically add annotations to your visualisations in Grafana based on data from Gateway Hub. Annotations settings can be configured separately for each dashboard.

To configure annotations:

  1. Open the Dashboard settings menu.
  2. Click Annotations.
  3. Click New.
  4. Configure the annotation query using the following options:
    1. Name — a name use to refer to this annotation query.
    2. Data source — data source used to provide the annotation data. Choose Gateway HubDatasource.
    3. Enabled — checked.
    4. Hidden — unchecked.
    5. Query — a query specified in the entity filter syntax, see Entity filter syntax.

    Note: When specifying a query you will need to escape special characters.

  5. Click Add.

Grafana overlays your existing visualisations with indicators for the annotations you have configured. These can be colour coded from the configuration menu. Hovering the cursor over an indicator displays the contents of the annotation query in a pop-up.

Note: Grafana annotations are applied at the dashboard level, active annotations are displayed on all panels in a dashboard.

In the example below, an annotation has been configured to show Geneos events. This is often useful since it allows you to correlate changes in severity with changes in the values of metrics.