Grafana-dsl NPM

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

grafana grafana dashboard grafana dashboard json grafana json

@everything-registry/sub-chunk-1782 @infinitebrahmanuniverse/nolb-graf

1.0.15

7 years ago

1.0.14

7 years ago