The Ant Build Sensor is an Ant task that collect metrics regarding an invocation of Ant and sends this data to the Hackystat server. It represents the build data using the Build sensor data type, documented in Section 25.4, “Build”. This sensor is implemented as an Ant task, which must be used to instrument the build script. It can catpure detailed build failure information about checkstyle, compilation, and junit. For other types of build failures, it captures generic build failure messages.
The Ant Build sensor requires Java 1.5.0 or later and Ant 1.6.5 or later.
Follow the instructions in Chapter 2, Client-side configuration: Tool sensor installation to set your Hackystat host and user key.
In the HackyInstaller main window, select the Ant Build sensor and press "Configure Selected Sensor". Figure 26.1, “ Ant Build installer configuration window ” shows what the configuration window should look like after the path to Ant is set, the sensor is enabled, and the "Install" button has been pressed to install the sensor.
This sensor supports the following properties and paths:
Enable Build Sensor: This property controls whether the sensor is active or not. If not checked, the sensor will not collect or send data even if installed.
Ant home directory: This path specifies the top-level directory for Ant. The Build sensor requires the placement of a sensor executable into Ant's lib/ directory.
You must attach the sensor in your build script. Example 26.1, “Build sensor initialization” illustrates one possible way to do this.
Example 26.1. Build sensor initialization
<target name="InitializeBuildSensor">
<taskdef name="hacky-build"
classname="org.hackystat.sensor.ant.BuildSensorInstallationAntTask"/>
<hacky-build verbose="true" 
debug="false" 
monitorCheckstyle="true" 
monitorCompilation="true" 
monitorJUnit="true" 
keyValuePairs="configuration=${ProjectConfiguration},
buildStartType=${ProjectBuildStartType}"/> 
</target>
The hacky-build task should be invoked at the very beginning of a build, preferably as part of the first task invoked. If it is invoked more than once during a build, the subsequent invocations are ignored.
Please note the following regarding Example 26.1, “Build sensor initialization”:
| | The "verbose" attribute is optional. If set to true, then detailed build information will be printed out to the console. The default value is false. |
| | The "debug" attribute is optional. If set to true, then detailed debug information will be printed out to the console. Usually you don't set this option in a production environment. The default value is false. |
| | The "monitorCheckstyle" attribute is optional. If set to true, the build sensor will treat checkstyle specially by capturing individual checkstyle errors. Note that you can write ant script in such a way that a checkstyle failure does not constitute a build failure, but the sensor will treat checkstyle violation as build failure anyway in this mode. If set to false, the build sensor will treat checkstyle as any other ant tasks. In this mode, the build sensor will record a single failure entry only when ant thinks it is a build failure. The default value is false. |
| | The "monitorCompilation" attribute is optional. If set to true, the build sensor will treat javac specially by capturing individual compilation errors. Note that javac warning messages should not be considered as compilation errors, and thus should not be captured by this sensor. Also note that the sensor understands only Sun java compiler output. If you are using other compilers such as jikes, the compilation error may not be captured correctly. If set to false, the build sensor will treat javac as any other ant tasks. In this mode, the build sensor will record a single failure entry only when ant thinks it is a build failure. The default value is false. |
| | The "monitorJUnit" attribute is optional. If set to true, the build sensor will treat junit specially by capturing individual junit errors. Note that you can write ant script in such a way that a junit failure does not constitute a build failure, but the sensor will treat junit failure as build failure anyway in this mode. If set to false, the build sensor will treat junit as any other ant tasks. In this mode, the build sensor will record a single failure entry only when ant thinks it is a build failure. The default value is false. |
| | The "keyValuePairs" attribute is optional. It allows you to pass arbitrary information to be stored along with the build sensor data. Two examples of key-value pairs are configuration and buildStartType. Many systems can be built in a variety of configurations, and it can be useful to keep track of this in your build data. The "configuration" key-value pair allows you to specify which configuration of the system you are building. In addition, build scripts can be invoked in different ways, such as manually by developers or automatically through a daily build system. A "buildStartType" key-value pair allows you to specify the condition under which the build is initiated. |
To verify your build sensor, invoke Ant with any target in verbose mode to see if data is sent to the server. Example 26.2, “Example Build sensor output” shows the shell output from an example call.
Example 26.2. Example Build sensor output
C:\cvs\StackyHack>ant
Buildfile: build.xml
installBuildSensor:
[hacky-build] New build sensor ant listener installed.
init:
checkstyle:
compile:
junit:
[junit] Running edu.hawaii.stack.TestClearStack
[junit] Tests run: 1, Failures: 0, Errors: 0, Time elapsed: 0.234 sec
[junit] Running edu.hawaii.stack.TestStack
[junit] Tests run: 2, Failures: 0, Errors: 0, Time elapsed: 0.234 sec
[junitreport] Transform time: 594ms
[echo] JUnit results in C:\cvs\StackyHack\build\junit/index.html
[hacky-junit] Sensor enabled?: true
[hacky-junit] Processing file: C:\cvs\StackyHack\build\junit\TEST-edu.hawaii.stack.TestClearStack.xml
[hacky-junit] Processing file: C:\cvs\StackyHack\build\junit\TEST-edu.hawaii.stack.TestStack.xml
[hacky-junit] Hackystat data on 3 JUnit tests sent to http://hackystat.ics.hawaii.edu/ (0 secs.)
makeManifest:
jar:
[jar] Building jar: C:\cvs\StackyHack\build\stackyhack.jar
default:
BUILD SUCCESSFUL
Total time: 5 seconds
Build Sensor Report:
Start Time = Wed Feb 23 11:08:59 GMT-10:00 2005
End Time = Wed Feb 23 11:09:03 GMT-10:00 2005
Configuration = Unknown
Start Type = Unknown
Last Target = default
Build Location = C:\cvs\StackyHack
Build Result = Success
Checkstyle Ran = true
Compilation Ran = true
Unittest Ran = true
C:\cvs\StackyHack>
Note that in verbose mode, the build sensor will print out a summary of its collected data at the end of the build. Of course, the build sensor must first be enabled by setting ENABLE_BUILD_SENSOR=true in the sensor.properties file. If there is any error in the sensor's internal logic, or if the sensor is unable to send the data to Hackystat server, the error information will be printed out as well.
Once you verify that Build data is being sent from the client using verbose mode, login to your account on your Hackystat server, and use the "List Sensor Data" command on the Extras page to verify that Build data for today's date was received by the server from the Ant Build sensor, as illustrated in Figure 26.2, “ List Sensor Data with Build data ”.
The first step in troubleshooting your sensor installation is to verify that your Hackystat host and key settings are valid and that you can contact the Hackystat server, as described in Section 2.4, “HackyInstaller GUI: Setting and verifying the Hackystat host and user key”
The Ant Build sensor writes out a file called build.0.log to the .hackystat/logs directory that can be useful in debugging your installation. Under normal conditions, this file should look similar to Example 26.3, “Log file for the Ant Build sensor”.
Example 26.3. Log file for the Ant Build sensor
Hackystat Version: 6.3.1119 (November 19 2004 15:22:57)
SensorShell started at: 11/19/2004 15:52:45
Type 'help' for a list of commands.
Host: http://hackystat.ics.hawaii.edu/ is available and key is valid.
Defined shell command: Activity
Defined shell command: Coverage
Defined shell command: UnitTest
Defined shell command: BuffTrans
Defined shell command: Perf
Defined shell command: Build
Defined shell command: FileMetric
#> AutoSend [10]
AutoSend OK (set to 10 minutes)
AutoSend enabled every 10 minutes.
Checking for offline data to recover.
No offline data found.
#> Build [setTool, Ant]
setTool OK
#> Build [add, Success, , , 1109108161394, 1109108161394, 1109108171298, E:\work\hackyBuild, junitAll, configuration=Unknown,startType=Unknown,checkstyleRan=false,compilationRan=false,unittestRan=true,failureModuleName=N/A]
Build add OK (1 total)
#> send
Sending sensor data (11/19 15:52:46)
Activity: Send OK (No entries to send.)
Ping: Ping OK (contacted server http://hackystat.ics.hawaii.edu/ with valid key.)
Coverage: Send OK (No entries to send.)
AutoSend: AutoSend OK ('send' command ignored)
BuffTrans: Send OK (No entries to send.)
UnitTest: Send OK (No entries to send.)
Build: Send OK (1 entries)
Perf: Send OK (No entries to send.)
FileMetric: Send OK (No entries to send.)
If none of the above troubleshooting activities solves your problem, then you should send an email to your Hackystat Administrator to request help. Please include in your email the following information:
The output from 'java -version'.
The output from 'java -jar sensorshell.jar -verify'.
The contents of your sensor.properties file.
The contents of the build.0.log file.
A description of the problem you are having.
To disable Ant Build data collection temporarily, invoke HackyInstaller, bring up the Ant Build configuration window, and uncheck the "Enable Ant Build sensor" property, and apply the setting. To permanently uninstall the Ant Build sensor, press the "Uninstall" button and remove the Build targets from your Ant build.xml files.