doc: add documentation for check_output_matches

README.md

@@ -35,9 +35,9 @@ supports the following command-line flags:
 
 ### DNS zone serials
 
-  The `check_zone_serial` plugin can be used to check that the version of a
+The `check_zone_serial` plugin can be used to check that the version of a
-  zone served by a DNS is up-to-date compared to the same zone served by
+zone served by a DNS is up-to-date compared to the same zone served by
-  another, "reference" DNS. It supports the following command-line flags:
+another, "reference" DNS. It supports the following command-line flags:
 
 * `-H name`/`--hostname name`: the host name or address of the server to
   check.
@@ -49,6 +49,48 @@ supports the following command-line flags:
 * `-p port`/`--rs-port port`: the port to use on the reference server
   (defaults to 53).
 
+### Generic text match counter
+
+The `check_output_matches` plugin can be used to count occurrences of strings
+in a program's output or in a text file, and compute its final status based on
+that.
+
+It supports the following general command line flags:
+
+* `-f` / `--is-file` indicates that the plugin will be reading from a text file
+  instead of running another program;
+* `-s` / `--source` is either the name of the file to read, or the command to
+  execute. The command may include multiple arguments separated by single
+  spaces; it does not support any form of quoting.
+* `-T` / `--timeout` can set a timeout for the command. It is disabled by
+  default.
+* `-S` / `--strict` determines how unmatched lines are handled. By default they
+  are ignored, but setting this flag will cause the plugin to enter `CRITICAL`
+  mode if unmatched lines are found.
+
+Other flags are available in order to configure the matches. The main flag is
+`-m` / `--match`, which adds a new match string to the set of checks to run.
+The checks are influenced by the following additional flags, which apply to all
+subsequent matches.
+
+* `-r` / `--regexp` indicates that new matches will be based on regular
+  expressions instead of substrings.
+* `-R` / `--no-regexp` switches back to substring-based matches.
+* `-w` / `--warn` can be used to set a warning range. It must be followed by
+  a Nagios range specification.
+* `-W` / `--no-warn` clears the warning range.
+* `-c` / `--critical` can be used to set the critical range. It must be followed
+  by a Nagios range specification.
+* `-C` / `--no-critical` clears the critical range.
+
+For example, the command below:
+
+    gomonop check_output_matches -s 'find /some/place' \
+       -w 4 -r -m '^.*\.warn$' \
+       -W -c 0 -R -m fatal
+
+configures a warning if more than 4 files ending in `.warn` are found, and a
+critical state if any file with `fatal` in its name is found.
 
 Building from source
 --------------------