Grafana-DSL

A DSL for programmatically generating Grafana dashboards. Currently, this module does not interface with Grafana's API. Instead, write the configurations to disk and configure Grafana to load the dashboards.

[dashboards.json]
enabled = true
path = /var/lib/dashboards

Installation

npm install -s grafana-dsl

Usage

import dashboard from 'grafana-dsl';

const backendDashboard = dashboard()
  .title('Backend Dashboard')
  .row(row => row()
    .graohPanel(panel => panel()
      .title('CPU')
      .span(12)
      .target(target => target()
        .expr('node_cpu')
        .datasource('Prometheus'))
      .alert(alert=> alert()
        .name('High CPU')
        .notifications([1])
        .condition(condition => condition()
          .when('max')
          .of(1)
          .isAbove(50)))));

// output
require('fs').writeFileSync(__dirname + '/backendDashboard.json', JSON.stringify(backendDashboard.serialize()));

In addition to the above syntax, you can also create objects like rows, panels, alerts, and more directly. This pattern enables reusable configuration components.

import dashboard, { graohPanel } from 'grafana-dsl';

const cpuGraph = graphPanel()
  .title('CPU')
  .span(12)
  .target(target => target()
    .expr('')
    .datasource('Prometheus'))
  .alert(alert => alert()
    .name('High CPU')
    .notifications([1])
    .condition(condition => condition()
      .when('avg')
      .of(1)
      .isAbove(50)));

const backendDashboard = dashboard()
  .row(row => row()
    .graphPanel(cpuGraph));

// output
require('fs').writeFileSync(__dirname + '/backendDashboard.json', JSON.stringify(backendDashboard.serialize()));

DSL

All top level DSL methods accept a config object. Use this parameter to directly pass raw Grafana configuration to accomodate cases where the DSL doesn't provide a required method.

Dashboard

method	description	default
title	Set dashboard title	''
tags	Set dashboard tags	[]
refresh	Set refresh rate	1m
time(from,to='now')	Set time range	from=now-1h to=now
template	Add template variable. Accepts either a callback function receiving template DSL function, or a pre-configured template object
row	Add row. Accepts either a callback function receiving row DSL function, or a pre-built row object

Template

method	description	default
name	Set template variable name	''
type	Set template variable type (e.g: query,custom)	''
multi(val=true)	Toggle multi-select	false
includeAll(val=true)	Include all option	false
query	Template variable query. For type=custom, a comma delimited list of options
datasource	For type=query, set the datasource
regex	For type=query, apply a regex against each return value
refreshOnLoad	Sets refresh=1 to enable variable refresh on dashboard load
refreshOnTimeChange	Sets refresh=2 to enable variable refresh on time change

Row

method	description	default
title	Set row title	''
singleStatPanel	Accepts either a callback function receiving singleStatPanel DSL function, or a pre-configured singleStatPanel object
graphPanel	Accepts either a callback function receiving graphPanel DSL function, or a pre-configured graphPanel object

graphPanel

method	description	default
title	Set panel title	''
span	Set panel span (Out of 12 columns)	12
datasource	Set panel datasource	''
lines	Toggle lines draw mode	true
points	Toggle lines draw mode	false
bars	Toggle lines draw mode	false
format	Shortcut for setting yaxes.format	``
fill	Set fill transparency 0-10	1
yaxes	Configure yaxes for graph. Accepts either a callback function receiving yaxes DSL function, or a pre-configured yaxes object
target	Add target to panel. Accepts either a callback function receiving target DSL function, or a pre-configured target object
alert	Configure alerting for panel. Accepts either a callback function receiving an alert DSL function, or a pre-configured alert object

singleStatPanel

method	description	default
title	Set panel title	''
span	Set panel span (Out of 12 columns)	12
format	Set data format (e.g short, percent)	'short'
datasource	Set panel datasource	''
target	Add target to panel. Accepts either a callback function receiving target DSL function, or a pre-configured target object
sparkline	Enable sparklines. Accepts either a callback function receiving a sparkline DSL function, or a pre-configured sparkline object
alert	Configure alerting for panel. Accepts either a callback function receiving an alert DSL function, or a pre-configured alert object
valueName	Set value name property for panel	'avg'

Target

Configure a panel target.

method	description	default
expr	The query to execute	''
legendFormat	Configure target's legend format

sparkline

Configure singlestat panel sparkline.

method	description	default
show(val=true)	Show sparkline	false
full(val=true)	Set sparkline to full background mode	false
fillColor({rgba(,,,)})	Set sparkline fill color	'rgba(31, 118, 189, 0.18)'
lineColor({rgb(,,,)})	Set sparkline line color	'rgb(31, 120, 193)'

yaxes

Configure panel yaxes for graphPanel

method	description	default
format	Set data format	'short'
show	Show y axes	true
max	Set max value	``
min	Set min value	``

Alert

Configure a panel alert. Currently only for graphPanel

method	description	default
name	Set alert name	''
frequency	Set alert check frequency	''
notifications([{0-9},])	Set alert notifications. Pass in the notification ID. You can find this from the notification edit page (e.g /alerting/notification/1/edit -> .notifications([1]))	[]
condition	Configure an alert condition. Accepts either a callback function receiving a condition DSL function, or a pre-configured condition object

Condition

Configure an alert condition.

method	description	default
when	e.g: avg,min,max,sum,median,count,last	'avg'
of(index,start='5m',end='now')	Set the alert query target and window. The first param is the id of a configured panel target. If your panel has a single target, you would pass 1	index=null start='5m' end='now'
isAbove(val)	Set condition evaluator to gt
isBelow(val)	Set alert condition evaluator to lt
isOutsideRange(from, to)	Set alert condition evaluator to outside_range
isWithintRange(from, to)	Set alert condition evaluator to within_range
hasNoValue	Set alert condition evaluator to no_value

Contributors

• Nouman Saleem