# grafana/jsonnet-libs: dashboards and alerts as code

> Grafana Labs' Jsonnet libraries are an Apache 2.0 licensed collection of the configurations the company uses to ship monitoring mixins, observability libraries, a dashboard builder pattern and a Kubernetes overlay, with two linters and a promtool test convention behind them. The judgement is that the repository is mostly a format and a convention rather than a library, and that the signal extension is the part of the format still being designed.

**grafana/jsonnet-libs** — Grafana Labs' Jsonnet libraries

- Repository: https://github.com/grafana/jsonnet-libs
- Stars: 734 · Forks: 189
- Language: Jsonnet
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/grafana-jsonnet-libs

## A monorepo of dashboards, alerts and the format they share

Grafana Labs' Jsonnet libraries is the repository of the various Jsonnet libraries the company uses, and the topic list on the repository describes it as a monorepo for observability and Prometheus.

The scale is the first thing to understand. The tree contains a directory for each technology the company monitors, with mixin directories for ActiveMQ, Airflow, Camel, Cassandra, CouchDB, Hadoop, HBase, HTTP, Mesos, Solr, Tomcat, Argo CD, Asterisk, AWX, Caddy, Catchpoint, Ceph, Cilium Enterprise, ClickHouse, Cloudflare, Cloudflare Workers, Confluent Kafka, Couchbase, CSP, Discourse, Docker, Elasticsearch, Envoy, the etcd operator, the F5 BIG-IP, GitLab, the Go runtime, the Grafana Agent, Jira, Kafka, Kubernetes, Memcached, Node.js, OVHcloud, Percona, RabbitMQ, Redis, ScyllaDB, SNMP, Solidigm and Windows, among others, plus standalone pieces such as alertmanager, cert-manager, the consul directory, docker-registry, the common library, the Grafana builder and the grizzly tooling.

What makes that collection usable is that it is not forty unrelated projects. It is one format, described on the monitoring mixins site, with two kinds of component built on top of it, the mixins and the observability libraries, and a shared library directory that applies consistent style options across everything.

The repository is maintained actively, with the last push on 2026-10-20, and it carries the governance files a company repository needs, a CODEOWNERS file, an AGENTS.md, a CLAUDE.md and a scripts directory. There are no GitHub releases, because the artefact is the content, not a package.

## The four libraries that are not mixins

Four entries in the tree are libraries rather than collections of dashboards, and they are the ones a user is most likely to depend on directly.

prometheus-ksonnet is a set of extensible configurations for running Prometheus on Kubernetes. ksonnet-util is an overlay and a set of utilities aimed at making working with Kubernetes easier. grafana-builder is a library for building Grafana dashboards with Jsonnet, following the builder pattern. And oauth2-proxy is a Jsonnet configuration for deploying the OAuth proxy from bitly to Kubernetes.

The builder pattern deserves a note, because it is the one that shapes how you write a dashboard. A builder library means you compose a dashboard from reusable pieces rather than assembling the JSON by hand, so the same panel definitions can be shared between dashboards and the layout code stays short. The other three are infrastructure configurations, and the fact that they live in the same repository as the mixins is a hint about how the company works, with the same packaging and the same review process for a Prometheus deployment as for a dashboard set.

The oauth2-proxy configuration is also the one with an explicit upstream, the bitly project, which is notable because it tells you where to look if you want to understand the deployment itself rather than the Jsonnet that packages it.

## A mixin is a directory with a standard shape

The mixin concept comes from a format described on the monitoring mixins site, and each mixin in this repository is a directory with the -mixin suffix, holding a set of reusable and extensible dashboards and alerts for one technology.

The named examples in the readme are the Consul mixin for HashiCorp's Consul, the Memcached mixin, the Node.js mixin, the Caddy mixin and the JIRA mixin, and the readme says you can find more in the directories with the -mixin suffix. The word reusable is doing real work in those descriptions, because a mixin is meant to be imported by someone else's configuration rather than copied, and the extension part means a mixin can be a base for a mixin of your own.

The format is enforced by a linter. The readme states that the monitoring mixins use two linting tools to ensure quality and consistency, and names them. mixtool validates the structure and syntax of monitoring mixins, ensuring they follow the standard mixin format, and pint lints Prometheus rules and alerts to catch common mistakes and enforce best practices.

That split is the interesting part. mixtool is checking the shape of the Jsonnet, that the files are where the format says they should be and that the structure parses the way the mixin specification expects. pint is checking the content, that the PromQL does what it is supposed to and that the alerts follow the rules the Prometheus community has agreed on. A mixin that passes both is structurally a mixin and semantically a set of good rules, and the two failures are different in kind and would be fixed in different files.

## Observability libraries and the experimental signal extension

An observability library is described as a modular format for dashboards and alerts, so that libraries can be imported into one another or into monitoring mixins. They live in folders with the -observ-lib suffix, and the common library is also used to apply consistent style options.

The examples in the readme are the Kafka, JVM, SNMP, process, Golang and Windows observability libraries, plus the docker, CSP and other mixins that use them. So a library captures the knowledge about one system, the metrics it exposes and the dashboards that make sense for them, and a mixin for a product assembles the libraries of the components it runs.

The signal extension is the part that is still being designed, and the readme calls it experimental. A signal is a declaration of a metric, and the point of declaring metrics separately is that the same declaration can be rendered as different Grafana panel types, a time series, a stat or a table, or as an alert rule. The same metric, one source of truth, several presentations.

That is the kind of extension that saves real work in a mixed stack, because a metric that is a time series on one dashboard and a table on another is usually written twice, and the two copies drift. The cost is that the extension is experimental, so the format it produces may still change, and the examples it ships are the specification.

## The tool chain is pinned in the Makefile

The Makefile is the place to look for how the tool chain is put together, and the pinning is consistent with how the mixins are built.

The formatter is jsonnetfmt with an explicit set of options, two spaces of indentation, at most two blank lines, single string style and single comment style, and the fmt target finds every .libsonnet and .jsonnet file in the tree and formats it in place. The formatting is therefore not a matter of taste, it is the same everywhere, and it is enforced on commit.

The install target installs the tools that are not installed from a package manager, and the versions are pinned deliberately:

```make
go install github.com/google/go-jsonnet/cmd/jsonnet@v0.22.0
go install github.com/monitoring-mixins/mixtool/cmd/mixtool@main
go install github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb@v0.6.0
go install github.com/cloudflare/pint/cmd/pint@v0.70.0
```

So the Jsonnet implementation, the formatter and the linter are all at the same version, the bundler is at a fixed release, and the Prometheus rule linter is at a fixed release. The mixtool is installed from the main branch rather than a tag, which is the one unpinned entry, and the reason is obvious once you know that mixtool is the tool that defines and checks the mixin format, so it has to track the format as it evolves.

Prometheus's own tool is handled separately. The install-promtool target downloads a release archive of promtool 3.2.0 for the detected operating system and architecture, unpacks it and moves the binary into the path, and the target contains a mapping from the machine architecture to the naming the Prometheus release uses, x86_64 to amd64, aarch64 to arm64 and armv7l to armv7.

## promtool test rules is the safety net for the alerts

The recommendation in the readme is specific and practical: it is highly recommended to test Prometheus alerts with the promtool test rules command when complex PromQL queries are used, or when additional queries are used in the alerts' annotations.

The reason is that the alert rules are code, and code that runs only when an alert fires is code nobody runs. A PromQL expression that silently returns no data, an annotation query that returns nothing, a threshold that no longer matches the metric, none of these fail loudly in a dashboard review, they just produce an alert that never fires or an alert with an empty context. The unit test file is where you can pin that behaviour down.

The conventions are specified so the continuous integration can find the tests. The test files should be placed in a tests directory at the root of the library, and they should be named like prometheus_*.yaml. That naming is what enables the tests to run in GitHub Actions and with the make test command, so a test file in the wrong place is a test file that never runs.

The readme points at a good example in the Windows observability library, in a file called prometheus_alerts_test.yaml. The Windows library is a sensible place for one, because Windows alerting is the kind of case where the queries are conditional and the annotations pull in extra series, which is exactly the situation the recommendation is aimed at.

## Changing a mixin is five commands

The contributing section describes the loop for changing a mixin, and it is short enough to follow without a tutorial.

The first step is to install the mixin dependencies, with make, which is the target that installs the formatting, linting and test tools. Then you change to the target mixin directory, for example into the Memcached mixin, and install the Jsonnet dependencies with jb install, which is the jsonnet-bundler resolving the imports the mixin declares.

After that you edit the dashboard, alert or other files, the readme uses dashboards.jsonnet as the example, and then you run make again to format, lint and generate the updated mixin rendered files.

```console
cd memcached-mixin/
jb install
vim dashboards.jsonnet
make
```

Two things are notable about that sequence. The rendered files are generated rather than written by hand, and they are committed, which means a pull request contains both the source and the output, and the diff in the output is how a reviewer sees what the change actually does to the dashboards. And the same make command runs in continuous integration, so the formatting and the linting are checked on the same files you edited.

The repository also carries a separate Makefile_mixin file, a common library for shared style, a scripts directory for the shared tooling and a docs directory, and the CODEOWNERS file tells you which team owns which mixin, which is the practical answer to who to ask when a dashboard for one of the forty technologies needs to change.

## Conclusion

grafana/jsonnet-libs fits a team that wants to consume or contribute to Grafana's monitoring mixins, because the mixin and observability library conventions are documented well enough to build a new one, and the tooling, jsonnetfmt, mixtool, pint and promtool, is already wired into the make targets. It is the wrong choice if you want a Grafana dashboard builder, since the grafana-builder library is one of four components here and the mixins are the bulk of the repository, and it is the wrong choice if you are not ready to work in Jsonnet, because a dashboard is generated code and the generated output has to be committed alongside the source. Before you start, run make to install the tool chain, read the mixin format specification rather than copying an existing mixin, and put your promtool tests in a tests directory with the prometheus_ prefix, because that naming is what the continuous integration looks for.

## FAQ

### What is Grafana Labs' Jsonnet libraries repository?

It is an Apache 2.0 licensed monorepo of the Jsonnet libraries the company uses, including prometheus-ksonnet for running Prometheus on Kubernetes, grafana-builder for building dashboards, ksonnet-util as a Kubernetes overlay and an oauth2-proxy configuration, plus a large set of monitoring mixins and observability libraries.

### What is the difference between a mixin and an observability library?

A monitoring mixin is a directory of reusable dashboards and alerts for one technology, following the format described on the monitoring mixins site. An observability library is a modular description of dashboards and alerts for one system that can be imported into other libraries or into mixins, and the common library applies consistent style options across them.

### How are the mixins checked for quality?

Two linters are used. mixtool validates the structure and syntax so the mixins follow the standard format, and pint from Cloudflare lints the Prometheus rules and alerts for common mistakes. The Makefile pins the Jsonnet tools at version 0.22.0, the bundler at 0.6.0 and pint at 0.70.0.

### How do I test the alert rules in a mixin?

With promtool test rules, which the readme recommends whenever complex PromQL or extra annotation queries are involved. The test files go in a tests directory at the root of the library and are named prometheus_*.yaml, which is what lets the continuous integration and the make test command find them.

## Sources

- [grafana/jsonnet-libs on GitHub](https://github.com/grafana/jsonnet-libs)
- [Issues](https://github.com/grafana/jsonnet-libs/issues)
- [README](https://github.com/grafana/jsonnet-libs/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/grafana-jsonnet-libs