Official extra modules
A module is the code that does the work of one check or of one alert
destination of MMWatchdog. An official extra module is a module that the MMWatchdog
project writes, maintains, and tests, as a Starlark script. Starlark is a
small language that reads like Python. An official extra module is not built
into the mmwatchdog program: MMWatchdog runs the script when a check or an alert
destination names the module.
Official extra modules are for uncommon work and for alerts sent to a service operated by a single provider, such as Slack or Telegram.
The index of the module pages lists every official extra module, with what each one checks or where it delivers alerts.
Each module has a directory in official_extra_modules/, named for the tool
or the service:
official_extra_modules/
shipped_with_mmwatchdog_version one line: the version of the MMWatchdog release
slack/
module.star the script
module_description.yml the module's inputs, measurements, and examples
README.md the module's page: how to set it up, and what its messages mean
zfs_pool/
module.star
module_description.yml
README.md
An MMWatchdog release holds official_extra_modules/ beside the mmwatchdog
program, so a deployment project made from the release also holds
official_extra_modules/. Every deploy with the release's MMX workflows
installs the whole directory on every node, in
/usr/local/lib/mmwatchdog/official_extra_modules. The
Write your own check or destination has the steps.
To use a module, name it. A check or an alert destination names the module like any module of MMWatchdog, and writes the module's inputs below the name:
# /etc/mmwatchdog/alert_destinations.yml (on a standalone node or on the MMWatchdog fleet hub)
destinations:
team_chat:
remind_every: never
slack: # the official extra module for Slack
webhook_url_file: /etc/mmwatchdog/secrets/slack-webhook-team # an input of the module
alert_severities: [info, warn, sos]
There is no other step. MMWatchdog loads only the modules that the configuration of
a node names, so a module that nothing names is never read and never run.
On a node, mmwatchdog describe-module lists every module, and
mmwatchdog describe-module slack prints the page of one: the README.md in its
directory.
A module that delivers alerts needs nothing on a node but MMWatchdog. Most
modules that check a tool run the tool's own program on the node to obtain
the check result. So the node needs the tool's program, such as zpool for
zfs_pool. The apache_status module sends an HTTP request directly and
needs no separate program. The page of each module says what the module
needs.
Each module is named for the tool or service. When a module checks
something of a tool, the module's name also identifies what the module checks,
such as zfs_pool.
The modules and the mmwatchdog program belong to one release. The file
shipped_with_mmwatchdog_version holds the version of the MMWatchdog release
that supplies the official extra modules.
mmwatchdog compares the version in shipped_with_mmwatchdog_version with
the program's version and refuses to run when the two versions differ.
The error message names the modules' release version and the program's
version, such as the official extra modules in /usr/local/lib/mmwatchdog/official_extra_modules were shipped with MMWatchdog 1.0.0, and this mmwatchdog program is MMWatchdog 1.1.0. One MMWatchdog release holds both: deploy that release again. In the MMWatchdog repository, shipped_with_mmwatchdog_version says
dev, the version of a build that is no release.
Do not edit a module in official_extra_modules/, and do not copy an
official extra module into a project. The next MMWatchdog release brings
the module again.
For a module that works differently, write a module of your own under
another name, in the directory
mmwatchdog_external_modules/ of your deployment project. The
writing modules reference says how.
This page is official_extra_modules/README.md in the MMWatchdog repository.