Introduction

Grafana supports a wide range of data sources, including Prometheus, MySQL, and even Datadog. There’s a good chance you can already visualize metrics from the systems you have set up. In some cases, though, you already have an in-house metrics solution that you’d like to add to your Grafana dashboards. This tutorial teaches you to build a support for your data source.

For more information about backend plugins, refer to the documentation on .

Set up your environment

Before you can get started building plugins, you need to set up your environment for plugin development.

To discover plugins, Grafana scans a plugin directory, the location of which depends on your operating system.

1. Create a directory called grafana-plugins in your preferred workspace.

2. Find the plugins property in the Grafana configuration file and set the plugins property to the path of your grafana-plugins directory. Refer to the

   [paths]
   plugins = "/path/to/grafana-plugins"
   

3. Restart Grafana if it’s already running, to load the new configuration.

If you don’t want to install Grafana on your local machine, you can use Docker.

To set up Grafana for plugin development using Docker, run the following command:

docker run -d -p 3000:3000 -v "$(pwd)"/grafana-plugins:/var/lib/grafana/plugins --name=grafana grafana/grafana:7.0.0

Since Grafana only loads plugins on start-up, you need to restart the container whenever you add or remove a plugin.

docker restart grafana

Create a new plugin

To build a backend for your data source plugin, Grafana requires a binary that it can execute when it loads the plugin during start-up. In this guide, we will build a binary using the .

npx @grafana/toolkit plugin:create my-plugin

cd my-plugin

yarn install
yarn build

Run the following to update

go get -u github.com/grafana/grafana-plugin-sdk-go
go mod tidy

mage -v

By default, Grafana requires backend plugins to be signed. To load unsigned backend plugins, you need to configure Grafana to . For more information, refer to .

The

We begin by opening the file /pkg/plugin/plugin.go. In this file you will see the SampleDatasource struct which implements the backend.QueryDataHandler interface. The QueryData method on this struct is where the data fetching happens for a data source plugin.

Each request contains multiple queries to reduce traffic between Grafana and plugins. So you need to loop over the slice of queries, process each query, and then return the results of all queries.

In the tutorial we have extracted a method named query to take care of each query model. Since each plugin has their own unique query model, Grafana sends it to the backend plugin as JSON. Therefore the plugin needs to Unmarshal the query model into something easier to work with.

As you can see the sample only returns static numbers. Try to extend the plugin to return other types of data.

You can read more about how to .

Open /pkg/plugin/plugin.go. In this file you’ll see that the SampleDatasource struct also implements the backend.CheckHealthHandler interface. Navigate to the CheckHealth method to see how the health check for this sample plugin is implemented.

Enable Grafana Alerting

1. Open src/plugin.json.
2. Add the top level backend property with a value of true to specify that your plugin supports Grafana Alerting, e.g.

   {
     ...
     "backend": true,
     "executable": "gpx_simple_datasource_backend",
     "alerting": true,
     "info": {
     ...
   }
   

3. Rebuild frontend parts of the plugin to dist directory:

yarn build

1. Restart your Grafana instance.
2. Open Grafana in your web browser.
3. Open the dashboard you created earlier in the Create a new plugin step.
4. Edit the existing panel.
5. Click on the Alert tab.
6. Click on Create Alert button.
7. Edit condition and specify IS ABOVE 10. Change Evaluate every to 10s and clear the For field to make the alert rule evaluate quickly.
8. Save the dashboard.
9. After some time the alert rule evaluates and transitions into Alerting state.

Summary