日本語 : Monitoring external jobs

Created by Unknown User (sogabe), last modified by Unknown User (akiko) on Oct 20, 2011

オリジナル: Monitoring external jobs

Jenkinsは、cron、procmail、inetdデーモンによるプロセスのような非対話型なプロセスの実行を、監視することができます。これらのタスクをまったく監視しないこともあります(その結果、失敗の検出がより難しくなっています)し、成功、失敗にかかわらず常にメールを送信する(そうすると、すぐにメールを無視するようになります）こともあります。Jenkinsを使用すれば、少しの手間で大量のタスクの監視を実行できます。

プロジェクトの設定

新しいジョブを作成して、"外部ジョブの監視"を選択します。

実行監視

一度プロジェクトを準備すれば、次のようなコマンドを起動すると実行を監視できます。

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

Windowsの場合はこちらです。

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

もしご利用のWebサーバが、Jenkinsのデプロイのために jenkins.war ファイルを展開しているのであれば、WEB-INF/libのパスを直接参照すれば、jenkins-core.jarを始めとした、実行に必要なjarファイルが見つかります。もしくは、jenkins.warを展開すれば、そこから必要なjarファイルを取り出すことができます。

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

上記のファイルは、warファイルの中の、 WEB-INF/lib の下にあります。また、どれも同じディレクトリにあるので、 java -jar /path/to/jenkins-core-*.jar という形でコマンドを実行すれば、他に必要なファイルも検出してくれます。

  • Note: Jenkins 1.324以前の旧バージョンでは、コマンド実行のためには winstone.jar も必要でした。このjarファイルはwarファイルのトップレベルのディレクトリにあります。また、このファイルは、別途手動で (-classpath や -cp) といったjavaコマンドのオプションで、クラスパスに追加する必要があります。

JENKINS_HOME 変数には、Jenkinsが起動しているサーバーの位置を指定しますので必須です。
もしJenkinsのジョブに認証が必要であれば、上記の例のように、URLに username:password@ を追加して下さい。

  • Note: JENKINS_HOME中以下に指定したusername:password を通した認証は、Jenkins 1.324からの実装です。旧バージョンでは、ジョブに対して匿名ユーザでの実行を許可するか、もしくは後述のように、Jenkinsに対してcurlのようなHTTPクライアントを通してXMLのリクエストを送信して下さい。

jenkins-core-*.jar とその他必要なjarファイルを他のマシンにコピーすれば、さらに別なマシンで実行されるジョブを監視することもできます。

プログラムの標準出力や標準エラーもログに記録し、0以外の終了コードであれば、そのジョブを失敗とみなします。

cronの監視

cronを監視するには、上記をcronスクリプトから起動するだけです。cronデーモンからのメールを受信しないように次のように記述してもいいかもしれません。

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

cron自身をフリースタイル・プロジェクトのビルドを使用してJenkins上に移すこともできます。そうすれば、スケジュールされた起動以外でもジョブを手動で実行することもできます。

プログラムからの外部ジョブの送信

jenkins-core.jar は、指定されたコマンドを起動して、その結果をHTTPでXMLとしてサーバーに送信するだけです。サーバーは決められたXMLフォーマットである限り、どんなものでも受け入れます。つまり、次の形式でJenkinsに結果を送信するプログラムを書くことができます。

フォーマットは以下の通りです。

<run>
  <log encoding='hexBinary'>...コンソール出力を16進数のバイナリエンコードしたもの...</log>
  <result>... エラーコード（整数）0は成功でそれ以外は失敗</result>
  <duration>... 実行時間(ms) ...</duration>
  <displayName>... ビルドナンバーの代わりとして表示させたい名前 ...</displayName>
  <description>... ビルドの詳細 ...</description>
</run>

duration 要素はオプションです。 1.429からは、 displayName と description がオプションで付加できるようになりました。これらの3要素はどの順番で指定しても構いません。ただし、ログと結果(log, result)要素の後に指定しないといけません。
また、コンソール出力はhexBinaryでバイナリエンコードしたものを指定して下さい。XML上では、そのままでは制御コードを指定することはできませんが、hexBinaryエンコードすればXMLでの扱いが可能になります。

上記のXMLを http://myhost/jenkins/job/_jobName_/postBuildResult に送信してください。

下記に、curlを使ったシンプルな例を示します。(この例では、実際のデータは利用せず、コンソールからの出力である ABC と改行コード(LF)を、hexBinaryで 4142430A とエンコードして送信しています)

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

クロスサイト・リクエスト・フォージ(CSRF)対策 / CSRF Protection

Jenkins 1.384 までは、セキュリティオプションの "Prevent Cross Site Request Forgery exploits" を使ってJenkinsを利用している場合、上記のような (java -jar や curl/wget によるPOST) リクエストは、"有効なcrumbがありません/ No valid crumb was included" といった403エラーでリジェクトされてしまいます。

(CSRFについては、こちら: https://www.owasp.org/index.php/Cross-Site_Request_Forgery)

1.385以降のバージョンでは、上記のような java -jar コマンドは、 CSRF対策を有効にしている場合でも利用できます。curl/wgetの場合は、 http://server/jenkins/crumbIssuer/api/xml (または /api/json) のURLを通して、必要なヘッダを取得することができます。
たとえば、このような感じになります。

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