graaf

README

Graaf Dashboarding

Create grafana dashboards from simple yaml. Graaf acts like a filter and ingests YAML and spits out Grafana (9+) compatible JSON. Graaf is used to provision Grafana from git and to make humans not review long JSON dashboard, but super short YAML ones. The promQL used in the graphs is syntax checked during the generation.

Graaf also makes your dashboards consistent and takes the fun out of toying with Grafana for hours to make your thing look just right.

Graaf means 'to dig' and 'count' (the noble rank) in Dutch.

Semantic Checks

Each promQL expression must have a job matcher to make sure you're dealing with the right metric.

A expression with only a topk or bottomk is also disallowed, as this retrieves way to many metrics. This can be overriden in the yaml, with the allow: [topk, bottomk] under an expression that uses it.

Dashboards and Panels

Supported are timeseries, heatmaps and stat panels. For grafana homepage tweaking dashlist and a news panel is also supported.

A sample dashboard would look something like this:

title: My example dashboard
uid: stable identifier for this dashboard
panels:
  - timeseries:
     title: Active Memory
     width: 12
     y:
      unit: "decbytes"
      min: 0
     exprs:
       - expr: 'node_memory_Active_bytes{job="node"}'
         legend: "{{__name__}}"

With graaf dashboard.yaml | grep '"uid":' you can check what the UID of a dashboard is, this is important when linking to other dashboards, i.e. the link then becomes <url>/d/<uid>.

The pointsize in timeseries is set to 2 (really small) and to 8 (rather large) if the are panel links.

Columns and Rows

Grafana uses a simple grid, where the total width is 24, and each row is 10 heigh. So having a grid with y: 10 means the second row.

Links

Dashboard links will have the current time and current instance variables attached to them automatically.

For data links see https://grafana.com/docs/grafana/v9.3/panels-visualizations/configure-data-links/#data-links. If a panel has data links the dot size of the pointer is increased to signify there is more to it (as Grafana has no good way of signaling this otherwise...)

Panel links are not supported as these are barely discoverable in the UI.

Dashboards

Each dashboard has an uid that gets generated from the title by SHA1 summing it and taking the first 8 characters. This helps generated fixed dashboard URLs, so data links keep on working.

• title: title for the dashboad
• uid: stable identifier for this dashboard, will be SHA1-ed by Graaf when generating the uid for the dashboard. This must be unique among dashboards!
• vars: holds all variable definitions in var:
  • name: for the variable
  • expr: promQL query, must have a job= matcher.
  • regex: regex to parse expr: e.g. /.*job="(?<value>.*)".*/, the other supported capture group is (?<text>).
  • multi: allow selecting multiple values
• links: dashboard links, see below they are identical in their setup.
• refresh: if you want a dashboard to refresh (in kiosk mode for instance), add this, needs a Go time.Duration string.

Shared Parameters for all Panels

• width: 24 units is the entire screen, stat panel uses 5 by default.

• height: height of the panel, 10 is good (and the default), stat panels are 5.

• grid: that has x, and y values for exact placement in grid. So placing two panels on the same level would entail:

  grid:
    x: 0
    y: 0
  

  and the next panel:

  grid:
    x: 12
    y: 0
  

  At same time assuming the width: 12 is set on both to make 24 in total. Panels have default height of 10, to incrementing y with 10 is a new row.

• color: specify the color for the graph, a single color will apply to all exprs.

• y: the Y axes definition. If not specified it will be "hidden". Has:

  • unit specifies the unit for the Y axes, needs to be a grafana one which can be seen with inspect panel json or see the definitions in grafana.
  • decimals number of decimals places after the dot.
  • min set minimal value
  • max set maximum value

• tags: a list of tags for this dashboard. Helps with searching.

• links: a list of data Links, note Panel Links are not supported.

  • title: title for the link
  • url: set when pointing to external URL
  • tags: set when pointing to dashboards with these tags See https://grafana.com/docs/grafana/v9.0/panels/configure-data-links/ for what can be used inside these links. Especially variable usage as ${__field.labels.instance} and ${__value.time} if set. An example would then be:

  links:
   - title: "CPU details for ${__field.labels.instance}"
     url: "/d/9fc1f0c0/cpu?var-instance=${__field.labels.instance}"
  

  Where var-<name> is the way to give the new panel a variable.

• transparent: a boolean indicating the panel should be transparent, default is false.

• exprs: hold the prometheus expressions.

  • expr: the promQL
  • legend: specify what should be in the legend
  • transform: how to transform the y axes
    • negative-y is the current only supported value.

See https://grafana.com/blog/2019/12/10/pro-tips-dashboard-navigation-using-links/ for all types of links panels can have.

Timeseries Panel

See https://grafana.com/docs/grafana/v9.0/visualizations/time-series/

Use timeseries in the YAML.

Supported are:

• Stack: true, stack the metrics.
• For y you can:
  • scale set scale: valid options: log2, log10, not specifying results in linear. With some units the following is done
  • percent: set min to 0 and max to 100 (if Min and Max isn't set).
  • percentunit: set min to 0.0 and max to 1.0 (if Min and Max isn't set).

Stat Panel

See https://grafana.com/docs/grafana/v9.0/visualizations/stat-panel/

Use stat in the YAML to have a "stat" panel

Heatmap Panel

See <https://grafana.com/docs/grafana/v9.0/visualizations/heatmap/

More...? TODO

News Panel

This is used on the home panel in Grafana, you can link it to an RSS feed and show that in grafana:

- news:
    title: Latest news
    links:
      - url: 'https://localhost/news.xml'

List Panel

Use list in the YAML to have a Dashlist Panel that lists recent and starred panel. This is useful in the home dashboard.

Developer Notes

In sdk/* we have the definitions as used by grafana in the top level directory of graaf we have struct definitions used to parse our yaml files.