Hudson is useful for monitoring the non-interactive execution of processes, such as cron jobs, procmail, inetd-launched processes. Often those tasks are completely unmonitored (which makes it hard for you to notice when things go wrong), or they send e-mails constantly regardless of the success or failure (which results into the same situation as you'll quickly start ignoring them anyway.) Using Hudson enables you to monitor large number of such tasks with little overhead.

Setting up a project

Create a new job and choose "monitoring an external job".

Monitoring an execution

Once you set up a project, you can monitor an execution by running a command like this:

$ export HUDSON_HOME=http://myserver.acme.org/path/to/hudson/
$ java -jar /path/to/hudson-core.jar "job name" <program arg1 arg2...>

The HUDSON_HOME variable is used to locate the server Hudson is running, so this must be set. You can copy hudson-core.jar to other machines if you want to monitor jobs that are run on a different machine. When you do that, you also need ant.jar for now.

stdout and stderr of the program will be recorded, and the non-0 exit code will be considered as a failure.

Monitoring cron jobs

To monitor a cron job, simply run the above set up from your cron script. To avoid receiving e-mails from cron daemon, you might want to write something like:

HUDSON_HOME=http://myserver.acme.org/path/to/hudson/
0 * * * *     export HUDSON_HOME=$HUDSON_HOME; java -jar hudson-core.jar "backup" backup.sh 2>&1 > /dev/null

Note that you can also move the cron job itself to Hudson by using free-style software project, which would also allow you to manually execute the job outside the scheduld executions.

Submit a run programatically

What hudson-core.jar really does is just execute the specified command and send its result to the server as XML over HTTP. The server accepts any submission as long as it follows the expected XML format. This allows you to write programs that send its result to Hudson, by following the same format.

The format is explained below:

<run>
  <log encoding='hexBinary'>...hex binary encoded console output...</log>
  <result>... integer indicating the error code. 0 is success and everything else is failure</result>
  <duration>... milliseconds it took to execute this run ...</duration>
</run>

The duration element is optional. Console output is hexBinary encoded so that you can pass in any control characters that are otherwise disallowed in XML. Elements must be in this exact order.

The above XML needs to be sent to http://myhost/hudson/job/_jobName_/postBuildResult.