Creating a Custom Grafana visualisation

Before you begin, Grafana may be deployed either with or without authentication enabled. If authentication is enabled, ask the administrator to create an access account for you, or log in using your existing credentials.

After logging in, the Home page is displayed. The most important sections of Grafana for this tutorial are:

• Dashboards

• Alerting

• Data sources

For the initial configuration of Grafana, you can use import scripts provided via configTool (see here). The following chapters describe manual configuration and further customisation.

Managing Data Sources

Data sources can be added in Connections/Data sources. Click the blue Add new data source button in top right corner to open the configuration form and select the required data source type. For RTC Toolkit, the primary data source should be InfluxDB. To add an InfluxDB data source:

1. Assign a suitable name to the data source.

2. Select the query language. It is recommended to use SQL (for InfluxDB this is the Apache Arrow DataFusion implementation, see the documentation), because the pre-configured visualisations for RTC Toolkit use this language. However, if you need to use a different query language for your data source, this is possible.

Note

The choice of query language depends on the version of InfluxDB you are using. SQL support was introduced in InfluxDB version 3.0. Before this, in version 2 was popular to use the Flux language, but we do not recommend it because it is no longer available in version 3. The only language supported in all versions is InfluxQL, but it has limited features and functions compared to other languages. However, if you wish to use multiple languages simultaneously (InfluxQL and SQL), this is also possible. You will then need to configure multiple data sources pointing to the same InfluxDB instance using different query languages.

3. Fill in the InfluxDB Details section:

   • Database name

   • Authentication token (only if you secured your InfluxDB with operator access token during its installation)

4. Since InfluxDB is located on the same network, enable Insecure connection so that HTTP is used instead of HTTPS. Without this option enabled, communication with InfluxDB will fail.

5. Click “Save and test” button to verify your data source.

Dashboards

New visualisations are created in the form of dashboards. This section is available in the main Grafana navigation under Dashboards. A dashboard is a collection of panels. Each panel can use a different data source and display different data. A single dashboard should contain data that is meaningful to analyze together.

When creating dashboards, there are two options:

• Create a new dashboard from scratch

• Copy an existing dashboard and modify it

Create a New Dashboard from a Template

To create a new dashboard from an existing one:

1. Locate and open the existing dashboard. If you are creating a dashboard for your own RTC component, you can use the “Template” dashboard which is provided by RTC toolkit after initial import.

2. Switch to edit mode by clicking Edit (in the top toolbar below the search field).

3. Click Save and select Save as copy.

4. In the sidebar, enter the new dashboard name and select its folder.

5. Click Save.

The new dashboard will be saved and opened immediately.

Dashboards can also be imported. Grafana provides a large online library of community-maintained dashboards. If you want to use one of these community dashboards, you will most likely need to modify the database query used in the panels of this Dashboard.

Create a New Dashboard from Scratch

To create a new dashboard from scratch:

1. Navigate the “Dashboards” page in the main navigation.

2. Use the New button in the top right corner and select New Dashboard from the drop-down menu.

3. Add panels using the blue Add visualization button or insert panels from the list of Library panels.

4. Once you have finished working on your dashboard, don’t forget to save it by clicking the blue “Save dashboard” button, otherwise you will lose all your changes.

Important

Project-specific dashboards should be archived in a Git repository. It is recommended to use the configTool export command for this purpose. It downloads the dashboards as a JSON files, which can be versioned in Git. If your running Grafana configuration is broken or lost, you can clean up the dashboards and re-import the saved one using the configTool import command.

Create library panel

Library panels are reusable Grafana panels that are stored centrally and can be shared across multiple dashboards. Their purpose is to keep common visualisations consistent and easy to maintain. When you update a library panel, the change is automatically reflected everywhere the panel is used.

A library panel can only be created from an existing regular panel. Keep in mind that the library panels are associated with a folder. If the folder does not exist yet, create it first. Otherwise, follow these steps to add a panel to the library:

1. Open the dashboard that contains the regular panel.

2. Change the dashboard to edit mode using the Edit button, if you are not already in it.

3. Move the mouse cursor over the panel you want to add to the panel library.

4. In the top-right corner of the panel, click the three-dot menu.

5. From the menu, hover over More, then click New library panel in the secondary menu.

6. A form for saving the panel will appear on the right side of the screen.

7. Enter a suitable name, select the folder where the panel should be stored, and click Create library panel.

Warning

From this moment on, your original regular panel becomes a library panel and can be reused with the same configuration in multiple dashboards. If you modify this panel, the change will be applied to all other dashboards where the panel is used. If you want to modify only a specific instance of the library panel without affecting the others, you can convert it back into a regular panel: Use the same menu as before (Three dots/More) and select Unlink library panel option.