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.
Name | Description | Required | Default |
---|---|---|---|
GRAFANA_URL | Fully qualified domain name of your Grafana instance. | true | - |
GRAFANA_USER | Basic auth username if applicable. | false | api_key |
GRAFANA_TOKEN | Basic auth password or API token. | false | - |
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
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