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 "Monitor an external job" as the job type.

Monitoring an execution

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

$ export HUDSON_HOME=http://user:pw@myserver.acme.org/path/to/hudson/
$ java -jar /path/to/WEB-INF/lib/hudson-core-*.jar "job name" <program arg1 arg2...>

For Windows:

> set HUDSON_HOME=http://user:pw@myserver.acme.org/path/to/hudson/
> java -jar \path\to\WEB-INF\lib\hudson-core-*.jar "job name" cmd.exe /c <program arg1 arg2...>

If your webserver extracts the hudson.war file when it deploys Hudson then you may use the path directly to the WEB-INF/lib directory and all other required jars will be found there. Otherwise you may extract these from the war file:

hudson-core-*.jar
remoting-*.jar
ant-1.7.0.jar
commons-lang-2.4.jar
xstream-*.jar

All are found in the WEB-INF/lib path inside the war file. As long as they are all in the same directory, the java -jar /path/to/hudson-core-*.jar command will find the other required jars.

Note: Older versions of Hudson (before 1.324) also require winstone.jar in order to run this command. This jar is found at the top level directory inside the war file, and must be manually added to the classpath (with -classpath or -cp) in the java command.

The HUDSON_HOME variable is used to locate the server Hudson is running, so this must be set. Unless your Hudson job has build permission for guest users, include the username:password@ portion of the URL, as seen in the examples above.

Note: Authentication via username:password in HUDSON_HOME is added in Hudson 1.324; with previous versions either grant anonymous build permission on the job, or use curl to post XML to Hudson (see below).

You can copy hudson-core-*.jar and the other required jars to other machines if you want to monitor jobs that are run on a different machine.

stdout and stderr of the program will be recorded, and a non-zero 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 scheduled executions.

Submit a run programatically

The above command submits the execution and its result by sending XML to HTTP. This means you can submit an execution record from any program, as long as you follow the same XML 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 order.

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

A simple example using curl would be (using no real data):

$ curl -X POST -d '<run><log encoding="hexBinary">4142430A</log><result>0</result><duration>2000</duration></run>' \
http://user:pass@myhost/hudson/job/_jobName_/postBuildResult

CSRF Protection

If your Hudson uses the "Prevent Cross Site Request Forgery exploits" security option, all the above requests (java -jar commands and curl/wget POSTs) will be rejected with 403 errors ("No valid crumb was included") on Hudson versions up to 1.384.
Starting in 1.385 the java -jar commands above will work when CSRF protection is enabled. For curl/wget you can obtain the header needed in the request from the URL http://server/hudson/crumbIssuer/api/xml (or /api/json). Something like this:

wget -q --output-document - \
'http://server/hudson/crumbIssuer/api/xml?xpath=concat(//crumbRequestField,":",//crumb)'

Monitoring external jobs

Setting up a project

Monitoring an execution

Monitoring cron jobs

Submit a run programatically

CSRF Protection

Labels:

Comments (12)

Anonymous says:

Kohsuke Kawaguchi says:

Kevin Ketchum says:

Drew Cox says:

Pascal Cohen says:

Bryan Oakley says:

Josh Koenig says:

Prem Polavarapu says:

moon people says:

Michael Alsen says:

Jeff Peck says:

Derek Choi says: