Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/noumansaleem/grafana-dsl

alerting dashboards grafana graphs monitoring
Last synced: 13 days ago
JSON representation
Host: GitHub
URL: https://github.com/noumansaleem/grafana-dsl
Owner: NoumanSaleem
Created: 2017-07-26T13:48:05.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2021-01-14T14:49:13.000Z (almost 4 years ago)
Last Synced: 2024-12-15T23:48:05.357Z (13 days ago)
Topics: alerting, dashboards, grafana, graphs, monitoring
Language: JavaScript
Size: 5.86 KB
Stars: 6
Watchers: 3
Forks: 2
Open Issues: 1
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

        # Grafana-DSL

A DSL for programmatically generating [Grafana](http://grafana.org/) 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](https://github.com/noumanSaleem)