Skip to content

Latest commit

 

History

History
178 lines (150 loc) · 6.8 KB

README.md

File metadata and controls

178 lines (150 loc) · 6.8 KB
Raw

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