Creating a Custom Plugin in Grafana using React

With Grafana you can create dashboards for monitoring metrics, like status and health of IoT devices. Several types of visualizations are already available when developing the dashboard. If the choices aren’t sufficient, Grafana supports the ability to add custom plugins. In this post I will create a custom plugin in React, which can be used in Grafana, in order to show data in a nested tree view.

Grafana setup

The basic setup for Grafana is described on their website. I chose to install Grafana locally with a Windows installation package as this is a quick way to get started. Run the grafana-server.exe and it will open a Grafana environment on localhost:3000.

Grafana supports a wide range of data sources. PostgreSQL is one of them. I used this as it has a nifty tool, pgAdmin, to quickly create a database and insert data. I created two tables: Branches (id, name) and Leaves (id, name, branch_name).

Creating the Dashboard

Before I start on my custom plugin, I want to have everything ready for it in Grafana. On the Home Dashboard Grafana gives you some first-time user options:

• Create your first data source, it will take you to the data source options
• Select PostgreSQL, it will create a new data source page
• Fill in all connection information from your database connection (host will show a placeholder for the localhost-address, make sure to actually type it in)
• If clicking Save & Test has resulted in OK, then you have just created a working data source.

So data is coming into Grafana, but I want to see it in a dashboard.

• Create your first dashboard on the Home Dashboard, this will create a new dashboard with a panel
• Add Query in the panel
• Select the PostgreSQL data source and create the query. Click the pencil to write plain SQL and be sure to select “Format as”: Table

• Click Visualization and select Table (notice that there is no option for a tree view). The PostgreSQL data is displayed in the table.
• The data is now on the dashboard, but I want to see my branches and leaves in an actual Tree structure. Grafana doesn’t offer this type of visualization, so I’m making a custom plugin.

Custom Plugin setup

Grafana is written in AngularJS, but is migrating to React. This means a custom plugin can be created in AngularJS or React. Grafana provides examples for both. As AngularJS is a little outdated, I chose to use React. For this setup you will need a recent installation of Node.js and yarn.

• Get the ”Hello World” panel using React from the Grafana GitHub
• Add it to the Grafana/../grafana-<version>/data/plugins/
• Run yarn to install the plugin, then yarn run dev –watch to run the plugin and rerun grafana-server.exe
• The custom plugin appears on the Grafana Home Dashboard under Installed Panels.
• Go to the Tree dashboard and select the plugin as visualization in the panel (click the panel title to go to the edit page).

Creating the Custom Plugin

Up to this point the setup has been simple and straightforward. This doesn’t stop when developing the actual plugin. Open the ”Hello World” panel using React” in your favourite IDE. All code for the plugin can be written in the module.tsx, which is located in the src-file. I don’t want to create a tree component from scratch, so I’m bringing in the Material-UI library, which has a treeview component.

1. yarn add @material-ui/lab @material-ui/icons
2. Import both into module.tsx

Now I can start creating the actual Tree view! Before you start, take a look at the Grafana styleguide.

Creating the Tree view

The first part of showing the data in a tree view, is getting the data into the class. The data from the data source is available through a constructor in the custom plugin. The properties passed to the constructor contain a data object with a series-array. Remember when we formatted the data source query as a table? You can find the data in the series-array as rows.

I’ve kept it simple in my database, but that means I’ll have to do some frontend transformation of data. When dealing with multiple layers (more than two) or more (complex) data, I would recommend a database view to structure the data coming in from the data source, so it’s easier to handle in the React class.

The Material-UI tree view consists of a TreeView element with nested TreeItems. The TreeItems can be nested as many times as needed.

The plugin should automatically update in the browser (if the plugin and grafana-server are running, otherwise rerun). The result is a tree view with branches and leaves.

Creating your own custom plugin for Grafana is pretty simple with the examples Grafana offers you, as long as you keep it simple too. Grafana has some more advanced dashboard features like a panel editor and dashboard variables, I discuss this in this post.