mixin: move kubernetes to docs, dashboard and rendered rules to contrib

kubernetes/ moves to docs/kubernetes/, dashboard/ to contrib/dashboard/,
and the rendered Prometheus rules and alerts to contrib/monitoring/ with
a README that says how to use and regenerate them.

Signed-off-by: Jan-Otto Kröpke <mail@jkroepke.de>

.github/workflows/mixin.yml

@@ -6,7 +6,8 @@ on:
   pull_request:
     paths:
       - contrib/mixin/**
-      - dashboard/*.json
+      - contrib/dashboard/*.json
+      - contrib/monitoring/*.yaml
       - docs/collector.*.md
       - docs/runbooks/**
       - docs/upgrade/**
@@ -21,7 +22,8 @@ on:
       - main
     paths:
       - contrib/mixin/**
-      - dashboard/*.json
+      - contrib/dashboard/*.json
+      - contrib/monitoring/*.yaml
       - docs/collector.*.md
       - docs/runbooks/**
       - docs/upgrade/**

AGENTS.md

@@ -27,9 +27,10 @@ their runtime behavior.
   and examples. [`docs/collector-template.md`](docs/collector-template.md) is the
   documentation template.
 - [`contrib/mixin`](contrib/mixin): Jsonnet recording rules, alerts and dashboard
-  sources. [`dashboard`](dashboard) contains the generated Grafana dashboards;
+  sources. [`contrib/dashboard`](contrib/dashboard) contains the generated Grafana
-  [`docs/runbooks`](docs/runbooks) documents the alerts.
+  dashboards, [`contrib/monitoring`](contrib/monitoring) the rendered Prometheus
-- [`installer`](installer), [`kubernetes`](kubernetes) and [`tools`](tools): MSI
+  rules and alerts; [`docs/runbooks`](docs/runbooks) documents the alerts.
+- [`installer`](installer), [`docs/kubernetes`](docs/kubernetes) and [`tools`](tools): MSI
   packaging, deployment examples, CI fixtures and end-to-end helpers. The CI
   package job validates installer changes with
   [`tools/test-installer.ps1`](tools/test-installer.ps1), which installs the
@@ -356,9 +357,9 @@ dashes, followed by its age in hex.
 ## Dashboards, rules and runbooks
 
 Read [`contrib/mixin/README.md`](contrib/mixin/README.md) and
-[`dashboard/README.md`](dashboard/README.md) before editing monitoring artifacts.
+[`contrib/dashboard/README.md`](contrib/dashboard/README.md) before editing monitoring artifacts.
 Edit the Jsonnet/Grafonnet source under `contrib/mixin/dashboards`, including its
-tab modules and shared builders, and regenerate `dashboard/windows-exporter-*.json`:
+tab modules and shared builders, and regenerate `contrib/dashboard/windows-exporter-*.json`:
 the full dashboard `windows-exporter-dashboard.json` and one dashboard per tab.
 Do not hand-edit generated JSON. Tab dashboards keep only the variables their
 panels reference, so reference variables as `$name` or `${name}`.

README.md

@@ -204,7 +204,7 @@ The Docker image is tagged with the version of the exporter. The `latest` tag is
 
 ## Kubernetes Implementation
 
-See detailed steps to install on Windows Kubernetes [here](./kubernetes/kubernetes.md).
+See detailed steps to install on Windows Kubernetes [here](./docs/kubernetes/kubernetes.md).
 
 ## Prometheus rules
 

contrib/dashboard/README.md

@@ -10,7 +10,7 @@ and takes several ideas from Grafana's [windows-observ-lib](https://github.com/g
 - Grafana 13 or later with a Prometheus data source. The file uses the v2 dashboard schema, which Grafana needs for tabs.
 - windows_exporter with the default collectors (`cpu`, `logical_disk`, `memory`, `net`, `os`, `physical_disk`, `service`, `system`).
   The SMB, Processes, Scheduled tasks, Updates, GPU, Hyper-V and Time tabs and the MSSQL dashboard, the TCP and UDP rows of the Network tab and the Drives and Storage Spaces rows of the Disk tab need the `smb` or `smbclient`, `process`, `scheduled_task`, `update`, `gpu`, `hyperv`, `time`, `mssql`, `tcp`, `udp`, `diskdrive` and `storage_spaces` collectors, which are not enabled by default.
-  The sample shows every tab; build the dashboard from the [mixin](../contrib/mixin#collectors) with your collectors to hide the others.
+  The sample shows every tab; build the dashboard from the [mixin](../mixin#collectors) with your collectors to hide the others.
   The process names in the GPU tab need the `process` collector.
   GPU temperature, fan, power and clock panels require WDDM 2.4 or newer and driver support; unsupported sensors are absent.
 
@@ -22,7 +22,7 @@ Import the JSON files through **Dashboards > New > Import** and pick the Prometh
 | Windows Exporter / `<tab>` | `windows-exporter-<tab>.json`, for example [windows-exporter-cpu.json](windows-exporter-cpu.json) | `windows-exporter-<tab>`, for example `windows-exporter-cpu` |
 | Windows Exporter / MSSQL | [windows-exporter-mssql.json](windows-exporter-mssql.json) | `windows-exporter-mssql` |
 
-The MSSQL dashboard is not a tab of the full dashboard. The [mixin](../contrib/mixin#metadata) adds it as a tab with `separateDashboardTabs: []`.
+The MSSQL dashboard is not a tab of the full dashboard. The [mixin](../mixin#metadata) adds it as a tab with `separateDashboardTabs: []`.
 
 The tab dashboards show only the variables their panels use.
 The **Windows Exporter** dropdown in the links of the tab dashboards opens the other imported dashboards and keeps the time range and variables.
@@ -82,11 +82,11 @@ appear. I/O graphs combine read, write and other operations per process.
 
 ### Changing the dashboard
 
-Don't edit the JSON files by hand. They are generated from Jsonnet with [grafonnet](https://github.com/grafana/grafonnet) as part of the [windows_exporter mixin](../contrib/mixin):
+Don't edit the JSON files by hand. They are generated from Jsonnet with [grafonnet](https://github.com/grafana/grafonnet) as part of the [windows_exporter mixin](../mixin):
 
-- [dashboards/windows-exporter.libsonnet](../contrib/mixin/dashboards/windows-exporter.libsonnet) composes the dashboards from one file per tab.
+- [dashboards/windows-exporter.libsonnet](../mixin/dashboards/windows-exporter.libsonnet) composes the dashboards from one file per tab.
-- [dashboards/builders.libsonnet](../contrib/mixin/dashboards/builders.libsonnet) holds the panel, query, and layout builders.
+- [dashboards/builders.libsonnet](../mixin/dashboards/builders.libsonnet) holds the panel, query, and layout builders.
-- [dashboards/styles.libsonnet](../contrib/mixin/dashboards/styles.libsonnet) shares the visualization defaults.
+- [dashboards/styles.libsonnet](../mixin/dashboards/styles.libsonnet) shares the visualization defaults.
 
 The generator writes the v2 schema directly, so it needs neither Grafana nor Prometheus.
 Install [mise](https://mise.jdx.dev/) and Go, then install the pinned tools and

contrib/mixin/AGENTS.md

@@ -59,7 +59,8 @@ A new alert touches six places, and CI checks all of them:
    a runbook mentions against the metrics the exporter emits; the names in
    the collector docs are not always current, so check the collector source.
 5. A row in the alerts table of `README.md`.
-6. The committed `windows_rules.yaml` and `windows_alerts.yaml`, regenerated
+6. The committed `contrib/monitoring/windows_rules.yaml` and
+   `windows_alerts.yaml`, regenerated
    with `mise run rules`; `mise run check-rules` fails in CI when they are
    stale.
 

contrib/mixin/README.md

@@ -24,7 +24,8 @@ 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. The rules rendered from the default configuration are
-committed next to the sources, so they can be used without Jsonnet:
+committed in [`contrib/monitoring`](../monitoring), so they can be used
+without Jsonnet:
 
 - `windows_rules.yaml`: recording rules.
 - `windows_alerts.yaml`: alerting rules.
@@ -310,10 +311,10 @@ Fork users should override `runbookURLPattern` to match their published URL.
 
 `grafanaDashboards` contains `windows-exporter.json`, the full sample dashboard
 with all tabs in
-[dashboard/windows-exporter-dashboard.json](../../dashboard/windows-exporter-dashboard.json),
+[contrib/dashboard/windows-exporter-dashboard.json](../dashboard/windows-exporter-dashboard.json),
 and a shorter dashboard per tab, such as `windows-exporter-cpu.json`, in
-[dashboard](../../dashboard). They are Grafana v2 dashboards and need Grafana 13
+[contrib/dashboard](../dashboard). They are Grafana v2 dashboards and need Grafana 13
-or later. See the [dashboard documentation](../../dashboard/README.md) for their
+or later. See the [dashboard documentation](../dashboard/README.md) for their
 content.
 
 The dashboard uses additive builders with [grafonnet](https://github.com/grafana/grafonnet),
@@ -360,7 +361,7 @@ Regenerate the committed files after changing the dashboard source:
 mise run dashboard
 ```
 
-This runs `jb install` and writes `../../dashboard/windows-exporter-*.json`.
+This runs `jb install` and writes `../dashboard/windows-exporter-*.json`.
 `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`.
@@ -510,7 +511,7 @@ prometheus "local" {
 }
 ```
 
-Then run `pint --config /path/to/local.pint.hcl lint windows_rules.yaml windows_alerts.yaml`
+Then run `pint --config /path/to/local.pint.hcl lint ../monitoring/windows_rules.yaml ../monitoring/windows_alerts.yaml`
 without `--offline`. See the [pint documentation](https://cloudflare.github.io/pint/)
 for available checks.
 

contrib/mixin/dashboard.jsonnet

@@ -1,4 +1,4 @@
-// Renders the sample dashboards into ../../dashboard. Run with
+// Renders the sample dashboards into ../dashboard. Run with
 // jsonnet -J vendor -S -m <directory>. The sample dashboards show every
 // collector; mixin users select theirs with _config.collectors.
 local manifest = import 'lib/manifest.libsonnet';

contrib/mixin/mise.toml

@@ -8,7 +8,8 @@
 [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"
-dashboards = "../../dashboard"
+dashboards = "../dashboard"
+rules = "../monitoring"
 
 [tasks.generate]
 description = "Generate Prometheus rules, alerts, and the dashboard"
@@ -16,10 +17,10 @@ alias = "default"
 depends = ["rules", "dashboard"]
 
 [tasks.rules]
-description = "Generate Prometheus rules and alerts"
+description = "Generate the Prometheus rules and alerts in contrib/monitoring"
 run = [
-  "jsonnet -S rules.jsonnet > windows_rules.yaml",
+  "jsonnet -S rules.jsonnet > {{vars.rules}}/windows_rules.yaml",
-  "jsonnet -S alerts.jsonnet > windows_alerts.yaml",
+  "jsonnet -S alerts.jsonnet > {{vars.rules}}/windows_alerts.yaml",
 ]
 
 [tasks.vendor]
@@ -40,12 +41,12 @@ cp "$out"/*.json {{vars.dashboards}}/
 '''
 
 [tasks.check-rules]
-description = "Regenerate the rules and alerts and fail on uncommitted changes"
+description = "Regenerate the rules and alerts in contrib/monitoring and fail on uncommitted changes"
 depends = ["rules"]
 run = '''
 set -eu
-git add --intent-to-add -- windows_rules.yaml windows_alerts.yaml
+git add --intent-to-add -- {{vars.rules}}/windows_rules.yaml {{vars.rules}}/windows_alerts.yaml
-git diff --exit-code -- windows_rules.yaml windows_alerts.yaml
+git diff --exit-code -- {{vars.rules}}
 '''
 
 [tasks.check-dashboards]
@@ -97,8 +98,8 @@ for file in $(cat "$out/generated"); do
   diff -u {{vars.dashboards}}/"$file" "$out/$file" \
     || { echo "{{vars.dashboards}}/$file is out of date; run mise run dashboard"; exit 1; }
 done
-promtool check rules windows_rules.yaml windows_alerts.yaml tests/custom_rules.yaml tests/custom_alerts.yaml ../../docs/upgrade/0.32.prom
+promtool check rules {{vars.rules}}/windows_rules.yaml {{vars.rules}}/windows_alerts.yaml tests/custom_rules.yaml tests/custom_alerts.yaml ../../docs/upgrade/0.32.prom
-pint --offline lint windows_rules.yaml windows_alerts.yaml
+pint --offline lint {{vars.rules}}/windows_rules.yaml {{vars.rules}}/windows_alerts.yaml
 pint --offline lint tests/custom_rules.yaml tests/custom_alerts.yaml
 '''
 

contrib/mixin/tests/alerts.test.yaml

@@ -1,6 +1,6 @@
 rule_files:
-  - ../windows_rules.yaml
+  - ../../monitoring/windows_rules.yaml
-  - ../windows_alerts.yaml
+  - ../../monitoring/windows_alerts.yaml
 evaluation_interval: 1m
 group_eval_order:
   - windows-exporter-recording

contrib/mixin/tests/resources.test.yaml

@@ -1,6 +1,6 @@
 rule_files:
-  - ../windows_rules.yaml
+  - ../../monitoring/windows_rules.yaml
-  - ../windows_alerts.yaml
+  - ../../monitoring/windows_alerts.yaml
 evaluation_interval: 1m
 group_eval_order:
   - windows-exporter-recording

contrib/mixin/tests/rules.test.yaml

@@ -1,5 +1,5 @@
 rule_files:
-  - ../windows_rules.yaml
+  - ../../monitoring/windows_rules.yaml
 evaluation_interval: 1m
 fuzzy_compare: true
 

contrib/monitoring/README.md

@@ -0,0 +1,25 @@
+# Prometheus rules for windows_exporter
+
+Ready-to-use Prometheus rule files, rendered from the
+[mixin](../mixin/README.md) with its default configuration:
+
+- [`windows_rules.yaml`](windows_rules.yaml): recording rules.
+- [`windows_alerts.yaml`](windows_alerts.yaml): alerting rules for the default
+  collectors.
+
+The alerts build on the recording rules, so load both files:
+
+```yaml
+rule_files:
+  - /etc/prometheus/rules/windows_rules.yaml
+  - /etc/prometheus/rules/windows_alerts.yaml
+```
+
+The files expect the exporter under the job name `windows_exporter`. For other
+job names, thresholds, selectors or the alerts of opt-in collectors, render
+the mixin with your own configuration as the
+[mixin README](../mixin/README.md#customize-or-compose) describes. Every alert links
+to its [runbook](https://prometheus-community.github.io/windows_exporter/runbooks/).
+
+Do not edit these files by hand: `mise run rules` in `contrib/mixin`
+regenerates them, and CI fails when they are out of date.

docs/kubernetes/kubernetes.md

@@ -30,7 +30,7 @@ Before beginning you need to deploy the [Prometheus Operator](https://github.com
 This creates a pod on every Windows node. A ConfigMap holds the configuration of the Windows exporter with [configuration file](../README.md#using-a-configuration-file).  Adjust the configuration file for the collectors you are interested in.
 
 ```bash
-kubectl apply -f kubernetes/windows-exporter-daemonset.yaml
+kubectl apply -f docs/kubernetes/windows-exporter-daemonset.yaml
 ```
 
 > Note: This example manifest deploys the latest bleeding edge image `ghcr.io/prometheus-community/windows-exporter:latest` built from the main branch.  You should update this to use a released version which you can find at https://github.com/prometheus-community/windows_exporter/releases
@@ -58,7 +58,7 @@ spec:
 Create the [Pod Monitor](https://prometheus-operator.dev/docs/operator/design/#podmonitor) to configure the scraping:
 
 ```bash
-kubectl apply -f kubernetes/windows-exporter-podmonitor.yaml
+kubectl apply -f docs/kubernetes/windows-exporter-podmonitor.yaml
 ```
 
 ### View Metrics

docs/upgrade/0.32.md

@@ -339,7 +339,7 @@ The exporter's own metrics now also include Go scheduler metrics (`go_sched_*`),
 
 ### Dashboard and alerts
 
-- The sample dashboard in [`dashboard/`](../../dashboard/README.md) was rebuilt as one dashboard with tabs. It uses the Grafana v2 dashboard schema and requires **Grafana 13 or later**. Import the new JSON file; the 0.31 dashboard can't be updated in place.
+- The sample dashboard in [`contrib/dashboard/`](../../contrib/dashboard/README.md) was rebuilt as one dashboard with tabs. It uses the Grafana v2 dashboard schema and requires **Grafana 13 or later**. Import the new JSON file; the 0.31 dashboard can't be updated in place.
 - New: [`contrib/mixin`](../../contrib/mixin) provides Prometheus recording rules and alerts for windows_exporter, with a runbook for each alert in [`docs/runbooks`](../runbooks).
 
 ### Installer
@@ -375,7 +375,7 @@ These changes affect Go programs that embed `github.com/prometheus-community/win
 ## Metric reference
 
 windows_exporter 0.32 follows the Prometheus naming conventions for every metric: values are in base units (seconds, bytes, hertz, ratios from 0 to 1), the unit is part of the name, and counters end in `_total`.
-**The old names are no longer exported, there are no aliases.** The sample dashboards in [`dashboard/`](../../dashboard/README.md) and the rules in [`contrib/mixin`](../../contrib/mixin) already use the new names.
+**The old names are no longer exported, there are no aliases.** The sample dashboards in [`contrib/dashboard/`](../../contrib/dashboard/README.md) and the rules in [`contrib/mixin`](../../contrib/mixin) already use the new names.
 The tables below are also the source of [`0.32.prom`](0.32.prom): a test generates the compatibility rules from the 0.31 and 0.32 columns and the notes.
 
 ### Unit changes