A utility for managing Jsonnet dashboards - uses the Grafana REST API.

It is designed to work with monitoring mixins. It expects dashboards to be exposed by a libsonnet file as a grafanaDashboards object.

Status: Alpha. This is a proof of concept. It will have many holes. PRs welcome.

This tool interacts with Grafana via its REST API. For this, you will need to establish authentication credentials. These are provided to grr via environment variables.

See Grafana's Authentication API docs for more info.

Retrieves a dashboard from Grafana, via its UID:

$ grr get my-uid

List dashboard keys from file.

$ grr list some-mixin.libsonnet

Shows the mixin rendered as json.

$ grr show some-mixin.libsonnet

Compares each dashboard rendered by the mixin with the dashboard in Grafana

$ grr diff some-mixin.libsonnet

Uploads each dashboard rendered by the mixin to Grafana

$ grr apply some-mixin.libsonnet

Watches a directory for changes. When changes are identified, the mixin is rendered and pushed to Grafana.

$ grr watch . some-mixin.libsonnet

This watches any files in the current directory . for changes, then renders dashboards from some-mixin.libsonnet.

Renders dashboards to JSON in a directory, either specified with GRAFANA_DIR or with a second argument. This can be used with Grafana Provisioning to provision dashboards that can be picked up immediately by Grafana.

$ grr export some-mixin.libsonnet my-provisioning-dir

Renders a mixin and uploads each dashboard produced as snapshots to Grafana. Prints out links for each dashboard that was uploaded.

$ grr preview some-mixin.libsonnet

Snapshots by default do not expire. Expiration can be set via the -e, --expires flag which takes a number of seconds as an argument.

The show, diff, and apply commands accept this flag. It allows the targeting of dashboards by key. This can be useful if there are many dashboards configured in the Jsonnet file you are working with. Run grr list to get a list of the dashboard keys.

Create a file, called mydash.libsonnet, that contains this:

{

  grafanaDashboardFolder: 'my-folder', // optional

  grafanaDashboards+:: {
    'my-dash.json': {
      uid: 'prod-overview',
      title: 'Production Overview',
      tags: ['templated'],
      timezone: 'browser',
      schemaVersion: 16,
    },
  },
}

Note that this dashboard has a UID. UIDs are required for grr to function correctly.

This file follows the standard Monitoring Mixin pattern as defined within the prometheus-ksonnet library.

Now, we can see this rendered as a JSON dashboard with:

$ grr show mydash.libsonnet

Next, we need to interact with Grafana. You will need to export two environment variables: GRAFANA_TOKEN, an API token created within Grafana itself, and GRAFANA_HOST, the hostname for your Grafana installation. If the Grafana instance is not hosted at the root of the domain, you can add specify a hostname such as admin.example.com/grafana. If your Grafana does not use SSL, you can set GRAFANA_PROTOCOL to http.

Now, let's push our dashboard to Grafana:

$ grr apply mydash.libsonnet

At this point, you should find your dashboard has been uploaded and will be visible within the Grafana UI.

As a next step, we shall make a change to our dashboard. In your mydash.libsonnet, change the title to Production Overview mk2.

Then:

$ grr diff mydash.libsonnet

will show us the single change we have made to our dashboard.

And next:

$ grr apply mydash.libsonnet

will push our change up to Grafana. Check your Grafana dashboard list - you should see your dashboard show with its new name.

You can retrieve a dashboard from Grafana via its UID:

$ grr get prod-overview