Discovering how to use the Grafana scripting interface

If you're here, you already know what Grafana is and how easy it is to make professional-looking dashboards (graphs) of your favorite timeseries data. But again, because you're here, maybe you need to use the scripting interface to make your data presentation even more awesome.

Before I go any further, I want to state that the documentation on the Grafana website is, for the most part, VERY well done and extensive. But the scripting documentation....well, let's just say that there isn't a lot there. Grafana gives you a very minimal example (with no real database access) to whet your appetite and make you wish for more - but - as for actual reference guides....you're out of luck.

So I'm going to share some of the things I've discovered while trying glean info about this interface. Maybe you already discovered these things, but they were less than obvious to me.

The first thing you'll see in the Grafana example is what seems to be a pretty straightforward method of defining a dashboard on-the-fly using JSON:

var rows = 1;
var seriesName = 'argName';

if(!_.isUndefined(ARGS.rows)) {
  rows = parseInt(ARGS.rows, 10);
}

if(!_.isUndefined(ARGS.name)) {
  seriesName = ARGS.name;
}

for (var i = 0; i < rows; i++) {

  dashboard.rows.push({
    title: 'Scripted Graph ' + i,
    height: '300px',
    panels: [
      {
        title: 'Events',
        type: 'graph',
        span: 12,
        fill: 1,
        linewidth: 2,
        targets: [
          {
            'target': "randomWalk('" + seriesName + "')"
          },
          {
            'target': "randomWalk('random walk2')"
          }
        ],
      }
    ]
  });

}

return dashboard;

JSON is great! I was so excited to see this! I'll really be able to do a lot with this! But uh...how did the guy who wrote the above script know that there were fields named 'title' and 'type' and 'span' available in the 'panels' array? How did he know there even WAS a 'panels' array? What is the 'target' thing? It seems important....  So - where can I find all the parameters?

Ideally, there would be a reference guide available that you could use to find out all the parameters that you can set for a dashboard using the JSON interface. Alas, there is not (at least, not at the time of this writing or at least none that I can find).

Also, you may have noticed that when you try to run the example script scripted.js that they reference (above) it doesn't work. Not at all. I mean, you DO get 'n' dashboards created - which is cool! But they are useless, empty dashboards:

Hovering over the exclamation icon in the upper left corner tells you "Timeseries data request error". Examining the parameters of the dashboard you'll see a whole lot of default nothingness.

I tested the script like so:

http://<my-server>:3000/dashboard/script/scripted.js?rows=2&name=clients

My linked database is an influxdb instance and has a series named "clients". Alas, as I said, the above URL did not work at all. Maybe I'm invoking it incorrectly...but I could find no documentation on what I should see or how I should invoke it, so poking around in the code this was what I came up with.

So - what to do? Well, hang in there, because there's hope! If you've already successfully joined your Grafana installation with your favorite backend DB, odds are you've also already successfully created a dashboard or two. Using these already-existing dashboards, there's a way to get them dumped out as JSON! 

Here are two simple dashboards showing a series named "clients" from my influxdb instance:

Two simple dashboards

One less-than-intuitive thing about Grafana, is that you can click on the title of a dashboard to pull up the 'panel menu'. I must point out that this is indeed documented in the "getting-started guide" (you should definitely read this whole thing if you haven't already - even if you THINK you know what you're doing). But to a novice user, it's not obvious that the control is there. But I'm sure you've already discovered this by now or you never would have made any useful panels. 

Once you've clicked on the title and have the panel menu active, click on the menu 'button' on the left of the pop-up.

This will give you a drop-down selection:

Select Panel JSON from the panel menu

Yes, that's right, if you choose "Panel JSON" you'll get a JSON 'dump' of your panel! This will show you ALL the parameters you can tweak using the scripting interface! You ALSO can modify the json in the presented window to alter the dashboard. I'll grant you, this would be a very strange way to do this when you've got such nice GUI controls that do the same thing - but - it's available!

JSON "dump" of a typical panel

So, adding flesh to the skeletal structure of the original example posted on the Grafana doc site, we can do something like this:

Note the 'query' field (you knew it HAD to be there somewhere - didn't you?). It's the key to pulling out data from your associated database.

Of course, this is a very specific example tailored to my needs. But I've always believed an example is worth gigs of abstract documentation.