Grafana as Code Part Ⅰ: Build Grafana’s Dashboard

3 min readMar 26, 2022

Overview

Grafana as Code is the best practice to manage Grafana’s dashbords.

This tutorial consists of three parts to introduce how to run Grafana as Code on your way:

Part Ⅰ: Building Grafana’s Dashboard.
Part ⅠⅠ: Integration testing Dashboards.
Part ⅠⅠⅠ: Practice Guid.

Let’s move on the part 1: Building Grafana’s Dashboard. Th part 1 is about how to build Grafana’s dashboard written in Jsonnet using Bazel.

Introduction of Tools

Jsonnet: a kind of data templating languag. Normally, Grafana’s dashboard is made up by a huge json file that hard to read and maintaince. Jsonnet can solve this problem.
Grafonnet: a jsonnet library for helping template Grafana’s dashboard.
Bazel: a kind of fast build tool support many languages include Jsonnet.
Git & GitHub: GitOps tool you know. Or any kind of your favorite version control tool.
VS Code: a popular editor.

Bazel will download Jsonnet and Grafonnet automantically. Therefore, you just need Bazel and Git on your laptop.

Repo’s Structure

Owner repo contains the following files:

% tree 
.
├── BUILD.bazel
├── WORKSPACE
├── dashboard.jsonnet
└── grafonnet-lib.BUILD.bazel

WORKSPACE: define what external tools or external repo the project need.
BUILD.bazel: describe how dashboard.json is generated.
dashboard.jsonnet(around 90 lines): a dashboard written by jsonnet.
grafonnet-lib.BUILD.bazel: Grafonnet library’ BUILD file.

Building Dashboard

Building dashboard at your terminal:

# at the root folder of repo
$ bazel build //.......many logs are printed
INFO: Build completed successfully, 1 total action

After build completed successfully, you can find out dashboard.json(350 lines) in bazel-bin/ folder:

% wc -l bazel-bin/dashboard.json   
     350 bazel-bin/dashboard.json

We don’t desire upload dashboard.json to Grafana server manually. Th part 3 of this series, we’ll introduce how to upload it automanually.

After we have a big picture of the process of building dashboard.jsonnet, then let us have a look at each file in the repo.

BUILD.bazel

In BUILD.bazel, we can define many bazel tasks to build many dashboards. Notice that dashboard task depend on grafonnet-lib task so thar dashboard.jsonnet can use grafonnet as a library.

dashboard.jsonnet

As you see, writing dashboard as jsonnet code. In the dashboard.jsonnet, we added 3 pannels: buildinfo, systemLoad, networkTraffic.

The most important thing you must to know that is the grafonnet.libsonnet’s path import in the first line:

external/grafonnet-lib/grafonnet/grafana.libsonnet

external folder is where bazel’s external dependency located.
grafonnet-lib folder is the new_git_repository task name we defined in WORKSPACE.
grafonnet is the folder at https://github.com/grafana/grafonnet-lib.git repo.
grafanna.libsonnet is the main interface of grafonnet library.

WORKSPACE

We describe what rules are used in WORKSPACE file. new_git_repository task will download grafonnet repo from github.

grafonnet-lib.BUILD.bazel

Cause the grafana/grafonnet-lib.git repo has not BUILD file to build, so we add one in our repo that grafonnet-lib new_git_repository’s build_file attribute can reference it.

In grafonnet library, attribute name’s value(grafonnet) is referenced by task dashboard’s deps attribute( values is [“@grafonnet-lib//:grafonnet”]) in BUILD.bazel we talked before.

Building in Github Actions

We added Github pipeline where is defined in .github/workflows/build.yaml to our repo. Then push code to Github, therefore Github Actions build it.

Conclusion

At this article, we introduced the structure of the repo and how to build it on you laptop. Then we go through each files in the repo for understanding the relations of them. Finally, Github Actions help us to build them.

Of cause, in your team, it’s necessary to have a review at code before merging new code to the main branch.

Github: https://github.com/zacker330/bazel-jsonnet-grafana-demo