Getting started with Dashboard-as-Code#
Info
See the introduction about the Dashboard-as-Code (DaC) topic here.
Getting started with the CUE SDK#
Prerequisites#
percli
, the CLI of Perses.cue
, the CLI of Cuelang.
Repository setup#
Create a new folder that will become your DaC repository, then follow the steps below:
1. Initialize the CUE module#
See the CUE documentation for more information about this step.
2. Retrieve the CUE sources from Perses#
Ideally we should rely on a native dependency management here, but since it's not yet available for CUE as already mentioned, we provide in the meantime a dedicated CLI command dac setup
in order to add the CUE sources from Perses as external dependencies to your repo:
You can omit the version flag if you are connected to a Perses server (it will retrieve its version). Otherwise, unless you have a specific case, better to pass the latest version available.
Develop dashboards#
You are now fully ready to start developping dashboards as code!
It's first strongly recommended to ramp up on CUE if you are not familiar with this technology. For this have a look at:
- The official website of Cuelang.
- Cuetorials, a 3rd party source of information that is a very good complement.
You should then have a look at the CUE SDK documentation to better understand how to use the framework.
You can also check an example of DaC usage here.
Getting started with the Go SDK#
Prerequisites#
percli
, the CLI of Perses.go
, the programming language.
Repository setup#
Create a new folder that will become your DaC repository, then follow the steps below:
1. Initialize the Go module#
See the Go documentation for more information about this step.
2. Install the Perses SDK#
If you need a specific version, you can specify it as follows:
Develop dashboards#
You are now fully ready to start developing dashboards as code!
It's first strongly recommended to ramp up on Go if you are not familiar with this technology. For this have a look at:
- The official website of Go.
You should then have a look at the Go SDK documentation to better understand how to use the framework.
You can also check an example of DaC usage here.
Warning
Do not log / print on the standard stdout! It would break the output of the dac build
command.
Quick start example:
package main
import (
"flag"
"github.com/perses/perses/go-sdk"
"github.com/perses/perses/go-sdk/dashboard"
"github.com/perses/perses/go-sdk/panel"
"github.com/perses/perses/go-sdk/prometheus/query"
"github.com/perses/perses/go-sdk/panel-group"
timeSeriesPanel "github.com/perses/perses/go-sdk/panel/time-series"
promDs "github.com/perses/perses/go-sdk/prometheus/datasource"
labelValuesVar "github.com/perses/perses/go-sdk/prometheus/variable/label-values"
listVar "github.com/perses/perses/go-sdk/variable/list-variable"
)
func main() {
flag.Parse()
exec := sdk.NewExec()
builder, buildErr := dashboard.New("ContainersMonitoring",
dashboard.ProjectName("MyProject"),
dashboard.AddVariable("stack",
listVar.List(
labelValuesVar.PrometheusLabelValues("paas",
labelValuesVar.Matchers("thanos_build_info{}"),
labelValuesVar.Datasource("promDemo"),
),
listVar.DisplayName("My Super PaaS"),
),
),
dashboard.AddPanelGroup("Resource usage",
panelgroup.PanelsPerLine(3),
panelgroup.AddPanel("Container memory",
timeSeriesPanel.Chart(),
panel.AddQuery(
query.PromQL("max by (container) (container_memory_rss{paas=\"$paas\",namespace=\"$namespace\",pod=\"$pod\",container=\"$container\"})"),
),
),
),
dashboard.AddDatasource("promDemo", promDs.Prometheus(promDs.HTTPProxy("https://demo.prometheus.com"))),
)
exec.BuildDashboard(builder, buildErr)
}
Build dashboards#
Anytime you want to build the final dashboard definition (i.e: Perses dashboard in JSON or YAML format) corresponding to your as-code definition, you can use the dac build
command, as the following:
If the build is successful, the result can be found in the generated built
folder.
Note
the -o
(alternatively '--output') flag is optional (the default output format is YAML).
Build multiple dashboards at once#
If you want to develop multiple dashboards as code, you should have 1 dashboard per file and then call the build command with the directory option:
Deploy dashboards#
Once you are satisfied with the result of your DaC definition for a given dashboard, you can finally deploy it to Perses with the apply
command:
CICD setup#
TODO