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.53.0-beta.0 and onwards.

• Prometheus Overview
• Prometheus Remote Write

• Nodes
• Cluster USE Method

• AlertManager Overview

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

• 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 Overview

• Blackbox Exporter Overview

• Perses Overview

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

• OpenTelemetry Collector

• Thanos
• Blackbox Exporter

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.

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.

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" \
  --node-exporter-job=node-exporter

All available job label flags (defaults match the standard community conventions):

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.

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

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

make build-rules

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.

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.

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:

# 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

You can find some recomendation for dashboard design here