Skip to content

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. ⚠️ The version should be at least v0.54.0.
  • cue, the CLI of Cuelang. ⚠️ The version should be at least v0.15.0.

Repository setup#

Create a new folder that will become your DaC repository, then follow the steps below:

1. Initialize the CUE module#

You first have to initialize a CUE module in order to be able to import the SDK dependency afterwards:

cue mod init <module name>

See the CUE documentation for more information about this step.

2. Install the Perses SDK#

Now you can run the setup command that percli provides in order to install the SDK:

percli dac setup

Check the helper of that command to see the different flags available (e.g to define the SDK version to install).

Develop dashboards#

You are now fully ready to start developing dashboards as code with CUE!

You should first ramp up on CUE if you are not familiar with this technology.

Then you should have a look at the CUE SDK documentation to better understand how to use it.

For each plugin you would like to use in your DaC, it is strongly recommended to import its module so that you benefit from its schema validation locally. Optionally the plugin could also provide additional helpers (kind-of SDK additional piece) to help using it. Check the list of available plugins & their corresponding module name at https://github.com/perses/plugins.

Note

To resolve the dependencies added after the initial setup, use cue mod tidy.

You can have a look at the minimal example file has been generated by the setup command. For a richer DaC example, see below:

package mydac

import (
    dashboardBuilder "github.com/perses/perses/cue/dac-utils/dashboard"
    panelGroupsBuilder "github.com/perses/perses/cue/dac-utils/panelgroups"
    varGroupBuilder "github.com/perses/perses/cue/dac-utils/variable/group"
    labelValuesVarBuilder "github.com/perses/plugins/prometheus/sdk/cue/variable/labelvalues"
    panelBuilder "github.com/perses/plugins/prometheus/sdk/cue/panel"
    timeseriesChart "github.com/perses/plugins/timeserieschart/schemas:model"
    promQuery "github.com/perses/plugins/prometheus/schemas/prometheus-time-series-query:model"
    promDs "github.com/perses/plugins/prometheus/schemas/datasource:model"
)

dashboardBuilder & {
    #name:    "ContainersMonitoring"
    #project: "MyProject"

    #variables: {varGroupBuilder & {
        #input: [
            labelValuesVarBuilder & {
                #name: "stack"
                #display: name: "My Super PaaS"
                #metric:         "thanos_build_info"
                #label:          "paas"
                #datasourceName: "promDemo"
            },
        ]
    }}.variables

    #panelGroups: panelGroupsBuilder & {
        #input: [
            {
                #title: "Resource usage"
                #cols:  3
                #panels: [
                    panelBuilder & {
                        spec: {
                            display: name: "Container memory"
                            plugin: timeseriesChart
                            queries: [
                                {
                                    kind: "TimeSeriesQuery"
                                    spec: plugin: promQuery & {
                                        spec: query: "max by (container) (container_memory_rss{paas=\"$paas\",namespace=\"$namespace\",pod=\"$pod\",container=\"$container\"})"
                                    }
                                },
                            ]
                        }
                    },
                ]
            },
        ]
    }

    #datasources: promDemo: {
        default: true
        plugin: promDs & {
            spec: close({directUrl: "https://demo.prometheus.com"})
        }
    }
}

Getting started with the Go SDK#

Prerequisites#

Repository setup#

Create a new folder that will become your DaC repository, then follow the steps below:

1. Initialize the Go module#

You first have to initialize a Go module in order to be able to import the SDK dependency afterwards:

go mod init <module name>

See the Go documentation for more information about this step.

2. Install the Perses SDK#

Now you can run the setup command that percli provides in order to install the SDK:

percli dac setup --language go

Check the helper of that command to see the different flags available (e.g to define the SDK version to install).

Develop dashboards#

You are now fully ready to start developing dashboards as code with Go!

You should first ramp up on Go if you are not familiar with this technology.

Then you should have a look at the Go SDK documentation to better understand how to use the framework.

Warning

Do not log / print on the standard stdout! It would break the output of the dac build command.

For each plugin you would like to use in your DaC, you first have to check if it provides the corresponding piece of the Golang SDK* (it's always the case for official plugins). You will then have to import the corresponding dependency in order to be able to use it. Check the list of official plugins & their corresponding module name at https://github.com/perses/plugins.

Warning

*As already mentioned in the DaC introduction, outside official plugins, it is not guaranteed that all plugins would provide such piece of the Golang SDK. It's basically up to each plugin developer to provide a Go package to enable the DaC use case. This statement applies also to any other language we might have a SDK for in the future.

Note

To resolve the dependencies added after the initial setup, use either go mod tidy or go get ....

Note

On top of the Perses GO SDK, there is an SDK dedicated to build PromQL queries https://github.com/perses/promql-builder

You can have a look at the minimal example file has been generated by the setup command. For a richer DaC example, see below:

package main

import (
    "flag"

    "github.com/perses/perses/go-sdk"
    "github.com/perses/perses/go-sdk/dashboard"
    "github.com/perses/perses/go-sdk/panel"
    panelgroup "github.com/perses/perses/go-sdk/panel-group"
    listVar "github.com/perses/perses/go-sdk/variable/list-variable"
    promDs "github.com/perses/plugins/prometheus/sdk/go/datasource"
    "github.com/perses/plugins/prometheus/sdk/go/query"
    labelValuesVar "github.com/perses/plugins/prometheus/sdk/go/variable/label-values"
    timeSeriesPanel "github.com/perses/plugins/timeserieschart/sdk/go"
)

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:

percli dac build -f main.go -ojson
percli dac build -f my_dashboard.cue -ojson

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:

percli dac build -d my_dashboards

Development workflow with auto-reload#

For an improved development experience, instead of building the files each time manually with dac build, you can use the dac watch command that automatically rebuilds your dashboards whenever you save changes to your DaC files. This provides a workflow similar to frontend hot-reload development.

Basic watch mode#

Start watching your DaC files for changes:

# Watch current directory
percli dac watch

# Watch specific directory
percli dac watch ./my-dashboards

# Watch and output as JSON
percli dac watch ./my-dashboards -ojson

The watcher will: - Perform an initial build of all dashboards - Monitor all .go and .cue files in the source directory - Automatically rebuild when files are modified - Output results to the built folder (or custom location via --dac.output_folder)

Integrated development workflow#

To get a direct visual feedback of your changes when coding dashboards, you can run Perses with provisioning configured to watch your build directory:

Step 1: Create a Perses config file (perses-dev.yaml):

database:
  file:
    folder: /tmp/perses-dac-dev
    extension: yaml

provisioning:
  interval: 5s  # Check for changes every 5 seconds
  folders:
    - /absolute/path/to/your/built  # Your build output folder

security:
  enable_auth: false  # Disable auth for local development

Step 2: Start both processes:

# Terminal 1: Start Perses server with provisioning
perses --config perses-dev.yaml

# Terminal 2: At the root of your DaC repo, start the DaC watcher
percli dac watch

Step 3: Develop with instant feedback:

  1. Open http://localhost:8080 in your browser
  2. Navigate to your dashboards
  3. Edit your DaC files (.go or .cue)
  4. Watch the terminal show automatic rebuild
  5. Refresh your browser to see changes (provisioning picks them up within 5 seconds)

Tip

The provisioning interval of 5s provides a good balance between responsiveness and system load. You can adjust it based on your needs.

Tip

The watch command uses a 500ms debounce delay by default to avoid excessive rebuilds while you're actively editing. You can customize this with the --debounce flag.

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:

percli apply -f built/my_dashboard.json

CI/CD setup#

Setting up a CI/CD pipeline for your Dashboard-as-Code workflow is straightforward, as percli provides all the necessary commands to automate the process. You can integrate percli with any CI/CD technology of your choice: Jenkins, CircleCI, GitLab CI/CD, etc.

The key steps typically involve:

  • Building the dashboards using percli dac build to generate the final JSON/YAML definitions.
  • Validating the output to ensure correctness before deployment.
  • Deploying the dashboards to Perses with percli apply.

If you are using GitHub Actions, we provide a standard library that simplifies this integration. This includes:

  • A pre-configured workflow designed for common DaC CI/CD setups, making it easy to adopt without extensive configuration.

    Example of usage: 

    jobs:
  dac:
   uses: perses/cli-actions/.github/workflows/dac.yaml@v0.1.0
   with:
     url: https://demo.perses.dev
     directory: ./dac
     server-validation: true
   secrets:
     username: ${{ secrets.USR }}
     password: ${{ secrets.PWD }}

  • Independent actions for each CLI command, allowing you to build customized workflows.

    Example of usage: 

    steps:
  - name: Deploy the dashboards
    uses: perses/cli-actions/actions/apply_resources@v0.1.0
    with:
      directory: ./testdata/dashboards_folder

    The full list of actions is available here.

By leveraging these tools, you can ensure that your dashboards are automatically validated and deployed in a consistent and reliable manner.