Fully reproducible Grafana dashboards with Grafonnet

Fully reproducible Grafana dashboards with Grafonnet #

Grafana is an open-source analytics and visualization platform that allows users to create customizable dashboards and panels to visualize and monitor data from various sources. One way to create Grafana dashboards is through Jsonnet, a programming language that provides a toolset for managing complex configuration files written in JSON.

Grafonnet is a tool that allows developers to write and manage Grafana dashboards using a more concise and structured syntax than the traditional JSON or YAML formats. This approach can help to reduce errors and simplify the process of creating and maintaining dashboards.

Reproducibility is another key benefit of using Grafonnet to create Grafana dashboards. When you write a dashboard in Grafonnet, you are essentially creating a programmatic representation of the dashboard. This means that you have the following benefints:

• can version-control the code,
• track changes over time,
• and easily reproduce the same dashboard in different environments.

Below, you will find a step-by-step tutorial about how to create a Grafana dashboard with Jsonnet.

Step 1: Install and Configure Grafana #

Before we can start creating a dashboard, you need to install Grafana. Grafana can be installed on Linux, macOS, and Windows systems. Once installed, you can configure the Grafana server to use the desired data source. More information about possible ways to install it you can find on the official site – Install Grafana | Grafana documentation

Step 2: Install Jsonnet #

Jsonnet can be installed on Linux, macOS, and Windows systems using a package manager such as Homebrew or by downloading the binary from the official website. Once installed, you can start creating Jsonnet files.

There are two feature-compatible implementations of the Jsonnet interpreter. The first one we built was the C++ interpreter, and it is still the most mature / widely used. The new Go implementation has the benefits of simpler code (due to leveraging goroutines and the GO garbage collector). Below are links to these implementation:

• C++ implementation
• Go implementation

You can install any of them by following the links and reading the installation section.

Step 3: Installing Jsonnet Bundler and adding the external dependency. #

It is possible to create grafana dashboards from scratch but the best way is to use the Grafonnet library. And for this we need a package manager – Jsonnet Bundler.

Jsonnet Bundler is a tool that simplifies the management of dependencies in Jsonnet projects. There are features that are very useful when you use the package manager such as simplified dependency management, automatic installation and updating of dependencies and version pinning.

After installing Jsonnet Bundler you need to create an empty folder and run the following commands:

jb init # it creates an empty jsonnetfile.json file

Now add the Grafonnet dependency and after that run jb install. Jsonnet Bundler will install everything that we need for our dashboard.

Your final jsonnetfile.json should look like:

{
 "version": 1,
 "dependencies": [
   {
     "version": "master",
     "source": {
       "git": {
         "remote": "https://github.com/grafana/grafonnet-lib",
         "subdir": "grafonnet"
       }
     }
   }
 ],
 "legacyImports": true
}

Step 4: Creation of the dashboard. #

Now we have everything to start the dashboard creation.

In this step, we will create a Jsonnet file that defines the dashboard layout and configuration. Jsonnet provides a way to define objects and functions that can be used to generate JSON objects that Grafana can understand.

Here is an example Jsonnet file that creates a simple dashboard:

local grafana = import 'grafonnet/grafana.libsonnet';
local dashboard = grafana.dashboard.new(
  'My Dashboard'
);

local graphPanel = grafana.graphPanel.new(
  'Graph',
  {
    targets: [
      {
        expr: 'my_metric',
        legendFormat: '{{instance}}',
      },
    ],
    title: 'My Panel',
  }
);

local singleStatPanel = grafana.singlestat.new(
  'Singlestat',
  {
    targets: [
      {
        expr: 'my_metric',
      },
    ],
    title: 'My Singlestat Panel',
  }
);

dashboard
.addPanels([graphPanel, singleStatPanel])

This Jsonnet file defines a dashboard with two panels: a graph panel and a singlestat panel. The graph panel displays data from the my_metric metric, with the legend format set to show the instance label. The singlestat panel also displays data from the my_metric metric.

Step 5: Generate JSON Output #

Once you have created your Jsonnet file, you can generate the corresponding JSON output that Grafana can understand. This can be done using the jsonnet command-line tool.

This command generates a my_dashboard.json file that contains the JSON representation of your dashboard.

jsonnet --jpath vendor my_dashboard.jsonnet > my_dashboard.json

Step 6: Import the Dashboard #

Finally, you can import your dashboard into Grafana by uploading the JSON file. To do this, log in to the Grafana web interface, go to the Dashboards page, and click the Import button. Select the my_dashboard.json file you generated in the previous step and click Import.

That’s it. The process is very simple.

Step 7: Dashboard management and maintenance. #

Grafana dashboards allow you to define complex layouts and configurations with ease. You can use different strategies on how to organize your dashboards and layouts for panels inside them. A good practice is to use one dashboard per file. It simplifies generation and deployment scripts.

Also, by separating each dashboard into its own JSON file, it’s easier to keep track of each dashboard’s configuration and make changes to individual dashboards without affecting others. By creating a single Jsonnet file, you can define multiple panels and graphs that can be easily modified and updated as your monitoring needs change.

Conclusion #

In the examples we used Grafonnet. It provides a library of pre-built objects and functions that can be used to create Grafana dashboards. This can save you time and effort by allowing you to reuse common configuration patterns and templates. Overall, Grafonnet can be a good tool for authoring Grafana dashboards, offering benefits such as improved code readability, reusability, flexibility, and integration with GitOps workflows.

Also, when the number of projects grows inside the team, you may create a repository with useful panels, graphs that you may share between different projects. In such cases Jsonnet Bundler is a good choice. It significantly simplifies the management of dependencies in Jsonnet projects.