Merge for #181

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

@@ -2,6 +2,24 @@
 All Commands:
 
 [embedmd]:# (_intermediate/help.txt)
+```txt
+A command-line application to lint Grafana dashboards.
+
+Usage:
+  dashboard-linter [flags]
+  dashboard-linter [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  help        Help about any command
+  lint        Lint a dashboard
+  rules       Print documentation about each lint rule.
+
+Flags:
+  -h, --help   help for dashboard-linter
+
+Use "dashboard-linter [command] --help" for more information about a command.
+```
 
 ```txt
 A command-line application to lint Grafana dashboards.
@@ -25,6 +43,24 @@ Use "dashboard-linter [command] --help" for more information about a command.
 ## Completion
 
 [embedmd]:# (_intermediate/completion.txt)
+```txt
+Generate the autocompletion script for dashboard-linter for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+Usage:
+  dashboard-linter completion [command]
+
+Available Commands:
+  bash        Generate the autocompletion script for bash
+  fish        Generate the autocompletion script for fish
+  powershell  Generate the autocompletion script for powershell
+  zsh         Generate the autocompletion script for zsh
+
+Flags:
+  -h, --help   help for completion
+
+Use "dashboard-linter completion [command] --help" for more information about a command.
+```
 
 ```txt
 Generate the autocompletion script for dashboard-linter for the specified shell.
@@ -48,6 +84,21 @@ Use "dashboard-linter completion [command] --help" for more information about a
 ## Lint
 
 [embedmd]:# (_intermediate/lint.txt)
+```txt
+Returns warnings or errors for dashboard which do not adhere to accepted standards
+
+Usage:
+  dashboard-linter lint [dashboard.json] [flags]
+
+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
+```
 
 ```txt
 Returns warnings or errors for dashboard which do not adhere to accepted standards
@@ -57,6 +108,7 @@ 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
@@ -68,23 +120,34 @@ 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-logql-rule](./rules/target-logql-rule.md) - Checks that each target uses a valid LogQL query.
-* [target-logql-auto-rule](./rules/target-logql-auto-rule.md) - Checks that each Loki target uses $__auto for range vectors when appropriate.
-* [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.
-* `uneditable-dashboard` - Checks that the dashboard is not editable.
+* [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-logql-rule](./rules/target-logql-rule) - `experimental` - Checks that each target uses a valid LogQL query.
+* [target-logql-auto-rule](./rules/target-logql-auto-rule) - `experimental` - Checks that each Loki target uses $__auto for range vectors when appropriate.
+* [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,10 @@
 module github.com/grafana/dashboard-linter
 
-go 1.21.8
-
-toolchain go1.23.1
+go 1.23.1
 
 require (
-	github.com/grafana/loki/v3 v3.2.0
+	github.com/grafana/grafana-foundation-sdk/go v0.0.0-20241106131137-6420b47bdc17
+	github.com/grafana/loki/v3 v3.2.1
 	github.com/prometheus/prometheus v0.54.1
 	github.com/spf13/cobra v1.8.1
 	github.com/spf13/viper v1.19.0
@@ -15,6 +14,27 @@ require (
 	gopkg.in/yaml.v3 v3.0.1
 )
 
+require (
+	github.com/aws/aws-sdk-go v1.54.19 // indirect
+	github.com/gorilla/mux v1.8.1 // indirect
+	github.com/grafana/dskit v0.0.0-20240905221822-931a021fb06b // indirect
+	github.com/grafana/gomemcache v0.0.0-20240229205252-cd6a66d6fb56 // indirect
+	github.com/grafana/jsonparser v0.0.0-20240425183733-ea80629e1a32 // indirect
+	github.com/grafana/loki/pkg/push v0.0.0-20231124142027-e52380921608 // indirect
+	github.com/grafana/pyroscope-go/godeltaprof v0.1.8 // 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
+	github.com/prometheus/exporter-toolkit v0.11.0 // indirect
+	go.opentelemetry.io/collector/pdata v1.12.0 // indirect
+	go.uber.org/zap v1.21.0 // indirect
+	go4.org/netipx v0.0.0-20230125063823-8449b0a6169f // indirect
+	golang.org/x/mod v0.19.0 // indirect
+	golang.org/x/tools v0.23.0 // indirect
+)
+
 require (
 	cloud.google.com/go v0.115.1 // indirect
 	cloud.google.com/go/auth v0.9.0 // indirect
@@ -61,13 +81,6 @@ require (
 	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.13.0 // indirect
-	github.com/gorilla/mux v1.8.1 // indirect
-	github.com/grafana/dskit v0.0.0-20240905221822-931a021fb06b // indirect
-	github.com/grafana/gomemcache v0.0.0-20240229205252-cd6a66d6fb56 // indirect
-	github.com/grafana/grafana-foundation-sdk/go v0.0.0-20241101005901-83e3491f2a70 // indirect
-	github.com/grafana/jsonparser v0.0.0-20240425183733-ea80629e1a32 // indirect
-	github.com/grafana/loki/pkg/push v0.0.0-20231124142027-e52380921608 // indirect
-	github.com/grafana/pyroscope-go/godeltaprof v0.1.8 // indirect
 	github.com/grafana/regexp v0.0.0-20240518133315-a468a5bfb3bc // indirect
 	github.com/hashicorp/consul/api v1.29.4 // indirect
 	github.com/hashicorp/errwrap v1.1.0 // indirect
@@ -85,7 +98,6 @@ require (
 	github.com/huandu/xstrings v1.3.3 // indirect
 	github.com/imdario/mergo v0.3.16 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/jpillora/backoff v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/klauspost/compress v1.17.9 // indirect
 	github.com/magiconair/properties v1.8.7 // indirect
@@ -98,19 +110,17 @@ require (
 	github.com/mitchellh/reflectwalk v1.0.1 // indirect
 	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
 	github.com/modern-go/reflect2 v1.0.2 // indirect
-	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
-	github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f // indirect
 	github.com/opentracing-contrib/go-grpc v0.0.0-20210225150812-73cb765af46e // indirect
 	github.com/opentracing-contrib/go-stdlib v1.0.0 // indirect
 	github.com/opentracing/opentracing-go v1.2.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
 	github.com/pires/go-proxyproto v0.7.0 // indirect
 	github.com/pkg/errors v0.9.1 // 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.55.0 // indirect
-	github.com/prometheus/exporter-toolkit v0.11.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
@@ -133,25 +143,20 @@ require (
 	go.etcd.io/etcd/client/pkg/v3 v3.5.12 // indirect
 	go.etcd.io/etcd/client/v3 v3.5.12 // indirect
 	go.opencensus.io v0.24.0 // indirect
-	go.opentelemetry.io/collector/pdata v1.12.0 // indirect
 	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.53.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
-	go.uber.org/zap v1.21.0 // indirect
-	go4.org/netipx v0.0.0-20230125063823-8449b0a6169f // indirect
 	golang.org/x/crypto v0.26.0 // indirect
 	golang.org/x/exp v0.0.0-20240404231335-c0f41cb1a7a0 // indirect
-	golang.org/x/mod v0.19.0 // indirect
 	golang.org/x/net v0.28.0 // indirect
 	golang.org/x/oauth2 v0.22.0 // indirect
 	golang.org/x/sync v0.8.0 // indirect
 	golang.org/x/sys v0.24.0 // indirect
 	golang.org/x/time v0.6.0 // indirect
-	golang.org/x/tools v0.23.0 // indirect
 	google.golang.org/api v0.193.0 // indirect
 	google.golang.org/genproto v0.0.0-20240820151423-278611b39280 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20240820151423-278611b39280 // indirect