Skip to content
Snippets Groups Projects
Commit f1a5bf56 authored by Miek Gieben's avatar Miek Gieben
Browse files

docs


Signed-off-by: default avatarMiek Gieben <miek.gieben@ru.nl>
parent 6cc9ecb4
Branches paramschange
No related tags found
No related merge requests found
Pipeline #80829 passed
......@@ -3,7 +3,7 @@
.SH "NAME"
.PP
graaf \- generate Grafana JSON from smaller YAML dashboards.
graaf \- generate Grafana JSON from smaller YAML dashboards
.SH "SYNOPSIS"
.PP
......@@ -11,10 +11,10 @@ graaf \fI\fB\fC[FILE]\fR\fP
.SH "DESCRIPTION"
.PP
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
\fInot\fP review long JSON dashboard, but super short YAML ones. The promQL used in the graphs is syntax
checked during the generation.
Create grafana dashboards from simple(r) YAML files. Graaf acts like a filter and ingests YAML and
spits out Grafana (9+) compatible JSON. Graaf can be used to provision Grafana from git and to make
humans \fInot\fP review long JSON dashboards, but much shorter YAML ones. The promQL used in the graphs
is syntax checked during the generation.
.PP
If no \fBFILE\fP is given the input is read from standard input. The created JSON is printed to
......@@ -30,16 +30,13 @@ Graaf means 'to dig' and 'count' (the noble rank) in Dutch.
.SS "SEMANTIC CHECKS"
.PP
Each promQL expression \fImust\fP have a \fIjob\fP matcher to make sure you're dealing with the right
metric.
.PP
A expression with only a \fB\fCtopk\fR or \fB\fCbottomk\fR is also disallowed, as this retrieves way to many
metrics. This can be overridden \fIin the yaml\fP, with the \fB\fCallow: [topk, bottomk]\fR under an expression
that uses it.
metric. An expression with only a \fB\fCtopk\fR or \fB\fCbottomk\fR is also disallowed, as this retrieves way to
many metrics. This can be overridden \fIin the YAML\fP, with the \fB\fCallow: [topk, bottomk]\fR under an
expression that uses it.
.SS "DASHBOARDS AND PANELS"
.PP
Supported are timeseries, heatmaps and stat panels. For grafana homepage tweaking dashlist and a
Supported are timeseries, heatmaps and stat panels. For grafana homepage tweaking, dashlist and the
news panel is also supported.
.PP
......@@ -54,7 +51,7 @@ uid: stable identifier for this dashboard
panels:
\- timeseries:
title: Active Memory
width: 12
width: 24
y:
unit: "decbytes"
min: 0
......@@ -67,7 +64,7 @@ panels:
.PP
With \fB\fCgraaf dashboard.yaml | grep '"uid":'\fR you can check what the UID of a dashboard is, this is
important when linking to other dashboards, i.e. the link then becomes \fB\fC<url>/d/<uid>\fR.
important when linking to other dashboards, i.e. the link then becomes \fB\fC.../d/<uid>\fR.
.PP
The point size in timeseries is set to 2 (really small) and to 8 (rather large) if the are panel
......@@ -75,8 +72,8 @@ links.
.SS "COLUMNS AND ROWS"
.PP
Grafana uses a simple grid, where the total width is 24, and each row is 10 heigh. So having a
\fB\fCgrid\fR with \fB\fCy: 10\fR means the second row.
Grafana uses a simple grid, where the total width is 24, and each row is 10 high. So having a \fB\fCgrid\fR
with \fB\fCy: 10\fR means the second row.
.SS "LINKS"
.PP
......@@ -95,14 +92,14 @@ Panel links are not supported as these are barely discoverable in the UI.
.SS "DASHBOARDS"
.PP
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.
Each dashboard has an uid that gets generated from the title by SHA1\-summing it and taking the first
8 characters. This helps generate fixed dashboard URLs, so data links keep on working. Other options
include:
.IP \(bu 4
\fB\fCtitle\fR: title for the dashboad
\fB\fCtitle\fR: title for the dashboard.
.IP \(bu 4
\fB\fCuid\fR: stable identifier for this dashboard, will be SHA1\-ed by Graaf when generating the uid for
the dashboard. This must be unique among dashboards!
\fB\fCuid\fR: stable identifier for this dashboard. This must be unique among dashboards!
.IP \(bu 4
\fB\fCvars\fR: holds all variable definitions in \fB\fCvar\fR:
......@@ -147,6 +144,9 @@ dashboard.
.SS "SHARED PARAMETERS FOR ALL PANELS"
.PP
A dashboard contains multiple panels. Each panels has the following properties.
.IP \(bu 4
\fB\fCwidth\fR: 24 units is the entire screen, stat panel uses 5 by default.
.IP \(bu 4
......@@ -162,8 +162,8 @@ on the same level would entail:
.nf
grid:
x: 0
y: 0
x: 0
y: 0
.fi
.RE
......@@ -176,8 +176,8 @@ and the next panel:
.nf
grid:
x: 12
y: 0
x: 12
y: 0
.fi
.RE
......@@ -206,7 +206,7 @@ inspect panel JSON or see the definitions in grafana
.IP \(bu 4
\fB\fCtags\fR: a list of tags for this dashboard. Helps with searching.
.IP \(bu 4
\fB\fClinks\fR: a list of \fIdata\fP \fB\fCLink\fRs, note Panel Links are not supported.
\fB\fClinks\fR: a list of \fIData\fP \fB\fCLink\fRs, note Panel Links are not supported.
.RS
.IP \(en 4
......@@ -262,7 +262,7 @@ Where \fB\fCvar-<name>\fR is the way to give the new panel a variable.
.RS
.IP \(bu 4
\fB\fCok|warning|critical{value="VALUE[%]"}\fR, where \fB\fCvalue=VALUE\fR is where the threshold
be drawn. If a %\-sign is used, you want it to be a percentage instead of absolute.
is to be drawn. If a %\-sign is used, you want it to be a percentage instead of absolute.
\fB\fCok\fR, \fB\fCwarning\fR or \fB\fCcritical\fR defined the color of the lines, green, yellow or red
respectively.
......@@ -285,13 +285,24 @@ See https://grafana.com/docs/grafana/v9.0/visualizations/time\-series/
Use \fB\fCtimeseries\fR in the YAML.
.PP
Supported are:
* \fB\fCStack: true\fR, stack the metrics.
* For \fB\fCy\fR you can:
\- \fB\fCscale\fR set scale: valid options: log2, log10, not specifying results in linear.
With some units the following is done
* \fB\fCpercent\fR: set min to 0 and max to 100 (if Min and Max isn't set).
* \fB\fCpercentunit\fR: set min to 0.0 and max to 1.0 (if Min and Max isn't set).
Extra supported are:
.IP \(bu 4
\fB\fCStack: true\fR, stack the metrics.
.IP \(bu 4
For \fB\fCy\fR you can:
.RS
.IP \(en 4
\fB\fCscale\fR set scale: valid options: log2, log10, not specifying results in linear.
With some units the following is done
.IP \(en 4
\fB\fCpercent\fR: set min to 0 and max to 100 (if Min and Max isn't set).
.IP \(en 4
\fB\fCpercentunit\fR: set min to 0.0 and max to 1.0 (if Min and Max isn't set).
.RE
.SS "STAT PANEL"
.PP
......@@ -299,7 +310,26 @@ See https://grafana.com/docs/grafana/v9.0/visualizations/stat\-panel/
\[la]https://grafana.com/docs/grafana/v9.0/visualizations/stat-panel/\[ra]
.PP
Use \fB\fCstat\fR in the YAML to have a "stat" panel
Use \fB\fCstat\fR in the YAML to have a "stat" panel, here is an example:
.PP
.RS
.nf
\- stat:
title: Active Memory Usage for $hello
grid:
x: 12
y: 0
y:
unit: "decbytes"
decimals: 1
exprs:
\- expr: 'node\_memory\_Active\_bytes{job="node"}'
legend: "Bytes"
.fi
.RE
.SS "HEATMAP PANEL"
.PP
......@@ -330,7 +360,7 @@ in the home dashboard.
.SS "DEVELOPER NOTES"
.PP
In \fB\fCsdk/*\fR 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.
struct definitions used to parse our YAML files.
.PP
While working on graaf you probably want to load the generated dashboard into grafana. The easiest
......@@ -348,7 +378,7 @@ See if it works, and use "Inspect"\->"Panel JSON" to see what Grafana did with y
.SH "GRAFANA SETUP"
.PP
For Grafana to work you only may used OrgID 1 and provision the datasource and dashboards via the
For Grafana to work you only may use OrgID 1 and provision the datasource and dashboards via the
following YAML config:
.PP
......
......@@ -6,7 +6,7 @@ workgroup = "C&CZ"
## Name
graaf - generate Grafana JSON from smaller YAML dashboards.
graaf - generate Grafana JSON from smaller YAML dashboards
## Synopsis
......@@ -14,10 +14,10 @@ graaf *`[FILE]`*
## Description
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.
Create grafana dashboards from simple(r) YAML files. Graaf acts like a filter and ingests YAML and
spits out Grafana (9+) compatible JSON. Graaf can be used to provision Grafana from git and to make
humans _not_ review long JSON dashboards, but much shorter YAML ones. The promQL used in the graphs
is syntax checked during the generation.
If no **FILE** is given the input is read from standard input. The created JSON is printed to
standard output. There are no options.
......@@ -30,15 +30,13 @@ 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 overridden *in the yaml*, with the `allow: [topk, bottomk]` under an expression
that uses it.
metric. An expression with only a `topk` or `bottomk` is also disallowed, as this retrieves way to
many metrics. This can be overridden *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
Supported are timeseries, heatmaps and stat panels. For grafana homepage tweaking, dashlist and the
news panel is also supported.
A sample dashboard would look something like this:
......@@ -49,7 +47,7 @@ uid: stable identifier for this dashboard
panels:
- timeseries:
title: Active Memory
width: 12
width: 24
y:
unit: "decbytes"
min: 0
......@@ -59,15 +57,15 @@ panels:
~~~
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>`.
important when linking to other dashboards, i.e. the link then becomes `.../d/<uid>`.
The point size 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.
Grafana uses a simple grid, where the total width is 24, and each row is 10 high. So having a `grid`
with `y: 10` means the second row.
### Links
......@@ -83,12 +81,12 @@ 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.
Each dashboard has an uid that gets generated from the title by SHA1-summing it and taking the first
8 characters. This helps generate fixed dashboard URLs, so data links keep on working. Other options
include:
* `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!
* `title`: title for the dashboard.
* `uid`: stable identifier for this 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.
......@@ -110,6 +108,8 @@ Each dashboard has an uid that gets generated from the title by SHA1 summing it
#### Shared Parameters for all Panels
A dashboard contains multiple panels. Each panels has the following properties.
* `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
......@@ -117,14 +117,14 @@ Each dashboard has an uid that gets generated from the title by SHA1 summing it
on the same level would entail:
~~~ yaml
grid:
x: 0
y: 0
x: 0
y: 0
~~~
and the next panel:
~~~ yaml
grid:
x: 12
y: 0
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.
......@@ -137,7 +137,7 @@ Each dashboard has an uid that gets generated from the title by SHA1 summing it
- `min` set minimal value
- `max` set maximum value
* `tags`: a list of tags for this dashboard. Helps with searching.
* `links`: a list of *data* `Link`s, note Panel Links are not supported.
* `links`: a list of *Data* `Link`s, 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
......@@ -160,7 +160,7 @@ Each dashboard has an uid that gets generated from the title by SHA1 summing it
- `negative-y` is the current only supported value.
- `threshold`: draw a (dashed) threshold line. These are _also_ specified in a promQL syntax:
* `ok|warning|critical{value="VALUE[%]"}`, where `value=VALUE` is where the threshold
be drawn. If a %-sign is used, you want it to be a percentage instead of absolute.
is to be drawn. If a %-sign is used, you want it to be a percentage instead of absolute.
`ok`, `warning` or `critical` defined the color of the lines, green, yellow or red
respectively.
......@@ -173,7 +173,8 @@ See <https://grafana.com/docs/grafana/v9.0/visualizations/time-series/>
Use `timeseries` in the YAML.
Supported are:
Extra supported are:
* `Stack: true`, stack the metrics.
* For `y` you can:
- `scale` set scale: valid options: log2, log10, not specifying results in linear.
......@@ -185,7 +186,21 @@ Supported are:
See <https://grafana.com/docs/grafana/v9.0/visualizations/stat-panel/>
Use `stat` in the YAML to have a "stat" panel
Use `stat` in the YAML to have a "stat" panel, here is an example:
~~~ yaml
- stat:
title: Active Memory Usage for $hello
grid:
x: 12
y: 0
y:
unit: "decbytes"
decimals: 1
exprs:
- expr: 'node_memory_Active_bytes{job="node"}'
legend: "Bytes"
~~~
#### Heatmap Panel
......@@ -211,7 +226,7 @@ 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.
struct definitions used to parse our YAML files.
While working on graaf you probably want to load the generated dashboard into grafana. The easiest
way to do this is:
......@@ -223,7 +238,7 @@ way to do this is:
## Grafana Setup
For Grafana to work you only may used OrgID 1 and provision the datasource and dashboards via the
For Grafana to work you only may use OrgID 1 and provision the datasource and dashboards via the
following YAML config:
In `.../provisioning/dashboards/dashboards.yaml`, put:
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment