How to include dashboards in your data source plugin

Grafana Plugin Development Share & showcase
1

I recently published a data source for YNAB to give YNABers a better insight into their personal finances. Since the vast majority of people using YNAB don’t have experience with Grafana (or system monitoring for that matter), plugin needs to let them get started with minimal effort.

Instead of asking users to create a dashboard from scratch, I wanted to let new users get started quickly with a ready-made experience with some common queries and visualizations. In this guide, I’ll show you how to include pre-configured dashboards to your data source.

Step 1: Create a dashboard

First, create the dashboard you want to include. You can use an already configured data source while you build the dashboard. You’ll replace it with a placeholder when you export it later on.

Step 2: Export the dashboard

In this step, you’ll export the dashboard definition to a JSON file so that you can check it in along your data source plugin.

  1. Click the Share icon in at the top-left of the dashboard.
  2. Click Export.
  3. Enable Export for sharing externally, and then click Save to file.

When you export a dashboard for sharing externally, Grafana adds a placeholder rather than a direct reference to the data source. That way, when the user imports the dashboard, it’ll use their data source instance instead.

Step 3: Add the dashboard to your plugin

This is where the magic happens.

  1. Create a folder called dashboards in the src directory of your plugin.

  2. Copy the exported dashboard definition file to the dashboards folder.

  3. In plugin.json, add a new dashboard resource to the includes property, where the path is the relative path to the dashboard definition within the src folder.

    {
  // ...

  "includes": [
    {
      "type": "dashboard",
      "path": "dashboards/overview.json"
    }
  ]
}

  4. Rebuild your plugin, and restart Grafana to reload the plugin configuration.

Step 4: Import the dashboard

To test it out and import the dashboard yourself:

  1. Create or edit an existing instance of your data source.
  2. Click Dashboards to list all included dashboards.
  3. Click Import next to the dashboard you want to import.

Import dashboard
Import dashboard1854×394 12 KB

Include dashboards for a better onboarding experience

By including ready-made dashboards with curated queries and visualizations, you can create a better onboarding experience for your users. Do users set up the same variables or panels for every new dashboard? Include a dashboard to serve as a template that they can use to scaffold new dashboard. Your users will thank you!

Make sure to check out the Share & showcase category for more plugin development guides like this one!

4 Likes
2

Can this also be done with panels?

1 Like
3

Unfortunately not, only data sources and app plugins at this point. You could of course ship dashboards with your panel plugin, but Grafana doesn’t have any UI to import the dashboard unfortunately.

1 Like