docs(example,contributing): add README skeleton, ruff formatter, and coding conventions

Author: markuslf

.pre-commit-config.yaml

@@ -23,6 +23,13 @@ repos:
       - id: 'end-of-file-fixer'
       - id: 'trailing-whitespace'
 
+  - repo: 'https://github.com/astral-sh/ruff-pre-commit'
+    rev: 'v0.15.9'
+    hooks:
+      - id: 'ruff-check'
+        args: ['--fix']
+      - id: 'ruff-format'
+
   - repo: 'https://github.com/pylint-dev/pylint'
     rev: 'v4.0.5'
     hooks:

CHANGELOG.md

@@ -14,13 +14,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+* Add ruff linter and formatter to pre-commit hooks, enforce single-quote style
 * CONTRIBUTING: add "no continuous counters" policy with rationale and link to example plugin ([#320](https://github.com/Linuxfabrik/monitoring-plugins/issues/320))
 * CONTRIBUTING: add early reference to example plugin as skeleton for new plugins
 * CONTRIBUTING: add Grafana migration note for grafanactl ([#1062](https://github.com/Linuxfabrik/monitoring-plugins/issues/1062))
+* CONTRIBUTING: add PEP 8 string quoting convention (single quotes, `"""` for triple-quoted)
+* CONTRIBUTING: add README structure guidelines with fixed section order, Fact Sheet template, and Nagios/Icinga check name for SEO
 * CONTRIBUTING: rewrite unit-test section with declarative test pattern, naming conventions, and tox usage
 * CONTRIBUTING: run pylint without `--disable` flags
 * CONTRIBUTING: remove inline `pylint: disable` comments from code examples
 * example: rewrite as comprehensive skeleton covering all standard patterns (argparse, SQLite delta calculations, regex filtering, `--lengthy` table output, human-readable formatting, get_state/get_worst, Grafana-compatible perfdata)
+* example: rewrite README as skeleton template with Overview, Fact Sheet, States, Perfdata, and Troubleshooting sections
 * Update and extend pre-commit hooks (add `check-added-large-files`, `check-merge-conflict`, `check-yaml`; update all hook versions)
 * Unify CONTRIBUTING and enhance it with the official Monitoring Plugins and Nagios Plugin Development Guidelines
 

CONTRIBUTING.md

@@ -585,6 +585,8 @@ A monitoring plugin has to calculate such values always on its own. If this is n
 
 We use [PEP 8 -- Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/) where it makes sense.
 
+**String quoting:** Use single quotes as the default. Use double quotes only inside f-string expressions (e.g. `f'{lib.base.state2str(state, prefix=" ")}'`) or when the string itself contains single quotes (e.g. `'Python module "psutil" is not installed.'`). Use `"""` for all triple-quoted strings (docstrings, `DESCRIPTION`, SQL, etc.). This is enforced by `ruff format`.
+
 
 ### Docstrings
 
@@ -830,6 +832,43 @@ If you want to create a Service Set, edit `assets/icingaweb2-module-director/all
 If you want to move a service from one Service Set to another, you have to create a new UUID for the new service (this isn't even possible in the Icinga Director GUI).
 
 
+### README Structure
+
+Each plugin README follows a fixed structure. See [check-plugins/example/README.md](check-plugins/example/README.md) for the reference template. The sections are:
+
+1. **Overview**: Describes *what* the plugin does. A leading sentence stating the main purpose. This must include at least the text from the plugin's `DESCRIPTION` variable. Followed by subsections:
+
+    * **Data Collection**: How data is gathered (shell command, API, psutil, etc.), filtering options, SQLite usage, non-blocking measurement.
+    * **Compatibility**: Supported platforms, required tools or modules.
+    * **Important Notes** (optional): Operational edge cases the admin must know before deploying, for example: "Requires sudo", "Only works with Redis 3.0+", "First run returns OK with 'Waiting for more data.'", "After a reboot, counters reset and the check waits for a new baseline". No implementation details - only things that affect deployment and daily operations.
+
+2. **Fact Sheet**: Key properties as a table (download link, check name, check interval, parameters required, Windows support, 3rd party modules, state file path, etc.). Only list applicable rows.
+
+    | Fact | Value |
+    |----|----|
+    | Check Plugin Download                 | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/example> |
+    | Nagios/Icinga Check Name              | `check_example` (for SEO: helps admins find the plugin when searching for the traditional Nagios-style name) |
+    | Check Interval Recommendation         | Every minute, Every 5/15/30 minutes, Every hour, Every 4/8/12 hours, Every day, Every week |
+    | Can be called without parameters      | Yes/No |
+    | Compiled for Windows                  | Yes (when `.windows` file exists)/No (runs with Python interpreter) |
+    | Requirements                          | command-line tool `foo`; User with higher permissions |
+    | 3rd Party Python modules              | `module-name` |
+    | Handles Periods                       | Yes (alerts only after `--count` consecutive threshold violations) |
+    | Uses State File                       | `$TEMP/linuxfabrik-monitoring-plugins-<plugin-name>.db` |
+
+3. **Help**: The full `--help` output in a code block. Regenerate via `tools/update-readmes`.
+
+4. **Usage Examples**: One or more realistic invocations with their output. Show at least one OK case. If the plugin has `--lengthy`, show both variants.
+
+5. **States**: Describes *when* the plugin returns which state. Be precise about OK, WARN, CRIT, UNKNOWN conditions (e.g. "WARN if the percentage value is >= `--warning`"). Include `--always-ok` behavior, consecutive-run requirements, and first-run/reboot edge cases.
+
+6. **Perfdata / Metrics**: Table with columns Name, Type, Description. Types: `Bytes`, `Number`, `Percentage`, `Seconds`. Where possible, use the metric descriptions from the vendor's official documentation (e.g. Redis INFO, psutil docs, API references).
+
+7. **Troubleshooting** (optional): Known error messages with their solutions. Format: error message in backticks on its own line, followed by two trailing spaces for a Markdown line break, solution on the next line. Separate entries with a blank line.
+
+8. **Credits, License**: Always present.
+
+
 ### Grafana Dashboards
 
 The title of the dashboard should be capitalized, the name has to match the folder/plugin name (spaces will be replaced with `-`, `/` will be ignored. eg `Network I/O` will become `network-io`). Each Grafana panel should be meaningful, especially when comparing it to other related panels (eg memory usage and CPU usage).

check-plugins/cpu-usage/README.md

@@ -16,6 +16,7 @@ Monitors system-wide CPU utilization with sustained load detection to avoid fals
 * System-wide aggregate CPU statistics (not per-core)
 * Non-blocking measurement using SQLite state persistence between runs
 * Platform-specific extended metrics where available (context switches, interrupts, soft interrupts)
+
 **Compatibility:**
 
 * Cross-platform: Linux, Windows, and all psutil-supported systems

check-plugins/example/README.md

@@ -2,50 +2,45 @@
 
 ## Overview
 
-Help text from check command.
+Skeleton plugin demonstrating all standard patterns and library functions: argparse with append/deprecated/suppress parameters, (success, result) error handling, SQLite delta calculations (no continuous counters), regex filtering, `--lengthy` table output, human-readable formatting (bytes, seconds, numbers), perfdata, get_state/get_worst, and Grafana-compatible panel design. Use this as a template for new check plugins.
 
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+**Data Collection:**
 
-Hints:
+* Executes a shell command (`cat /etc/os-release` as a placeholder) to collect data
+* Items can be filtered by `--name` (exact match) and excluded by `--ignore-regex` (Python regular expression)
+* Uses SQLite state persistence between runs to calculate deltas (e.g. bytes per second)
+* On the first run, returns "Waiting for more data." until at least two measurements are available
+* After a system reboot, counter values may be lower than the previous measurement. The check detects this (negative delta) and returns "Waiting for more data." until the next valid measurement pair
 
-* Might be useful.
-* Could help.
+**Compatibility:**
 
+* Cross-platform: Linux, Windows, and all psutil-supported systems
 
 ## Fact Sheet
 
 | Fact | Value |
 |----|----|
 | Check Plugin Download                 | <https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/example> |
-| Check Interval Recommendation         | Once a minute |
-| Can be called without parameters      | Yes\|No |
-| Compiled for Windows                  | Yes\|No |
-| Requirements                          | command-line tool `foo`; User with higher permissions |
+| Nagios/Icinga Check Name              | `check_example` |
+| Check Interval Recommendation         | Every minute |
+| Can be called without parameters      | No (`--token` is required) |
+| Compiled for Windows                  | No (runs with Python interpreter) |
 | 3rd Party Python modules              | `psutil` |
-| Handles Periods                       | Yes |
-| Uses SQLite DBs                       | `$TEMP/linuxfabrik-monitoring-plugins-example.db` |
-| Perfdata compatible with Prometheus   | Yes |
-
-Hints for the Author (delete those):
-
-* Check Interval Recommendation: other texts are "Every 15 minutes", "Once a day" etc.
-* Available for: delete inappropriate ones
-* Requirements: delete if none
-* Handles Periods: delete if not
-* Uses SQLite DBs: delete if not
-* Perfdata compatible with Prometheus: delete if not
+| Uses State File                       | `$TEMP/linuxfabrik-monitoring-plugins-example.db` |
 
 
 ## Help
 
 ```text
 usage: example [-h] [-V] [--always-ok] [-c CRIT] [--ignore-regex IGNORE_REGEX]
-               [--module MODULE] [--name NAME] [--test TEST] --token TOKEN
-               [-w WARN]
+               [--lengthy] [--module MODULE] [--name NAME] [--test TEST]
+               [--timeout TIMEOUT] --token TOKEN [-w WARN]
 
-A working Linuxfabrik monitoring plugin, written in Python 3, as a basis for
-further development, and much more text to help admins get this check up and
-running.
+Skeleton plugin demonstrating all standard patterns and library functions:
+argparse with append/deprecated/suppress parameters, (success, result) error
+handling, SQLite delta calculations (no continuous counters), regex filtering,
+--lengthy table output, human-readable formatting (bytes, seconds, numbers),
+perfdata, get_state/get_worst, and Grafana-compatible panel design.
 
 options:
   -h, --help            show this help message and exit
@@ -56,12 +51,14 @@ options:
                         Any english title matching this python regex will be
                         ignored (repeating). Example: '(?i)linuxfabrik' for a
                         case-insensitive search for "linuxfabrik".
+  --lengthy             Extended reporting.
   --module MODULE       "modulename" to check (startswith), for example
                         `--module json --module mbstring` (repeating)
   --name NAME           Only check items with this name (repeating). If not
                         specified, all items are checked.
   --test TEST           For unit tests. Needs "path-to-stdout-file,path-to-
                         stderr-file,expected-retc".
+  --timeout TIMEOUT     Network timeout in seconds. Default: 8 (seconds)
   --token TOKEN         Software API token
   -w, --warning WARN    Set the WARN threshold as a percentage. Default: >= 80
 ```
@@ -70,48 +67,64 @@ options:
 ## Usage Examples
 
 ```bash
-./example --warning 80 --critical 90 --count 5
+./example --token=mytoken --warning=80 --critical=90
 ```
 
-Output:
+Output (first run):
 
 ```text
-Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
-tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
-quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
-consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
-cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
-proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+Waiting for more data.
 ```
 
+Output (subsequent runs):
 
-## States
+```text
+42% used, up 1D 10h, since 2026-04-09 06:30:44, 1.0GiB/s, 42K items
 
-* Always returns OK.
-* WARN or CRIT if any condition.
+Title       ! Value
+------------+------
+Lorem ipsum ! 42%
+```
 
+With `--lengthy`:
 
-## Perfdata / Metrics
+```text
+42% used, up 1D 10h, since 2026-04-09 06:30:44, 1.0GiB/s, 42K items
 
-There is no perfdata.
+Title       ! Type  ! Value
+------------+-------+------
+Lorem ipsum ! Lorem ! 42%
+```
 
-OR
+
+## States
+
+* OK if the percentage value is below the warning threshold.
+* OK with "Waiting for more data." on the first run or after a reboot.
+* WARN if the percentage value is >= `--warning` (default: 80).
+* CRIT if the percentage value is >= `--critical` (default: 90).
+* UNKNOWN on missing Python modules, invalid `--ignore-regex` patterns, or invalid command-line arguments.
+* `--always-ok` suppresses all alerts and always returns OK.
+
+
+## Perfdata / Metrics
 
 | Name | Type | Description |
 |----|----|----|
-| allocation_btree_compares_total | Continous Counter | Number of allocation B-tree compares for a filesystem. |
-| allocation_btree_lookups_total | Bytes | Number of allocation B-tree lookups for a filesystem. |
-| allocation_btree_lookups_total | Percentage | Number of allocation B-tree lookups for a filesystem. |
-| allocation_btree_lookups_total | None | Number of allocation B-tree lookups for a filesystem. |
+| cpu-usage | Percentage | The measured percentage value. |
+| rx-bytes-per-second | Bytes | Received bytes per second, calculated as delta between two consecutive check runs. |
 
 
 ## Troubleshooting
 
-My Error Message 1  
-My Solution goes here.
+`Python module "psutil" is not installed.`  
+Install `psutil`: `pip install psutil` or `dnf install python3-psutil`.
+
+`Waiting for more data.`  
+This is expected on the first run. The check needs at least two measurements to calculate a delta. Wait for the next check interval.
 
-My Error Message 2  
-My Solution goes here.
+`Unable to compile regex.`  
+The pattern passed via `--ignore-regex` is not a valid Python regular expression. Check the syntax at <https://docs.python.org/3/library/re.html>.
 
 
 ## Credits, License