docs/mixin: jsonnetify mixin to allow using common mixin tooling

Signed-off-by: Paweł Krupa (paulfantom) <pawel@krupa.net.pl>

.github/CODEOWNERS

@@ -19,5 +19,7 @@ go.sum @antekresic @paulfantom
 /pkg/tests/testdata/ @timescale/o11y-data-platform
 /pkg/tests/upgrade_tests/ @timescale/o11y-data-platform
 
+/docs/mixin @paulfantom 
+
 # helm and kubernetes related parts
 /deploy @cevian @paulfantom @JamesGuthrie

.github/workflows/mixin.yml

@@ -10,6 +10,10 @@ on:
 env:
   golang-version: 1.18.0
 
+defaults:
+  run:
+    working-directory: docs/mixin
+
 jobs:
   check-mixin:
     runs-on: ubuntu-latest
@@ -31,9 +35,13 @@ jobs:
       run: |
         make generate-helm --always-make
         git diff --exit-code
+      working-directory: .
+
+    - name: download mixtool
+      run: go install -a github.com/monitoring-mixins/mixtool/cmd/mixtool@latest
 
-    - name: download dashboard linter
-      run: go install -a github.com/grafana/dashboard-linter@latest
+    - name: download jsonnetfmt
+      run: go install -a github.com/google/go-jsonnet/cmd/jsonnetfmt@latest
 
     - name: download promtool
       run: |
@@ -43,10 +51,16 @@ jobs:
     - name: download gojsontoyaml
       run: go install github.com/brancz/gojsontoyaml@latest
 
-    - name: check alerts
+    - name: lint
+      run: make lint
+
+    - name: fmt
+      run: make fmt && git diff --exit-code
+
+    - name: build
+      run: make build
+
+    - name: test alerts
       run: |
         PATH="${PATH}:${GITHUB_WORKSPACE}"
-        make check-alerts
-
-    - name: check dashboards
-      run: make check-dashboards
+        make test

Makefile

@@ -50,22 +50,5 @@ generate-helm: deploy/helm-chart/templates/prometheus-rule.yaml
 deploy/helm-chart/templates/prometheus-rule.yaml:
 	./scripts/generate-helm-alerts.sh
 
-.PHONY: check-alerts
-check-alerts:
-	# If you don't have promtool, install it with
-	# go install -a github.com/prometheus/prometheus/cmd/promtool@latest
-	promtool check rules docs/mixin/alerts/alerts.yaml
-
-	# If you don't have gojsontoyaml, install it with
-	# go install -a github.com/brancz/gojsontoyaml@latest
-	gojsontoyaml -yamltojson < docs/mixin/alerts/alerts.yaml | jq -e '.groups[].rules[].annotations | has("runbook_url")' 
-
-
-.PHONY: check-dashboards
-check-dashboards:
-	# If you don't have promtool, install it with
-	# go install -a github.com/grafana/dashboard-linter@latest
-	find docs/mixin/dashboards -name '*.json' -print0 | xargs -n 1 -0 dashboard-linter lint
-
 .PHONY: all
 all: build test go-fmt go-lint

docs/mixin/.gitignore

@@ -0,0 +1,3 @@
+/alerts.yaml
+/rules.yaml
+dashboards_out/

docs/mixin/.lint

@@ -0,0 +1,4 @@
+# Those exclusions are needed due to usage of newer dashboard schema
+exclusions:
+  template-datasource-rule:
+  panel-datasource-rule:

docs/mixin/Makefile

@@ -0,0 +1,32 @@
+JSONNET_FMT := jsonnetfmt -n 2 --max-blank-lines 2 --string-style s --comment-style s
+
+default: build
+
+all: fmt lint build clean
+
+fmt:
+	find . -name 'vendor' -prune -o -name '*.libsonnet' -print -o -name '*.jsonnet' -print | \
+		xargs -n 1 -- $(JSONNET_FMT) -i
+
+lint:
+	find . -name 'vendor' -prune -o -name '*.libsonnet' -print -o -name '*.jsonnet' -print | \
+		while read f; do \
+			$(JSONNET_FMT) "$$f" | diff -u "$$f" -; \
+		done
+
+	mixtool lint mixin.libsonnet
+
+build:
+	mixtool generate all mixin.libsonnet
+
+clean:
+	rm -rf dashboards_out alerts.yaml rules.yaml
+
+test: build
+	# If you don't have promtool, install it with
+	# go install -a github.com/prometheus/prometheus/cmd/promtool@latest
+	promtool check rules alerts.yaml
+
+	# If you don't have gojsontoyaml, install it with
+	# go install -a github.com/brancz/gojsontoyaml@latest
+	gojsontoyaml -yamltojson < alerts/alerts.yaml | jq -e '.groups[].rules[].annotations | has("runbook_url")' 

docs/mixin/README.md

@@ -1,17 +1,38 @@
 # Promscale Mixin
 
-This file contains instructions on how to use Promscale mixins.
+_This is a work in progress. We aim for it to become a good role model for alerts and dashboards eventually, but it is not quite there yet._
+
+The Promscale Mixin is a set of configurable, reusable, and extensible alerts and dashboards based on the metrics exported by the Promscale. The mixin creates recording and alerting rules for Prometheus and suitable dashboard descriptions for Grafana.
 
 We recommend monitoring your Promscale deployments and include the mixins in this package
 as part of your alerting environment.
 
-## How to use
+## Using pre-built mixin
+
+### How to use
 Promscale alerts are defined [here](alerts/alerts.yaml). Copy the context into a file
 say `promscale_alerts.yaml`.
 
-## Configuring Prometheus
+### Configuring Prometheus
 In the Prometheus configuration file, add `promscale_alerts.yaml` under `rule_files` like
 ```yaml
 rule_files:
   - promscale_alerts.yaml
 ```
+
+## Building mixin
+
+To build it, you need to have mixtool and jsonnetfmt installed. If you have a working Go development environment, it's easiest to run the following:
+
+```console
+$ go install github.com/monitoring-mixins/mixtool/cmd/mixtool@latest
+$ go install github.com/google/go-jsonnet/cmd/jsonnetfmt@latest
+```
+
+You can then build the Prometheus rules files alerts.yaml and rules.yaml and a directory dashboard_out with the JSON dashboard files for Grafana:
+
+```
+$ make build
+```
+
+For more advanced uses of mixins, see https://github.com/monitoring-mixins/docs.

docs/mixin/alerts/alerts.libsonnet

@@ -0,0 +1,5 @@
+{
+  prometheusAlerts+:: {
+    groups+: std.parseYaml(importstr 'alerts.yaml').groups,
+  },
+}

docs/mixin/config.libsonnet

@@ -0,0 +1,4 @@
+{
+  // This is left to allow possible customization in the future
+  _config+:: {},
+}

docs/mixin/dashboards/dashboards.libsonnet

@@ -0,0 +1,10 @@
+{
+  grafanaDashboards+:: {
+    'apm-dependencies.json': (import 'apm-dependencies.json'),
+    'apm-home.json': (import 'apm-home.json'),
+    'apm-service-dependencies-downstream.json': (import 'apm-service-dependencies-downstream.json'),
+    'apm-service-dependencies-upstream.json': (import 'apm-service-dependencies-upstream.json'),
+    'apm-service-overview.json': (import 'apm-service-overview.json'),
+    'promscale.json': (import 'promscale.json'),
+  },
+}

docs/mixin/mixin.libsonnet

@@ -0,0 +1,3 @@
+(import 'alerts/alerts.libsonnet') +
+(import 'dashboards/dashboards.libsonnet') +
+(import 'config.libsonnet')