Perses Community Mixins

Welcome to the Perses Community Mixins repository! This project is designed to provide Prometheus mixins tailored for the Perses platform. Developed with the Perses Go SDK, these dashboards are modular, reusable, and simple to integrate into various observability setups.

This repo also offers Prometheus Operator format recording rules and alerts alongside these dashboards, also maintained in Go as a complete mixin solution!

Note: These dashboards are compatible with Perses version v0.54.0 and onwards.

Overview of Available Dashboards

Prometheus Dashboards

• Prometheus Overview
• Prometheus Remote Write

Node Exporter Dashboards

• Nodes
• Cluster USE Method

AlertManager Dashboards

• AlertManager Overview

Thanos Dashboards

• Receive Overview
• Query Overview
• Query Frontend Overview
• Store Gateway Overview
• Compact Overview
• Ruler Overview

Kubernetes-mixin Dashboards

• API Server
• Compute Resources / Multi-Cluster
• Compute Resources / Cluster
• Compute Resources / Node
• Compute Resources / Namespace (Pods)
• Compute Resources / Namespace (Workloads)
• Compute Resources / Workloads
• Compute Resources / Pod
• Networking / Cluster
• Networking / Namespace (Pods)
• Networking / Namespace (Workload)
• Networking / Pod
• Networking / Workload
• Persistent Volume
• Kubelet
• Controller Manager
• Scheduler
• Proxy

etcd-mixin Dashboards

• etcd Overview

Blackbox Exporter

• Blackbox Exporter Overview

Perses

• Perses Overview

Istio

• Istio Control Plane Dashboard
• Istio Mesh Dashboard
• Istio Performance Dashboard
• Istio Service Dashboard
• Istio Workload Dashboard
• Istio Ztunnel Dashboard
• Istio Wasm Extension Dashboard

Tempo Dashboards

• Tempo / Writes
• Tempo / Tenant

OpenShift Dashboards

• OCP Audit Log Viewer (requires a Loki datasource; built when --loki-datasource is set)

OpenTelemetry Collector Dashboards

• OpenTelemetry Collector

Overview of Available PrometheusRules

• Thanos
• Thanos Operator
• Alertmanager
• Blackbox Exporter

Library Panels

In addition to the Community Mixins, this repository also offers a library of reusable panels. These panels can be used as building blocks for custom dashboard creation, enabling you to craft tailored setups to suit specific observability needs.

Rendering Dashboards

To render and generate the dashboards, run the following command:

make build-dashboards

The generated dashboard files will be stored as YAML files in the examples/dashboards/ directory by default and split by component (both in native Perses and Perses Operator format). You can then import these files into your Perses instances.

For local testing and CI (make build-dashboards-local), dashboards are written to built/dashboards/ instead.

Customizing Job Labels

Some dashboards use hardcoded job label values in PromQL queries (e.g., job="node" for Node Exporter). If your monitoring stack uses different job names (e.g., kube-prometheus-stack uses job="node-exporter"), you can override them with CLI flags:

go run main.go \
  --output-dir="./examples/dashboards/perses" \
  --output="yaml" \
  --project="default" \
  --datasource="prometheus-datasource" \
  --loki-datasource="loki-datasource" \
  --node-exporter-job=node-exporter

All available CLI flags:

Flag	Default	Description
--datasource	(empty)	Prometheus datasource name
--loki-datasource	(empty)	Loki datasource name; enables OCP Audit Log Viewer
--project	default	Perses project name
--cluster-label-name	(empty)	Cluster label name for multi-cluster variables
--node-exporter-job	node	Node Exporter dashboard queries
--apiserver-job	kube-apiserver	Kubernetes API server
--kubelet-job	kubelet	Kubelet
--kube-state-metrics-job	kube-state-metrics	kube-state-metrics
--cadvisor-job	cadvisor	cAdvisor
--node-exporter-k8s-job	node-exporter	Node Exporter in Kubernetes dashboards
--controller-manager-job	kube-controller-manager	Kube Controller Manager
--scheduler-job	kube-scheduler	Kube Scheduler
--kube-proxy-job	kube-proxy	Kube Proxy

Note: Dashboards for Prometheus, Thanos, Alertmanager, Perses, Blackbox, OpenTelemetry, and etcd already use a $job runtime variable, so users can select the job value directly in the Perses UI without needing a CLI flag.

Library Usage

When using this repository as a Go library, you can configure job labels programmatically by calling the exported setter functions before building dashboards:

import (
	nodeexporter "github.com/perses/community-mixins/pkg/panels/node_exporter"
	k8s "github.com/perses/community-mixins/pkg/panels/kubernetes"
	nodeexporterdash "github.com/perses/community-mixins/pkg/dashboards/node_exporter"
)

func main() {
	// Configure job labels before building dashboards
	nodeexporter.SetNodeExporterLabelValue("node-exporter")
	k8s.SetAPIServerLabelValue("my-apiserver")
	k8s.SetKubeletLabelValue("my-kubelet")

	// Build dashboards with the configured values
	result := nodeexporterdash.BuildNodeExporterNodes("myproject", "myds", "cluster")
	dashboard := result.Builder().Dashboard
	// ...
}

The full list of available setters can be found in:

• pkg/panels/node_exporter/globals.go — SetNodeExporterLabelValue
• pkg/panels/kubernetes/globals.go — SetAPIServerLabelValue, SetKubeletLabelValue, SetNodeExporterLabelValue, SetControllerManagerLabelValue, SetCAdvisorLabelValue, SetSchedulerLabelValue, SetKubeProxyLabelValue, SetKubeStateMetricsLabelValue

Rendering PrometheusRules

To render and generate the PrometheusRule objects, run the following command:

make build-rules

Local Development Guide

For local development, you can quickly spin up a Perses environment with the following command:

make start-demo

This command initializes a local Perses instance that includes predefined resources such as Projects and DataSources. Once the instance is running, you can access the Perses UI at http://localhost:8080.

Applying Dashboards with percli

You can use percli to apply the dashboards to your Perses instance. Use the percli tool with the following commands:

# Connect to your perses instance, for example if you want to use the demo perses
percli login http://localhost:8080/

# Add the dashboards to your instance (component-wise)
percli apply -d examples/dashboards/perses/prometheus/

# Add all the dashboards to your instance
find ./examples/dashboards/perses -type d -mindepth 1 -exec percli apply -d {} \;

This will deploy the dashboards from the examples/dashboards/perses directory to your local Perses instance.

Applying Dashboards with Perses Operator

Once you have installed Perses Operator, with a Perses instance and PersesDatasource object in your cluster (following the instructions here), you can apply the generated PersesDashboard objects using:

Minimum operator version: Generated dashboards under examples/dashboards/operator/ use apiVersion: perses.dev/v1alpha2 and require perses-operator v0.3.0 or later. Operator e2e tests in this repo validate against the version pinned in .github/env.

# Add the dashboard CRDs to Perses (component-wise)
kubectl apply -f examples/dashboards/operator/kubernetes/

# Add all the dashboard CRDs to Perses
kubectl apply -f examples/dashboards/operator/ -R

Dashboard Design Recommendations

You can find dashboard design recommendations here.

For background on the composable panel approach used in this repository, see Composable Dashboards — Lessons from building Perses Community Dashboards.

Testing

See TESTING.md.