1/31/2014

Monitoring external jobs - Jenkins - Jenkins Wiki

Monitoring external jobs

Added by Kohsuke Kawaguchi, last edited by Jesse Glick on Dec 04, 2013

Plugin Information
Plugin ID Latest Release Latest Release Date Required Core Dependencies Usage external-monitor-job 1.2 Aug 29, 2013 1.468 Changes Source Code Issue Tracking Maintainer(s) Installations In Latest Release Since Latest Release GitHub Open Issues n/a (id: jglick) 2013-Jan 41244 2013-Feb 43075 2013-Mar 48130 2013-Apr 51449 2013-May 53411 2013-Jun 54632 2013-Jul 58476 2013-Aug 59904 2013-Sep 61785 2013-Oct 66269 2013-Nov 66452 2013-Dec 65277

Adds the ability to monitor the result of externally executed jobs.

Jenkins 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 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 Jen enables you to monitor a 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
For Debian / Ubuntu: s u d oa p t g e ti n s t a l lj e n k i n s e x t e r n a l t o o l m o n i t o r #o b v i o u s l yy o us h o u l dr e p l a c el o c a l h o s tw i t haF Q D Ni fy o uw a n tt or u nj o b sf r o mo t h e rm a c h i n e s . e x p o r tJ E N K I N S _ H O M E = h t t p : / / @ s o r i n s . u k . x e n s o u r c e . c o m : 8 0 8 0 / e x p o r tJ E N K I N S _ H O M E = h t t p : / / @ l o c a l h o s t : 8 0 8 0 / j a v aj a r/ u s r / s h a r e / j e n k i n s / e x t e r n a l j o b m o n i t o r / j a v a / j e n k i n s c o r e * . j a r" e x t e r n a l b u i l d j o b n a m e "c o m m a n d t o r u n j a v aj a r/ u s r / s h a r e / j e n k i n s / e x t e r n a l j o b m o n i t o r / j a v a / j e n k i n s c o r e * . j a r" e x t e r n a l b u i l d t e s t "l sl Once you set up a project, you can monitor an execution by running a command like this: $e x p o r tJ E N K I N S _ H O M E = h t t p : / / u s e r : p w @ m y s e r v e r . a c m e . o r g / p a t h / t o / j e n k i n s / $j a v aj a r/ p a t h / t o / W E B I N F / l i b / j e n k i n s c o r e * . j a r" j o bn a m e "< p r o g r a ma r g 1a r g 2 . . . > For Windows: >s e tJ E N K I N S _ H O M E = h t t p : / / u s e r : p w @ m y s e r v e r . a c m e . o r g / p a t h / t o / j e n k i n s / >j a v aj a r\ p a t h \ t o \ W E B I N F \ l i b \ j e n k i n s c o r e * . j a r" j o bn a m e "c m d . e x e/ c< p r o g r a ma r g 1a r g 2 . . . >

If your webserver extracts the j e n k i n s . w a rfile when it deploys Jenkins then you may use the path directly to the W E B I N F / l i bdirectory and all other required jars will be found there. Otherwise yo extract these from the war file: j e n k i n s c o r e * . j a r r e m o t i n g * . j a r a n t 1 . 7 . 0 . j a r c o m m o n s i o 1 . 4 j a r c o m m o n s l a n g 2 . 4 . j a r j n a p o s i x * . j a r x s t r e a m * . j a r

All are found in the W E B I N F / l i bpath inside the war file. As long as they are all in the same directory, the j a v aj a r/ p a t h / t o / j e n k i n s c o r e * . j a rcommand will find the other required ja

Note: Older versions of Jenkins (before 1.324) also require w i n s t o n e . j a rin order to run this command. This jar is found at the top level directory inside the war file, and must be manually add the classpath (with c l a s s p a t hor c p ) in the java command. The JENKINS_HOME variable is used to locate the server Jenkins is running, so this must be set. Unless your Jenkins job has build permission for guest users, include the u s e r n a m e : p a s s w o r d @ of the URL, as seen in the examples above.

Note: Authentication via username:password in JENKINS_HOME is added in Jenkins 1.324; with previous versions either grant anonymous build permission on the job, or use c u r lto post XML Jenkins (see below).

https://wiki.jenkins-ci.org/display/JENKINS/Monitoring+external+jobs

1/2

1/31/2014

Monitoring external jobs - Jenkins - Jenkins Wiki

You can copy j e n k i n s c o r e * . j a rand 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: J E N K I N S _ H O M E = h t t p : / / m y s e r v e r . a c m e . o r g / p a t h / t o / j e n k i n s / 0**** e x p o r tJ E N K I N S _ H O M E = $ J E N K I N S _ H O M E ;j a v aj a rj e n k i n s c o r e * . j a r" b a c k u p "b a c k u p . s h2 > & 1>/ d e v / n u l l Note that you can also move the cron job itself to Jenkins 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: < r u n > < l o ge n c o d i n g = " h e x B i n a r y " > . . . h e xb i n a r ye n c o d e dc o n s o l eo u t p u t . . . < / l o g > < r e s u l t > . . .i n t e g e ri n d i c a t i n gt h ee r r o rc o d e .0i ss u c c e s sa n de v e r y t h i n ge l s ei sf a i l u r e < / r e s u l t > < d u r a t i o n > . . .m i l l i s e c o n d si tt o o kt oe x e c u t et h i sr u n. . . < / d u r a t i o n > < d i s p l a y N a m e > . . .T h en a m et ob ed i s p l a y e dr a t h e rt h a nt h eb u i l dn u m b e r. . . < / d i s p l a y N a m e > < d e s c r i p t i o n > . . .D e s c r i p t i o no ft h eb u i l d. . . < / d e s c r i p t i o n > < / r u n >

The d u r a t i o nelement is optional, since 1.429 d i s p l a y N a m eand d e s c r i p t i o ncan also optionally be appended, these three elements can be in any order, but must appear after log and result in order. Console output is hexBinary encoded so that you can pass in any control characters that are otherwise disallowed in XML. The above XML needs to be sent to h t t p : / / m y h o s t / j e n k i n s / j o b / _ j o b N a m e _ / p o s t B u i l d R e s u l t . A simple example using curl would be (using no real data; the sequence 4 1 4 2 4 3 0 Aencodes a console output of A B Cplus a trailing line feed symbol): $c u r lXP O S Td' < r u n > < l o ge n c o d i n g = " h e x B i n a r y " > 4 1 4 2 4 3 0 A < / l o g > < r e s u l t > 0 < / r e s u l t > < d u r a t i o n > 2 0 0 0 < / d u r a t i o n > < / r u n > '\ h t t p : / / u s e r : p a s s @ m y h o s t / j e n k i n s / j o b / _ j o b N a m e _ / p o s t B u i l d R e s u l t

Submit a run per CLI

The easiest option is for the execution can be submitted per CLI/ssh command. The gzipped log file can be transported through pipe:

$c a tr e s u l t . l o g . g z|s s hj e n k i n ss e t e x t e r n a l b u i l d r e s u l td i s p l a y7 d 5 5 2 c 4 b a _ L i n u x _ t b 2 1j o bb u i l d b o tr e s u l t1bd u r a t i o n4 2l o g

Sometimes build number is needed, as the calling program might need to put an URL to the submitted build. The CLI command above returns the new build number. The command above can be called programatically from an Java application. You can find a sample for it here.

Changelog
Version 1.2 (Aug 29, 2013)
new CLI command (pull #5) issue #19377 workaround for log rotation failure NPE fix translations

Labels
plugin-misc plugin-external

Comments (29) Show Comments Add Comment

Powered by a free Atlassian Confluence Open Source Project License granted to Jenkins. Evaluate Confluence today.
Printed by Atlassian Confluence 3.4.7, the Enterprise Wiki.

https://wiki.jenkins-ci.org/display/JENKINS/Monitoring+external+jobs

2/2