Grafana dashboards

Overview Copied

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 Copied

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.

To check which Grafana versions are compatible with the ITRS Geneos Gateway Hub Datasource, see the compatibility matrix.

Install the ITRS data source for Grafana Copied

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

5. If you are using Grafana version 8.0 or later, you need to manually enable the loading of the grafana-geneos-datasource plugin. Edit grafana.ini and add the following line:

   allow_loading_unsigned_plugins = itrs-geneos-datasource
   

   Note

   To check which Grafana versions work with the plugin, see the compatibility matrix.

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

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

Connecting to Gateway Hub Copied

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

To allow this, you must:

• Ensure certificates provided by Gateway Hub are accepted by Grafana. This is particularly important when using certificates signed using an internal certificate authority. For more information, see Add Gateway Hub certificate authority to Grafana in Troubleshooting User Guide.
• Generate application keys using the Web Console. You should provide these when connecting Grafana to a Gateway Hub. For more information, see Application Keys.
• If you are using LDAP based SSO, you must ensure the check origin function is disabled. For more information about LDAP based SSO, see LDAP configuration.

Display data from Gateway Hub Copied

Add Gateway Hub as a data source Copied

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:
   • Name — name for the datasource in Grafana.
   • URL — REST API endpoint of the Gateway Hub in the form https://<hostname>:<port>/<API version>/.
   • API Version — API version used when communicating with Gateway Hub.
   • Key — unique key used to identify an application to Gateway Hub.
   • Secret — secret used to authenticate the identity of an application.
   • 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 Copied

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:
   • Filter— a filter specified in the entity filter syntax, see Entity filter syntax.
   • Endpoint type — API endpoint used to perform query. Choose from Metric Query, Events, or Entities.
6. If the Endpoint type is Metric Query, specify:
   • Group By — attributes included in the Query.
   • Metrics — metric and aggregations used in the Query.
   • Include — regex filter applied to the output of the Query.
7. If the Endpoint type is Events, specify:
   • Events — event types used in the Query.
   • Duration — duration bucket size used in the Query.
   • Include — regex filter applied to the output of the Query.
8. If the Endpoint type is Entities, specify:
   • Group By — attributes included in the Query.
   • Include — regex filter applied to the output of 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 Copied

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.

Regex variable Copied

To create a new variable that allows you to apply a regex filter to data from Gateway Hub:

1. Open the Dashboard settings menu.
2. Click Variables.
3. Click New.
4. Configure the variable using the following options:
   • Name — name of the variable.
   • Type — type of data source used for the variable. Choose Text box.
   • Label — label of the text box displayed in the panel. Specify Include.
5. Click Add or Update.

Once you have created a regex variable, you can use it to adjust the information displayed in a dashboard by specifying a regex filter.

Query variable Copied

To create a new variable using query data from Gateway Hub:

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

Once you have created a query 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 Copied

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:
   • Name — a name use to refer to this annotation query.
   • Data source — data source used to provide the annotation data. Choose Gateway HubDatasource.
   • Enabled — checked.
   • Hidden — unchecked.
   • 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.