Don's Blog

This script is now available on GitHub:

https://github.com/DonaldSimpson/groovy

Here is a simple little Groovy script to monitor the health of slaves in Jenkins and let you know when they fail.

I use a lot of Jenkins slaves on many different Jenkins master instances, and I often have something like this running in a Jenkins job that lets me know if there are issues anywhere – which it will do if any of the Jenkins Slave Nodes are offline or dead etc.

To set this up, you first need to install the Groovy Plugin (https://wiki.jenkins-ci.org/display/JENKINS/Groovy+plugin).

Do this in Jenkins by going to “Manage Jenkins -> Manage Plugins -> Available”, then search for “Groovy Plugin”.

Once that’s done, create a new “Freestyle” Jenkins job and add a Build Step to “Execute System Groovy Script”.

Here’s the code:

int exitcode = 0
for (slave in hudson.model.Hudson.instance.slaves) {
 if (slave.getComputer().isOffline().toString() == "true"){
 println('Slave ' + slave.name + " is offline!"); 
 exitcode++;
 }
}

if (exitcode > 0){
 println("We have a Slave down, failing the build!");
 return 1;
}

You can see what’s going on here, but to be clear the main processing logic is:

for each Slave;
-  if it's offline, increment the exit code

if the exit code is greater than zero;
 - return 1, which will fail the job and trigger an email alert.

Obviously this is deliberately simple, and you could extend it to go off and do any number of things – including trying to bring the slave back online again with something like this: https://wiki.jenkins-ci.org/display/JENKINS/Monitor+and+Restart+Offline+Slaves.

I then configure the job run periodically through the Jenkins cron (check “build periodically” in the build triggers section of your jobs config, then put in a cron schedule – “* * * * *” or “@midnight” for example), and to email me if it fails so I know there’s something up.

A word of warning: don’t try changing the “return 1” to something like System.exit(1)… I did that initially, and it killed the running Jenkins instance… doh! 🙂

So when the Groovy script detects an Offline Jenkins Slave Node, the console output should look something like this:

Building on master in workspace /apps/jenkins/jobs/MonitorSlaves/workspace
Slave <YOURSLAVENAME> is offline!
We have a Slave down, failing the build!
Script returned: 1
Build step 'Execute system Groovy script' marked build as failure
Finished: FAILURE
<send an email or whatever here...>

Cheers,

Don

Updated! Yet Again!

There are several ideas and comments below on ways to get the logged in user in Jenkins – the person/user that triggered the current build.

This has changed/broken/altered quite a few times since I wrote the initial post (about 8 years ago) as changes have been made to Jenkins – not least being the introduction of Pipelines and Groovy! For quite some time the best solution was, probably, to use a plugin for this (see “build user vars” below).

If you’re writing a Jenkins Pipeline and you’re happy adding in the Build User Vars plugin, then you can simply do this to access the BUILD_USER variable in your Jenkins groovy Pipeline job:

wrap([$class: 'BuildUser']) {
  echo "BUILD_USER that started this Pipeline: ${BUILD_USER}"
}

A few alternative and older ideas follow…

I recently wanted (again) to get the logged-in user that triggered the build in Jenkins and came across my own post when searching… doh. I didn’t really feel like adding a plugin just for this one – supposedly simple – task so had another look at ways to achieve this, and this latest approach seems to work well…

It’s not pretty or robust, and I’m doing it in two goes (to demonstrate getting the correct line then refining things with sed to just the name) which you could simplify, but this is hopefully enough to illustrate the general plan. You’d need to validate it for builds that are started by timer and things like that too.

Here is the plain text version:

# Just show the output:
set -
# change dir to where this builds files are kept:
cd /home/don/jenkins/home/jobs/GetJenkinsJobUserName/builds/${BUILD_NUMBER}
# To start, just get the whole string from the 'log' file:
export STARTED_BY="`grep -i Started log`"
# Output it to the console:
echo "STARTED BY USER = ${STARTED_BY}"
# refine this to just the user name:
export JUST_NAME="`echo "${STARTED_BY}" | sed "s@Started by user@@"`"
echo "Jenkins User Name is ${JUST_NAME}"

This produces the following output when run:

That seems to do the job!

All the original thoughts and comments are below….

Here is a bit of code for getting the details of the logged-in user in Jenkins or Hudson – useful for auditing which user started a given build. I often add this to an audit database, that over time builds up a log of who has done what, where and when, as well as indicating the current state – I then query that through a JSP page that generates a dynamic table that is included via an iFrame in the Description part of the corresponding job… but anyway, back on topic…

Update: the Build User Vars plugin can now provide this functionality. Just install that then check the “Set jenkins user build variables” checkbox under the “Build Environment” section in the configuration page for the job you want to use it, then you should be able to access the following variables in your job:

• BUILD_USER — full name of user started build,
• BUILD_USER_FIRST_NAME — first name of user started build,
• BUILD_USER_LAST_NAME — last name of user started build,
• BUILD_USER_ID — id of user started build.

As far as I know, there’s no built-in way to do this (apart from the plugin now mentioned above). e.g. through a Jenkins environment variable like $CURRENT_USER or $USER_ID, but using wget, the Jenkins XML API and a little bit of XPath, you can easily query for many things at runtime like so:

THIS_USER=”$(wget -nv –no-proxy “$BUILD_URL/api/xml”‘?xpath=//userId/text()’ -O -)”

That line fetches the logged-on user id by requesting (via wget) the XML for the current BUILD_URL, filtering for the userId text and assigning that value to the variable $THIS_USER, so that it can be used elsewhere in the job.

You can change this around to get the username if you prefer:

THIS_USER=”$(wget -nv –no-proxy “$BUILD_URL/api/xml”‘?xpath=//userName/text()’ -O -)”

Or, try adding “/api/xml” to the end of a Jenkins URL, and you can see the numerous other elements you could request via the Jenkins XML API and XPath.

I have often used this approach to query and report on the status of multiple downstream jobs, for example. Sometimes it’s easier to wget the XML then parse it locally at runtime (with sed/awk/whatever you like) for the data you are interested in – the number of passed, failed or unstable builds can be counted by searching for the number of corresponding “blue”, “red” or “yellow” elements, for example.

UPDATE: It looks like the current version of Jenkins has disabled or broken this feature/ability, but there are always alternative solutions…

For example, if you have curl and xml_grep to hand, you could do it like this…

THIS_USER=`curl –silent $BUILD_URL | xml_grep –text_only userName`

most systems will have curl or alternatively wget, and if you don’t have xml_grep some plain old grep or awk will do the job.

Cheers,

Don