feat: dynamic matcher+template checks

Makefile

@@ -14,7 +14,7 @@ intermediate-docs:
 	@go run ./main.go -h > ./docs/_intermediate/help.txt
 	@go run ./main.go completion -h > ./docs/_intermediate/completion.txt
 	@go run ./main.go lint -h > ./docs/_intermediate/lint.txt
-	@go run ./main.go rules > ./docs/_intermediate/rules.txt
+	@go run ./main.go rules --experimental > ./docs/_intermediate/rules.txt
 	@echo "Can't automate everything, please replace the #Rules section of index.md with the contents of ./docs/_intermediate/rules.txt"
 
 embedmd:

docs/index.md

@@ -52,8 +52,10 @@ Usage:
 
 Flags:
   -c, --config string   path to a configuration file
+      --experimental    enable experimental rules
       --fix             automatically fix problems if possible
   -h, --help            help for lint
+      --stdin           read from stdin
       --strict          fail upon linting error or warning
       --verbose         show more information about linting
 ```
@@ -62,20 +64,32 @@ Flags:
 
 The linter implements the following rules:
 
-* [template-datasource-rule](./rules/template-datasource-rule.md) - Checks that the dashboard has a templated datasource.
-* [template-job-rule](./rules/template-job-rule.md) - Checks that the dashboard has a templated job.
-* [template-instance-rule](./rules/template-instance-rule.md) - Checks that the dashboard has a templated instance.
-* [template-label-promql-rule](./rules/template-label-promql-rule.md) - Checks that the dashboard templated labels have proper PromQL expressions.
-* [template-on-time-change-reload-rule](./rules/template-on-time-change-reload-rule.md) - Checks that the dashboard template variables are configured to reload on time change.
-* [panel-datasource-rule](./rules/panel-datasource-rule.md) - Checks that each panel uses the templated datasource.
-* [panel-title-description-rule](./rules/panel-title-description-rule.md) - Checks that each panel has a title and description.
-* [panel-units-rule](./rules/panel-units-rule.md) - Checks that each panel uses has valid units defined.
-* `panel-no-targets-rule` - Checks that each panel has at least one target.
-* [target-promql-rule](./rules/target-promql-rule.md) - Checks that each target uses a valid PromQL query.
-* [target-rate-interval-rule](./rules/target-rate-interval-rule.md) - Checks that each target uses $__rate_interval.
-* [target-job-rule](./rules/target-job-rule.md) - Checks that every PromQL query has a job matcher.
-* [target-instance-rule](./rules/target-instance-rule.md) - Checks that every PromQL query has a instance matcher.
-* `target-counter-agg-rule` - Checks that any counter metric (ending in _total) is aggregated with rate, irate, or increase.
+* [template-datasource-rule](./rules/template-datasource-rule) - ``stable`` - Checks that the dashboard has a templated datasource.
+* [template-job-rule](./rules/template-job-rule) - `stable` - Checks that the dashboard has a templated job.
+* [template-instance-rule](./rules/template-instance-rule) - `stable` - Checks that the dashboard has a templated instance.
+* [template-label-promql-rule](./rules/template-label-promql-rule) - `stable` - Checks that the dashboard templated labels have proper PromQL expressions.
+* [template-on-time-change-reload-rule](./rules/template-on-time-change-reload-rule) - `stable` - Checks that the dashboard template variables are configured to reload on time change.
+* [panel-datasource-rule](./rules/panel-datasource-rule) - `stable` - Checks that each panel uses the templated datasource.
+* [panel-title-description-rule](./rules/panel-title-description-rule) - `stable` - Checks that each panel has a title and description.
+* [panel-units-rule](./rules/panel-units-rule) - `stable` - Checks that each panel uses has valid units defined.
+* [panel-no-targets-rule](./rules/panel-no-targets-rule) - `stable` - Checks that each panel has at least one target.
+* [target-promql-rule](./rules/target-promql-rule) - `stable` - Checks that each target uses a valid PromQL query.
+* [target-rate-interval-rule](./rules/target-rate-interval-rule) - `stable` - Checks that each target uses $__rate_interval.
+* [target-job-rule](./rules/target-job-rule) - `stable` - Checks that every PromQL query has a job matcher.
+* [target-instance-rule](./rules/target-instance-rule) - `stable` - Checks that every PromQL query has a instance matcher.
+* [target-counter-agg-rule](./rules/target-counter-agg-rule) - `stable` - Checks that any counter metric (ending in _total) is aggregated with rate, irate, or increase.
+* [uneditable-dashboard-rule](./rules/uneditable-dashboard-rule) - `stable` - Checks that the dashboard is not editable.
+* [target-required-matchers-rule](./rules/target-required-matchers-rule) - `experimental` - Checks that target PromQL query has the required matchers
+* [template-required-variables-rule](./rules/template-required-variables-rule) - `experimental` - Checks that the dashboard has a template variable for required variables or matchers that use variables
+
+## Rule stability
+- **Stable** rules have gone through testing and been widely adopted.
+
+- **Experimental** rules are for new and experimental features.
+  These rules are not enabled by default, but can be enabled by providing the `experimental` flag.
+  Allowing early adopters to gain confidence with new features.
+
+- **Deprecated** rules may be removed or replaced when they are marked as deprecated.
 
 ## Related Rules
 

docs/rules/target-required-matchers-rule.md

@@ -0,0 +1,20 @@
+# target-required-matchers-rule
+Checks that each PromQL query has a the matchers specified in rule settings. This rule is experimental and is designed to work with Prometheus datasources.
+
+## Rule Settings
+
+```yaml
+settings:
+  target-required-matchers-rule:
+    matchers:
+      - cluster=~"$cluster"
+      - someLabel="someValue"
+```
+Legacy config example for job and instance
+```yaml
+settings:
+  target-required-matchers-rule:
+    matchers:
+      - job
+      - instance
+```

docs/rules/template-required-variables-rule.md

@@ -0,0 +1,31 @@
+# template-required-variables-rule
+Checks that each dashboard has a templated variable based on provided rule settings and detected variable usage for the target-required-matchers-rule.
+
+# Best Practice
+The rule ensures all of the following conditions.
+
+* The dashboard template exists.
+* The dashboard template is named `xxx`.
+* The dashboard template is labeled `xxx`.
+* The dashboard template uses a templated datasource, specifically named `$datasource`.
+* The dashboard template uses a Prometheus query to find available matching instances.
+* The dashboard template is multi select
+* The dashboard template has an allValue of `.+`
+
+## Rule Settings
+
+```yaml
+settings:
+  template-required-variables-rule:
+    variables:
+      - cluster
+      - namespace
+```
+Legacy config example for job and instance
+```yaml
+settings:
+  template-required-variables-rule:
+    variables:
+      - job
+      - instance
+```

go.mod

@@ -1,11 +1,11 @@
 module github.com/grafana/dashboard-linter
 
-go 1.21
+go 1.21.0
 
-toolchain go1.22.1
+toolchain go1.22.5
 
 require (
-	github.com/prometheus/prometheus v0.53.1
+	github.com/prometheus/prometheus v0.54.1
 	github.com/spf13/cobra v1.8.1
 	github.com/spf13/viper v1.19.0
 	github.com/stretchr/testify v1.9.0
@@ -15,12 +15,21 @@ require (
 )
 
 require (
-	cloud.google.com/go v0.114.0 // indirect
-	cloud.google.com/go/auth v0.5.1 // indirect
+	github.com/aws/aws-sdk-go v1.54.19 // indirect
+	github.com/jmespath/go-jmespath v0.4.0 // indirect
+	github.com/jpillora/backoff v1.0.0 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f // indirect
+	github.com/prometheus/common/sigv4 v0.1.0 // indirect
+)
+
+require (
+	cloud.google.com/go v0.115.0 // indirect
+	cloud.google.com/go/auth v0.7.0 // indirect
 	cloud.google.com/go/auth/oauth2adapt v0.2.2 // indirect
-	cloud.google.com/go/compute/metadata v0.3.0 // indirect
-	cloud.google.com/go/iam v1.1.8 // indirect
-	cloud.google.com/go/storage v1.40.0 // indirect
+	cloud.google.com/go/compute/metadata v0.4.0 // indirect
+	cloud.google.com/go/iam v1.1.10 // indirect
+	cloud.google.com/go/storage v1.41.0 // indirect
 	github.com/BurntSushi/toml v1.3.2 // indirect
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
@@ -31,25 +40,26 @@ require (
 	github.com/ghodss/yaml v1.0.0 // indirect
 	github.com/go-kit/log v0.2.1 // indirect
 	github.com/go-logfmt/logfmt v0.6.0 // indirect
-	github.com/go-logr/logr v1.4.1 // indirect
+	github.com/go-logr/logr v1.4.2 // indirect
 	github.com/go-logr/stdr v1.2.2 // indirect
 	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
 	github.com/golang/protobuf v1.5.4 // indirect
 	github.com/google/s2a-go v0.1.7 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/googleapis/enterprise-certificate-proxy v0.3.2 // indirect
-	github.com/googleapis/gax-go/v2 v2.12.4 // indirect
+	github.com/googleapis/gax-go/v2 v2.12.5 // indirect
 	github.com/grafana/regexp v0.0.0-20240518133315-a468a5bfb3bc // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/prometheus/alertmanager v0.27.0
 	github.com/prometheus/client_golang v1.19.1 // indirect
 	github.com/prometheus/client_model v0.6.1 // indirect
-	github.com/prometheus/common v0.54.0 // indirect
-	github.com/prometheus/procfs v0.13.0 // indirect
+	github.com/prometheus/common v0.55.0
+	github.com/prometheus/procfs v0.15.1 // indirect
 	github.com/sagikazarmark/locafero v0.4.0 // indirect
 	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
@@ -62,25 +72,25 @@ require (
 	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
 	go.opencensus.io v0.24.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.49.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.52.0 // indirect
-	go.opentelemetry.io/otel v1.27.0 // indirect
-	go.opentelemetry.io/otel/metric v1.27.0 // indirect
-	go.opentelemetry.io/otel/trace v1.27.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.53.0 // indirect
+	go.opentelemetry.io/otel v1.28.0 // indirect
+	go.opentelemetry.io/otel/metric v1.28.0 // indirect
+	go.opentelemetry.io/otel/trace v1.28.0 // indirect
 	go.uber.org/atomic v1.11.0 // indirect
 	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/crypto v0.24.0 // indirect
+	golang.org/x/crypto v0.25.0 // indirect
 	golang.org/x/exp v0.0.0-20240404231335-c0f41cb1a7a0 // indirect
-	golang.org/x/net v0.26.0 // indirect
+	golang.org/x/net v0.27.0 // indirect
 	golang.org/x/oauth2 v0.21.0 // indirect
 	golang.org/x/sync v0.8.0 // indirect
-	golang.org/x/sys v0.21.0 // indirect
+	golang.org/x/sys v0.22.0 // indirect
 	golang.org/x/time v0.5.0 // indirect
-	google.golang.org/api v0.183.0 // indirect
-	google.golang.org/genproto v0.0.0-20240528184218-531527333157 // indirect
-	google.golang.org/genproto/googleapis/api v0.0.0-20240528184218-531527333157 // indirect
-	google.golang.org/genproto/googleapis/rpc v0.0.0-20240528184218-531527333157 // indirect
-	google.golang.org/grpc v1.64.0 // indirect
-	google.golang.org/protobuf v1.34.1 // indirect
+	google.golang.org/api v0.188.0 // indirect
+	google.golang.org/genproto v0.0.0-20240708141625-4ad9e859172b // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20240711142825-46eb208f015d // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20240708141625-4ad9e859172b // indirect
+	google.golang.org/grpc v1.65.0 // indirect
+	google.golang.org/protobuf v1.34.2 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 )