How to use grafana scripted dashboards

I’m using prometheus to collect metrics of java applications or unix systems. On top I configured grafana just to have a nice an shiny view and to get the possibility to add dashboards and to save my graphs somehow. Grafana is pretty nice to add graphs in a fast way to new dashboards, but what happens if you have, like I have, a lot of metrics which change or new hosts are getting added. That’ something you don’t want to do by hand. Therefore grafana implemented the “scripted dashboards”. I figured out, that the documentation of these dashboards is more or less not enough to get a full working example. With scripted dashboards you can dynamically create your dashboards using javascript. Some examples can be found in the dashboard directory of the grafana installation. On my debian its located at /usr/share/grafana/public/dashboards. There I also placed my scripts, because everything in that directory can be called via http://Your-Grafana-Url/dashboard/script/FILE.js.

If you take a look at the scripted.js you get a first idea of how to use the scripted dashboard part. But this is just a small example with a short amount of options which can be used in these dashboards. I haven’t found any documentation about the available options, but I found a way to get an overview. You can take a look at one of your already existing dashboards.

Get available options for dashboards

Now we have two options to take a look at the available options:

  1. Take a look at the Dashboard itself
  2. Take a look at a dashboard row/graph

Take a look at the Dashboard itself

To see how the dashboard itself in json looks like, you can press the settings icon and then hit the View JSON section. There you see the whole Dashboard exported as json object.

Take a look at a dashboard row/graph

To view the row/graph json data itself is slightly similar. You have to click on the graph title and then press the option part like shown in the following screenshot:

Under that option you find the Panel JSON section:

If you hit it, you see the json object of the graph/row itself.

Start with a scripted dashboard

I start most of the time with the same lines on top of a js script.

/* setup some variables */
var dashboard;

// Intialize a skeleton with nothing but a rows array and service object
dashboard = {
      rows : [],
};

// Set a title
dashboard.title = 'My dashboard Title';

// Set default time
// time can be overriden in the url using from/to parameters, but this is
// handled automatically in grafana core during dashboard initialization
dashboard.time = {
      from: "now-6h",
        to: "now"
};

After initialising the variables above, I have an array (metrics) which contains all metrics I want to see in that dashboard. Right now I only used one graph per row. It is possible to push the graphs to dashboards row, like in the example below.

var metrics = [ 'metrics1', 'metrics2', 'metrics3'... ]

The panels array contains all needed informations/settings for the specific row, like the graph title, the width (span, 12 is maximum), the datasource (I use prometheus for saving the metrics data) and of course the targets array. This array contains the explicit data to display the graph. expr specifies the expression to show the graph. metric setting is not needed implicitly.

If you want to add a second graph to a row, you have to adapt span to get for both a sum of 12. And than you can add a second dict ({..}) to panels array.

for (var i = 0; i < metrics.length; i++) {
    dashboard.rows.push({
        title: 'Chart',
        height: "300px",
        panels: [
            {
                type: 'graph',
                datasource: 'prometheus',
                title: metrics[i],
                span: "12",
                "nullPointMode": "connected",
                fill: 1,
                linewidth: 2,
                targets: [
                    {
                        "expr": metrics[i],
                        "intervalFactor": 10,
                        "legendFormat": "",
                        "metric": metrics[i],
                        "refId": "A",
                        "step": 100,
                    },
                ],
                tooltip: {
                    shared: true
                }
            }
        ],
    });
}

But to know which settings can be used in panels and targets array, you may have to take a look at the exact json object of an already existing dashboard like described above.

At the end we have to return the dashboard object:

return dashboard;

In the end, if you took a look at already existing graphs/dashboards it is pretty easy to create your own scripted dashboards, but the start itself was very annoying not to have enough documentation.

comments powered by Disqus