Grafonnet: Grafana dashboards as Jsonnet, generated from the API spec

The library is generated, and that is the point

Grafonnet is a Jsonnet library for generating Grafana dashboards, and the distinguishing fact about it is stated in the second paragraph of the introduction. The library is generated from OpenAPI documents in the grafana-foundation-sdk, and those documents are themselves generated from the Grafana repository, specifically to ensure that Grafonnet can keep up with Grafana development. That is the whole design, and it is a direct answer to a problem the previous library had. Grafonnet is the spiritual successor of grafonnet-lib, and the README explains the two reasons for the change. The old library was manually written, so it had a hard time keeping up with Grafana development, which resulted in it being under-maintained. It also came with a performance penalty in Jsonnet, because it used the builder pattern, which is visually appealing but becomes very slow for environments that need to manage many dashboards. The second point is the more interesting one technically, since the builder pattern is the most common way to write a fluent configuration API, and in Jsonnet it means a deeply nested call chain evaluated at every use. A generated library of plain data avoids that, and the practical difference shows up exactly where the README says it does, in a fleet of dashboards rather than a single one.

The experimental warning is unusually specific

The README carries a warning block that is worth quoting in full, because it tells you what kind of project this is. The code in this repository should be considered experimental. Documentation is only available alongside the code. It comes without support, but the maintainers are keen to receive feedback on the product and suggestions on how to improve it, though they cannot commit to resolution of any particular issue. No SLAs are available. It is not meant to be used in production environments, and the risks are unknown and high. That last phrase, risks unknown and high, is the one to take seriously, because a dashboard library that produces invalid or subtly wrong dashboard JSON will not fail loudly, it will produce a dashboard that renders and lies. The README also points to the release life cycle documentation for Grafana Labs, which is where the surrounding product's own stability policy is described. This matters for a library whose whole job is producing a configuration file that a shared Grafana instance will act on, and a team that has a change management process for its dashboards should read this before wiring it into a pipeline.

Jsonnet, go-jsonnet and the jsonnet-bundler

The requirements section names the language and then makes a strong recommendation about which implementation to use. Grafonnet uses the Jsonnet programming language, and the note is that there is a significant performance issue with the C implementation of Jsonnet, so you are strongly recommended to use the newer go-jsonnet implementation, which is also the implementation recommended by the Jsonnet developers themselves. That is a useful warning because the C implementation is the older and more widely installed one, so a system with a package manager entry for jsonnet may well hand you the slow one without saying so. The library is installed with jsonnet-bundler, which is the standard package manager for Jsonnet, and the install command names the repository and a versioned path.

jb install github.com/grafana/grafonnet/gen/grafonnet-latest@main

The path in that command is worth understanding, because it explains the layout of the repository. The gen/ directory holds the generated library, and it is versioned, with the Makefile showing a LATEST variable set to v13.0.0 and a generate target that produces gen/grafonnet-latest from a versioned directory. The examples/ directory contains the shipped examples, and the sed in the Makefile rewrites the version string inside the expected output files so the examples keep matching. The custom/ directory presumably holds the hand written parts that generation cannot produce, and generator/ and scripts/ hold the code generation itself, with the generate.sh and generate_latest.sh scripts invoked by the Makefile target.

Writing a dashboard, and rendering it to JSON

The usage example is short enough to read in one breath, and it shows the shape of the API. A dashboard.jsonnet file imports the library and calls the dashboard constructor.

// dashboard.jsonnet
local grafonnet = import 'github.com/grafana/grafonnet/gen/grafonnet-latest/main.libsonnet';

grafonnet.dashboard.new('My Dashboard')

Then the Jsonnet compiler renders it to JSON, with the vendor directory on the import path.

jsonnet -J vendor dashboard.jsonnet

The naming convention is the giveaway about how the generated library is structured. The import path ends in main.libsonnet, and the call is grafonnet.dashboard.new, so the library is organised as a module per top-level object type, and a dashboard is one of them. From there the generated functions would cover the panels, rows, targets and the rest of the dashboard model, with the point of the generation being that every function corresponds to something in the Grafana API rather than to a hand written convenience. The examples/ directory shows the range of use cases the project expects, with directories for a simple dashboard, a runtime dashboard, a red method example, the documentation examples, a Terraform example and a docs folder. The Terraform one is the interesting signal, because a dashboard library that composes with infrastructure as code is aimed at teams who already generate their Grafana deployment rather than managing it by hand.

Testing, formatting and the documentation build

The Makefile shows how the project is checked, and the test target is worth reading because it explains the test layout. It removes the jsonnetfile.json and the vendor directory, runs jb init, installs the testonnet library from jsonnet-libs, installs the locally generated grafonnet library, and then creates symlinks in the vendor tree so that both the versioned directory and the latest directory resolve to the same generated code. It then walks the test directory looking for files matching the *_test.jsonnet pattern, runs the Jsonnet compiler on each with the vendor and lib paths, and accumulates the exit codes so that a single failure does not stop the sweep. That pattern of running the compiler over a set of test files and checking that it evaluates is a reasonable substitute for unit tests in a language where the artefacts are data, and it is the kind of check that catches a generated library drifting out of sync with the spec. The fmt target runs jsonnetfmt over the library and example sources while excluding the gen and docs directories, which is what you would expect given that the generated code should not be reformatted by hand. The localmkdocs target builds the documentation locally with mkdocs, using a virtual environment under .mkdocs/ and a requirements file of its own, and the repository has a .mkdocs/ directory and a docs/ directory, along with a catalog-info.yaml for the Backstage catalogue and a CODEOWNERS file.

Where Grafonnet is the wrong choice

The first limit is the experimental status, and it is not a formality. The project says the code is experimental, that documentation is only available alongside the code, that there is no support, no SLAs, and that it is not meant for production environments with risks unknown and high. A team with dashboards in production should read that as what it is and either avoid the library or gate every generated dashboard behind review. The second limit is the Jsonnet learning curve, which is real for anyone who has not met the language, and it is compounded by a two-step toolchain, since you need jsonnet-bundler for dependency management and a separate jsonnet compiler to render, plus the vendor directory layout the import path depends on. The third is that the generated library is only as good as its generator, so the value of the project depends on the Grafana foundation SDK keeping pace with the Grafana repository, and while the README claims that coupling is the reason the library exists, it is also the failure mode if the SDK lags. The fourth is that a generated library is harder to bend than a hand written one, since the functions are shaped by the API rather than by your use case, and if you need a dashboard feature the API does not have, you are writing Jsonnet against the generated internals. And the fifth is scope, because a dashboard is a configuration artefact, and if your Grafana provisioning is already handled by something like Terraform or the provisioning API, this library solves a smaller part of the problem than it first appears to.

Editorial conclusion

Adopt Grafonnet if you manage many Grafana dashboards as code and want the dashboard JSON to be generated from a typed library rather than hand-maintained, and you are comfortable with Jsonnet and its bundler. Skip it if you have a handful of dashboards, since the setup cost exceeds the benefit, and read the experimental warning carefully because the project states it is not meant for production and carries no support commitment. Verify first that you use the go-jsonnet implementation rather than the C one, that your Jsonnet tooling can resolve the vendored library path, and that the generated dashboards are reviewed by a human before they reach a shared Grafana instance.

Frequently asked questions

Official sources

1. grafana/grafonnet on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README