Skip to content
GitLab
Explore
Sign in
Primary navigation
Search or go to…
Project
go
Manage
Activity
Members
Labels
Plan
Issues
Issue boards
Milestones
Wiki
Code
Merge requests
Repository
Branches
Commits
Tags
Repository graph
Compare revisions
Snippets
Build
Pipelines
Jobs
Pipeline schedules
Artifacts
Deploy
Releases
Package Registry
Model registry
Operate
Environments
Terraform modules
Monitor
Incidents
Analyze
Value stream analytics
Contributor analytics
CI/CD analytics
Repository analytics
Model experiments
Help
Help
Support
GitLab documentation
Compare GitLab plans
Community forum
Contribute to GitLab
Provide feedback
Keyboard shortcuts
?
Snippets
Groups
Projects
Show more breadcrumbs
cncz
go
Commits
f1a5bf56
Commit
f1a5bf56
authored
1 year ago
by
Miek Gieben
Browse files
Options
Downloads
Patches
Plain Diff
docs
Signed-off-by:
Miek Gieben
<
miek.gieben@ru.nl
>
parent
6cc9ecb4
Branches
paramschange
No related tags found
No related merge requests found
Pipeline
#80829
passed
1 year ago
Stage: test
Stage: build
Stage: deploy
Changes
2
Pipelines
2
Hide whitespace changes
Inline
Side-by-side
Showing
2 changed files
cmd/graaf/graaf.1
+67
-37
67 additions, 37 deletions
cmd/graaf/graaf.1
cmd/graaf/graaf.1.md
+45
-30
45 additions, 30 deletions
cmd/graaf/graaf.1.md
with
112 additions
and
67 deletions
cmd/graaf/graaf.1
+
67
−
37
View file @
f1a5bf56
...
...
@@ -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 dashboard
s
, but
much
short
er
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:
1
2
width: 2
4
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 h
e
igh. 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 dashboa
d
\fB\fCtitle\fR: title for the dashboa
rd.
.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 \fI
d
ata\fP \fB\fCLink\fRs, note Panel Links are not supported.
\fB\fClinks\fR: a list of \fI
D
ata\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 use
d
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
...
...
This diff is collapsed.
Click to expand it.
cmd/graaf/graaf.1.md
+
45
−
30
View file @
f1a5bf56
...
...
@@ -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 dashboard
s
, but
much
short
er
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
:
1
2
width
:
2
4
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 h
e
igh. 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
*
d
ata*
`Link`
s, note Panel Links are not supported.
*
`links`
: a list of
*
D
ata*
`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 use
d
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:
...
...
This diff is collapsed.
Click to expand it.
Preview
0%
Loading
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Save comment
Cancel
Please
register
or
sign in
to comment