mirror of
https://github.com/prometheus-community/windows_exporter.git
synced 2026-10-21 03:59:04 +02:00
mixin: lint dashboards and migrate CI tasks to mise (#2608)
Signed-off-by: Jan-Otto Kröpke <mail@jkroepke.de>
This commit is contained in:
Jan-Otto Kröpke
@@ -0,0 +1,68 @@
|
||||
# Keep exceptions scoped to the existing sample dashboard and panels.
|
||||
exclusions:
|
||||
target-instance-rule:
|
||||
reason: Fleet panels intentionally span instances; per-host panels use an exact matcher for the single-select instance variable.
|
||||
entries:
|
||||
- dashboard: Windows Exporter
|
||||
template-instance-rule:
|
||||
reason: Per-host tabs require one instance, so the instance variable has neither multi-select nor an All value.
|
||||
entries:
|
||||
- dashboard: Windows Exporter
|
||||
template-job-rule:
|
||||
reason: Grafana expands All to the discovered job values rather than using a custom .+ wildcard.
|
||||
entries:
|
||||
- dashboard: Windows Exporter
|
||||
uneditable-dashboard:
|
||||
reason: This sample dashboard is editable so users can adapt it to their environment.
|
||||
entries:
|
||||
- dashboard: Windows Exporter
|
||||
panel-units-rule:
|
||||
reason: This table displays service names and states; the numeric query value is hidden.
|
||||
entries:
|
||||
- dashboard: Windows Exporter
|
||||
panel: Automatic services not running
|
||||
panel-title-description-rule:
|
||||
reason: These existing panels have titles but no descriptions; new panels must include both.
|
||||
entries:
|
||||
- dashboard: Windows Exporter
|
||||
panel: Operating system
|
||||
- dashboard: Windows Exporter
|
||||
panel: CPUs
|
||||
- dashboard: Windows Exporter
|
||||
panel: RAM
|
||||
- dashboard: Windows Exporter
|
||||
panel: CPU busy
|
||||
- dashboard: Windows Exporter
|
||||
panel: Memory used
|
||||
- dashboard: Windows Exporter
|
||||
panel: CPU utilization
|
||||
- dashboard: Windows Exporter
|
||||
panel: Volumes
|
||||
- dashboard: Windows Exporter
|
||||
panel: Context switches and interrupts
|
||||
- dashboard: Windows Exporter
|
||||
panel: Processes and threads
|
||||
- dashboard: Windows Exporter
|
||||
panel: System calls and exceptions
|
||||
- dashboard: Windows Exporter
|
||||
panel: Volume usage
|
||||
- dashboard: Windows Exporter
|
||||
panel: Network errors and discards
|
||||
- dashboard: Windows Exporter
|
||||
panel: Running services
|
||||
- dashboard: Windows Exporter
|
||||
panel: Disabled services
|
||||
- dashboard: Windows Exporter
|
||||
panel: VMs in critical health
|
||||
- dashboard: Windows Exporter
|
||||
panel: Logical processors
|
||||
- dashboard: Windows Exporter
|
||||
panel: Virtual switch dropped packets
|
||||
- dashboard: Windows Exporter
|
||||
panel: Clock sync source
|
||||
- dashboard: Windows Exporter
|
||||
panel: Clock offset and NTP round-trip delay
|
||||
- dashboard: Windows Exporter
|
||||
panel: Samples per scrape
|
||||
- dashboard: Windows Exporter
|
||||
panel: Collectors
|
||||
@@ -1,81 +0,0 @@
|
||||
JSONNET ?= jsonnet
|
||||
JSONNETFMT ?= jsonnetfmt
|
||||
JB ?= jb
|
||||
PROMTOOL ?= promtool
|
||||
PINT ?= pint
|
||||
PYTHON ?= python3
|
||||
|
||||
# renovate: go=github.com/google/go-jsonnet
|
||||
JSONNET_VERSION := v0.22.0
|
||||
# renovate: go=github.com/jsonnet-bundler/jsonnet-bundler
|
||||
JB_VERSION := v0.6.0
|
||||
# renovate: go=github.com/cloudflare/pint
|
||||
PINT_VERSION := v0.89.2
|
||||
SOURCES := $(wildcard *.libsonnet *.jsonnet lib/*.libsonnet rules/*.libsonnet alerts/*.libsonnet dashboards/*.libsonnet tests/*.libsonnet tests/*.jsonnet)
|
||||
FMT_FLAGS := -n 2 --max-blank-lines 2 --string-style s --comment-style s
|
||||
DASHBOARD := ../../dashboard/windows-exporter-dashboard.json
|
||||
|
||||
.DEFAULT_GOAL := generate
|
||||
.DELETE_ON_ERROR:
|
||||
.PHONY: generate rules dashboard dashboards check-dashboards tools jsonnet-tools fmt lint test check-runbooks clean
|
||||
|
||||
generate: rules dashboard
|
||||
|
||||
rules: windows_rules.yaml windows_alerts.yaml
|
||||
|
||||
tools: jsonnet-tools
|
||||
go install github.com/cloudflare/pint/cmd/pint@$(PINT_VERSION)
|
||||
|
||||
jsonnet-tools:
|
||||
go install github.com/google/go-jsonnet/cmd/jsonnet@$(JSONNET_VERSION)
|
||||
go install github.com/google/go-jsonnet/cmd/jsonnetfmt@$(JSONNET_VERSION)
|
||||
go install github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb@$(JB_VERSION)
|
||||
|
||||
# Only the dashboard needs the Jsonnet libraries (grafonnet).
|
||||
vendor: jsonnetfile.json jsonnetfile.lock.json
|
||||
$(JB) install
|
||||
@touch $@
|
||||
|
||||
windows_rules.yaml: $(SOURCES)
|
||||
$(JSONNET) -S rules.jsonnet > $@
|
||||
|
||||
windows_alerts.yaml: $(SOURCES)
|
||||
$(JSONNET) -S alerts.jsonnet > $@
|
||||
|
||||
tests/custom_rules.yaml: $(SOURCES)
|
||||
$(JSONNET) -S -e 'std.manifestYamlDoc((import "tests/config.libsonnet").prometheusRules)' > $@
|
||||
|
||||
tests/custom_alerts.yaml: $(SOURCES)
|
||||
$(JSONNET) -S -e 'std.manifestYamlDoc((import "tests/config.libsonnet").prometheusAlerts)' > $@
|
||||
|
||||
dashboard: vendor
|
||||
$(JSONNET) -J vendor -S dashboard.jsonnet > $(DASHBOARD).tmp
|
||||
mv $(DASHBOARD).tmp $(DASHBOARD)
|
||||
|
||||
dashboards: dashboard
|
||||
|
||||
check-dashboards: dashboard
|
||||
git diff --exit-code -- $(DASHBOARD)
|
||||
|
||||
fmt:
|
||||
$(JSONNETFMT) $(FMT_FLAGS) -i $(SOURCES)
|
||||
|
||||
lint: rules tests/custom_rules.yaml tests/custom_alerts.yaml vendor
|
||||
@set -e; for file in $(SOURCES); do \
|
||||
$(JSONNETFMT) $(FMT_FLAGS) "$$file" | diff -u "$$file" -; \
|
||||
done
|
||||
@$(JSONNET) -J vendor -S dashboard.jsonnet | diff -u $(DASHBOARD) - \
|
||||
|| { echo "$(DASHBOARD) is out of date; run make dashboard"; exit 1; }
|
||||
$(PROMTOOL) check rules windows_rules.yaml windows_alerts.yaml tests/custom_rules.yaml tests/custom_alerts.yaml
|
||||
$(PINT) --offline lint windows_rules.yaml windows_alerts.yaml
|
||||
$(PINT) --offline lint tests/custom_rules.yaml tests/custom_alerts.yaml
|
||||
|
||||
check-runbooks:
|
||||
$(JSONNET) -e '(import "mixin.libsonnet") { _config+:: { enableActiveDirectory: true, enableTime: true } }.prometheusAlerts' | $(PYTHON) tests/check_runbooks.py ../../docs/runbooks
|
||||
|
||||
test: lint check-runbooks
|
||||
$(JSONNET) tests/runbooks.test.jsonnet
|
||||
$(PROMTOOL) test rules tests/*.test.yaml
|
||||
|
||||
clean:
|
||||
rm -f windows_rules.yaml windows_alerts.yaml tests/custom_rules.yaml tests/custom_alerts.yaml
|
||||
+32
-20
@@ -6,16 +6,22 @@ source of the sample dashboard. The source uses Jsonnet and exposes the standard
|
||||
|
||||
## Generate rules
|
||||
|
||||
Install the pinned Jsonnet, [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler)
|
||||
and [pint](https://github.com/cloudflare/pint) tools:
|
||||
Install [mise](https://mise.jdx.dev/) and Go, then install the pinned Jsonnet,
|
||||
[jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler),
|
||||
[pint](https://github.com/cloudflare/pint),
|
||||
[dashboard-linter](https://github.com/grafana/dashboard-linter), and Prometheus
|
||||
tools from `mise.toml`. Tasks use a POSIX shell; on Windows, run them in WSL.
|
||||
|
||||
```sh
|
||||
cd contrib/mixin
|
||||
make tools
|
||||
export PATH="$(go env GOPATH)/bin:$PATH"
|
||||
make rules
|
||||
mise trust
|
||||
mise install
|
||||
mise run rules
|
||||
```
|
||||
|
||||
Mise installs release binaries with checksum verification and builds Jsonnet
|
||||
Bundler using Go. `mise run` makes the pinned tools available automatically.
|
||||
|
||||
Only the dashboard depends on Jsonnet libraries, so `jb install` is not required
|
||||
to generate rules. Generated rule files are ignored by Git:
|
||||
|
||||
@@ -233,50 +239,56 @@ b.panel.new(200, 'CPU usage', 'timeseries')
|
||||
Regenerate the committed file after changing the dashboard source:
|
||||
|
||||
```sh
|
||||
make dashboard
|
||||
mise run dashboard
|
||||
```
|
||||
|
||||
This runs `jb install` and writes `../../dashboard/windows-exporter-dashboard.json`.
|
||||
`make dashboards` is an alias. `make generate` builds both the rules and the
|
||||
dashboard, while `make rules` builds only the rules. The same commands work
|
||||
inside WSL with the Go tool binaries on `PATH`.
|
||||
`mise run dashboards` is an alias. `mise run generate` builds both the rules and the
|
||||
dashboard, while `mise run rules` builds only the rules. The same commands work
|
||||
inside WSL; mise supplies the tool binaries on `PATH`.
|
||||
|
||||
The checked-in JSON remains the reference for the rendered dashboard, including
|
||||
queries, IDs, variables, annotations, transformations, and tab/row layout.
|
||||
`make check-dashboards` regenerates it and runs `git diff --exit-code`, displaying
|
||||
`mise run check-dashboards` regenerates it and runs `git diff --exit-code`, displaying
|
||||
any drift. CI runs that check before the mixin tests. The dashboard uses its own
|
||||
variables and does not read `_config`.
|
||||
|
||||
## Validate
|
||||
|
||||
Install Python 3 and `promtool` from a [Prometheus release](https://github.com/prometheus/prometheus/releases),
|
||||
then run:
|
||||
Install Python 3, run `mise install`, then run:
|
||||
|
||||
```sh
|
||||
make test
|
||||
mise run test
|
||||
```
|
||||
|
||||
This checks Jsonnet formatting, checks that the committed dashboard is up to
|
||||
date, validates generated rules with `promtool`, runs
|
||||
`pint --offline lint`, and evaluates the rules against synthetic time series.
|
||||
date, runs `dashboard-linter lint --strict`, validates generated rules with
|
||||
`promtool`, runs `pint --offline lint`, and evaluates the rules against synthetic
|
||||
time series.
|
||||
Tests cover all 25 recordings, alert timing and recovery, threshold
|
||||
boundaries, counter resets, zero denominators, disk forecasts, target-label
|
||||
preservation, and custom selectors/thresholds with Active Directory and clock
|
||||
alerts enabled. Runbook checks include opt-in alerts and verify that their pages
|
||||
and URLs exist. CI uses Prometheus 3.15.0 and the same pinned tool versions as
|
||||
`make tools`.
|
||||
`mise install`.
|
||||
|
||||
If you prefer to run `promtool` through Docker:
|
||||
To list the available tasks:
|
||||
|
||||
```sh
|
||||
make test PROMTOOL="docker run --rm --entrypoint promtool -v \"$PWD:/mixin:ro\" -w /mixin prom/prometheus:v3.15.0"
|
||||
mise tasks ls
|
||||
```
|
||||
|
||||
The dedicated `Mixin` workflow runs on changes to `contrib/mixin/**`, the
|
||||
committed dashboard JSON or its own workflow file, and can also be started
|
||||
manually. It caches pinned tool binaries and runs the same `make test` checks
|
||||
manually. It caches pinned tool binaries and runs the same `mise run test` checks
|
||||
used locally.
|
||||
|
||||
Run `mise run lint-dashboards` to lint just the committed dashboard. `.dashboard-lint.yaml`
|
||||
documents exceptions for the sample dashboard's single-host selection, fleet
|
||||
queries, editable state, and existing panels without descriptions or numeric
|
||||
units. Other findings fail validation, including warnings. Remove panel
|
||||
exceptions when adding the missing descriptions.
|
||||
|
||||
`.pint.hcl` requires a non-empty severity label, summary/description annotations,
|
||||
and an HTTP(S) runbook URL on alerts, in addition to pint's built-in checks.
|
||||
CI uses offline mode without a Prometheus endpoint. To validate metric
|
||||
@@ -293,7 +305,7 @@ Then run `pint --config /path/to/local.pint.hcl lint windows_rules.yaml windows_
|
||||
without `--offline`. See the [pint documentation](https://cloudflare.github.io/pint/)
|
||||
for available checks.
|
||||
|
||||
Run `make fmt` after source changes and `make clean` to remove generated rule
|
||||
Run `mise run fmt` after source changes and `mise run clean` to remove generated rule
|
||||
files. For downstream composition with Jsonnet Bundler, import
|
||||
`github.com/prometheus-community/windows_exporter/contrib/mixin/mixin.libsonnet`
|
||||
and extend `_config`. See the [monitoring mixin documentation](https://github.com/monitoring-mixins/docs)
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
[tools]
|
||||
"github:google/go-jsonnet" = "0.22.0"
|
||||
"go:github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb" = "0.6.0"
|
||||
"github:cloudflare/pint" = "0.89.2"
|
||||
"github:grafana/dashboard-linter" = "0.3.0"
|
||||
"github:prometheus/prometheus" = "3.15.0"
|
||||
|
||||
[vars]
|
||||
sources = "*.libsonnet *.jsonnet lib/*.libsonnet rules/*.libsonnet alerts/*.libsonnet dashboards/*.libsonnet tests/*.libsonnet tests/*.jsonnet"
|
||||
fmt_flags = "-n 2 --max-blank-lines 2 --string-style s --comment-style s"
|
||||
dashboard = "../../dashboard/windows-exporter-dashboard.json"
|
||||
|
||||
[tasks.generate]
|
||||
description = "Generate Prometheus rules, alerts, and the dashboard"
|
||||
alias = "default"
|
||||
depends = ["rules", "dashboard"]
|
||||
|
||||
[tasks.rules]
|
||||
description = "Generate Prometheus rules and alerts"
|
||||
run = [
|
||||
"jsonnet -S rules.jsonnet > windows_rules.yaml",
|
||||
"jsonnet -S alerts.jsonnet > windows_alerts.yaml",
|
||||
]
|
||||
|
||||
[tasks.vendor]
|
||||
description = "Install dashboard Jsonnet libraries"
|
||||
run = "jb install"
|
||||
|
||||
[tasks.dashboard]
|
||||
description = "Regenerate the committed Grafana dashboard"
|
||||
alias = "dashboards"
|
||||
depends = ["vendor"]
|
||||
run = '''
|
||||
set -eu
|
||||
trap 'rm -f {{vars.dashboard}}.tmp' EXIT
|
||||
jsonnet -J vendor -S dashboard.jsonnet > {{vars.dashboard}}.tmp
|
||||
mv {{vars.dashboard}}.tmp {{vars.dashboard}}
|
||||
'''
|
||||
|
||||
[tasks.check-dashboards]
|
||||
description = "Regenerate the dashboard and fail on uncommitted changes"
|
||||
depends = ["dashboard"]
|
||||
run = "git diff --exit-code -- {{vars.dashboard}}"
|
||||
|
||||
[tasks.lint-dashboards]
|
||||
description = "Lint the committed dashboard in strict mode"
|
||||
run = "dashboard-linter lint --strict --config .dashboard-lint.yaml {{vars.dashboard}}"
|
||||
|
||||
[tasks.fmt]
|
||||
description = "Format all mixin Jsonnet sources"
|
||||
run = "jsonnetfmt {{vars.fmt_flags}} -i {{vars.sources}}"
|
||||
|
||||
[tasks.custom-rules]
|
||||
description = "Generate rules and alerts with the test configuration"
|
||||
hide = true
|
||||
run = [
|
||||
'''jsonnet -S -e 'std.manifestYamlDoc((import "tests/config.libsonnet").prometheusRules)' > tests/custom_rules.yaml''',
|
||||
'''jsonnet -S -e 'std.manifestYamlDoc((import "tests/config.libsonnet").prometheusAlerts)' > tests/custom_alerts.yaml''',
|
||||
]
|
||||
|
||||
[tasks.lint]
|
||||
description = "Check Jsonnet formatting, dashboard drift, and Prometheus rules"
|
||||
depends = ["rules", "custom-rules", "vendor", "lint-dashboards"]
|
||||
run = '''
|
||||
set -eu
|
||||
for file in {{vars.sources}}; do
|
||||
jsonnetfmt {{vars.fmt_flags}} "$file" | diff -u "$file" -
|
||||
done
|
||||
jsonnet -J vendor -S dashboard.jsonnet | diff -u {{vars.dashboard}} - \
|
||||
|| { echo "{{vars.dashboard}} is out of date; run mise run dashboard"; exit 1; }
|
||||
promtool check rules windows_rules.yaml windows_alerts.yaml tests/custom_rules.yaml tests/custom_alerts.yaml
|
||||
pint --offline lint windows_rules.yaml windows_alerts.yaml
|
||||
pint --offline lint tests/custom_rules.yaml tests/custom_alerts.yaml
|
||||
'''
|
||||
|
||||
[tasks.check-runbooks]
|
||||
description = "Check runbook coverage for all alerts, including opt-in alerts"
|
||||
run = '''jsonnet -e '(import "mixin.libsonnet") { _config+:: { enableActiveDirectory: true, enableTime: true } }.prometheusAlerts' | python3 tests/check_runbooks.py ../../docs/runbooks'''
|
||||
|
||||
[tasks.test]
|
||||
description = "Run all mixin lint, runbook, and rule tests"
|
||||
depends = ["lint", "check-runbooks"]
|
||||
run = [
|
||||
"jsonnet tests/runbooks.test.jsonnet",
|
||||
"promtool test rules tests/*.test.yaml",
|
||||
]
|
||||
|
||||
[tasks.clean]
|
||||
description = "Remove generated rule and alert files"
|
||||
run = "rm -f windows_rules.yaml windows_alerts.yaml tests/custom_rules.yaml tests/custom_alerts.yaml"
|
||||
Reference in New Issue
Block a user