How to declare new probes

README

@@ -370,3 +370,79 @@ than 98%, the "buzzer" alert will make some bad noises in the room to
 warn me about this.
 
 Note : escalation is an alias for the **or** function.
+
+
+Extend with your own probes
+===========================
+
+It is likely that you want to write your own probes. While using the
+command probe can be convenient, you may want to have a probe with
+more parameters and better integration than the command probe.
+
+There are two methods for adding probes :
+- in the configuration file before using it
+- in a separated lisp file that you load from the configuration file
+
+If you want to reuse for multiples configuration files or servers, I
+would recommend a separate file, otherwise, adding it at the top of
+the configuration file can be convenient too.
+
+
+Using a shell command
+---------------------
+
+A minimum of Common LISP comprehension is needed for this. But using
+the easiest way to go by writing a probe using a command shell, the
+declaration can be really simple.
+
+We are going to write a probe that will use curl to fetch an page and
+then grep on the output to look for a pattern. The return code of grep
+will be the return status of the probe, if grep finds the pattern,
+it's a success, if not it's a failure.
+
+In the following code, the "create-probe" part is a macro that will
+write most of the code for you. Then, we use "command-return-code"
+function which will execute the shell command passed as a string (or
+as a list) and return the correct values in case of success or
+failure.
+
+    (create-probe
+     check-http-pattern
+     (command-return-code (format nil "curl ~a | grep -i ~a"
+                                  (getf params :url) (getf params :pattern))))
+
+If you don't know LISP, "format" function works like "printf", using
+"~a" instead of "%s". This is the only required thing to know if you
+want to reuse the previous code.
+
+Then we can call it like this :
+
+    (=> notifier check-http-pattern :url "http://127.0.0.1" :pattern "Powered by cl-yag")
+
+
+Using plain LISP
+----------------
+
+We have seen previously how tocreate new probes from a shell command,
+but one may want to do it in LISP, allowing to use full features of
+the language and even some libraries to check values in a database for
+example. I recommend to read the "probes.lisp" file, it's the best way
+to learn how to write a new probe. But as an example, we will learn
+from the easiest probe included : file-exists
+
+    (create-probe
+     file-exists
+     (let ((result (probe-file (getf params :path))))
+       (if result
+           t
+           (list nil "file not found"))))
+
+Like before, we use the "create-probe" macro and give a name to the
+probe. Then, we have to write some code, in the current case, check if
+the file exists. Finally, if it is a success, we have to return **t**,
+if it fails we return a list containing **nil** and a value or a
+string. The second element in the list will replaced %result% in the
+notification command, so you can use something explicit, a
+concatenation of a message with the return value etc..". Parameters
+should be get with getf from **params** variable, allowing to use a
+default value in case it's not defined in the configuration file.