Monitoring Builds using Build Activities
The build component is designed to allow you to integrate your build system with Jazz so that your builds become first-class Jazz objects. Among other benefits, this allows you to more easily track and monitor your builds. An important aspect of this functionality is the ability to divide your build into well-defined periods of activity in order to facilitate more fine-grained monitoring and tracking. We call these user-delineated segments build activities.
Build engineers create build activities by demarcating their start and end points in build scripts with calls to the startBuildActivity and completeBuildActivity ant tasks. These ant tasks are part of the Team Concert Build System Toolkit, a library of functionality intended to facilitate integration of your build with Team Concert. For more information on the ant tasks, see the documentation in the online help.
In the sections below we’ll look at some common examples of how to use build activities in your builds.
Simple Build Example
In a simple build example, the build activities occur serially during the build, one following the other without overlapping. Each activity is started with a call to the startBuildActivity ant task. In this case you do not need to use the completeBuildActivity task to explicitly complete build activities. Instead you can specify that each activity completes automatically when the next activity begins. This is accomplished by specifying autocomplete=true in the startBuildActivity task. Example:
<startBuildActivity label="Testing" autoComplete="true" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> Below is an example of an activities page in the Build Result Editor for a build with a series of build activities created in this manner.
Nested Build Example
In builds that are more complex and lengthy, a flat list of activities becomes unwieldy and less helpful. In this case it makes sense to subdivide activities into smaller segments, creating a hierarchy of build activities. To create a nested child activity you must specify the id of the parent activity in the startBuildActivity task. This means you must first have the parent id in hand.
Capturing an Activity ID
Whenever a build activity is created using startBuildActivity, a unique id is generated for that activity. If you need access to that id, you can supply the name of an ant property using the activityIdProperty attribute. The startBuildActivity implementation will then set the value of the ant property with that name to the id of the new activity.
In the following example we first create the parent activity and specify the ant property name testingActivityId to contain the generated activity id. We then create the nested child activity by supplying the value of testingActivityId as the parent activity id.
<startBuildActivity label="Testing" activityIdProperty="testingActivityId" autoComplete="true" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> <startBuildActivity label="testing foo" parentActivityId="${testingActivityId}" autoComplete="true" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> <startBuildActivity label="testing bar" parentActivityId="${testingActivityId}" autoComplete="true" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> Autocomplete and Nested Activities
Note that in the example above, we are still specifying autocomplete=true in lieu of using the completeBuildActivity task. Autocomplete will still work as expected with nested activities in a serial build. Child activities with autocomplete set to true are automatically completed when the next child activity of the same parent is started. The last child activity is then automatically completed when the parent completes (either automatically or explicitly).
Below is an example of an activities page in the Build Result Editor for a build with a series of nested build activities created in this manner.
The Compiling activity has 3 child activities that are already complete. The Testing activity has 2 children, the 2nd of which is currently in progress.
Parallel Build Example
The most complex scenario involves a parallel build. A build may fork off several processes, possibly on multiple machines, that will run simultaneously and will each create their own build activities. There is no way to differentiate build activities started by one process from those started by other processes in the build. This means that if we specify autocomplete=true for peer build activities running in different threads of execution, the activities would be randomly auto-completed as new activities are started in other processes. By peer activities we mean activities with the same parent activity, which includes all top-level activities (activities with no parent).
So in the parallel build case, build activities that will run in parallel with other peer activities must not use the autocomplete flag. Instead, each of these activities must be explicitly completed using the completeBuildActivity task. The activity id must be obtained and specified in the same manner as in the nested build example.
Nested child activities that will occur serially in a particular thread of build execution can still use the autocomplete flag as they cannot be auto-completed by activities outside of their parent.
Below is an example of a starting a compile build activity (with nested children) that will run in parallel with compile activities started by other processes.
<startBuildActivity label="Compiling Bar" activityIdProperty="compilingBarActivityId" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> <startBuildActivity label="compiling bar1" parentActivityId="${compilingBarActivityId}" autocomplete="true" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> <startBuildActivity label="compiling bar2" parentActivityId="${compilingBarActivityId}" autocomplete="true" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> <completeBuildActivity activityId="${compilingBarActivityId}" buildResultUUID="${buildResultUUID}" repositoryAddress="${repositoryAddress}" userId="${userId}" password="${password}" /> In the example above, the build activity compiling bar1 is auto-completed when compiling bar2 is started. The build activity compiling bar2 is auto-completed when its parent activity is explicitly completed by the call to the completeBuildActivity task.
The build activity “Compiling Foo” is started in a similar manner to this by another thread of build execution and runs in parallel with the “Compiling Bar” activity.
The image below shows the resulting activities page in the Build Result Editor:
In the example above, the activities Compiling Bar and Compiling Foo execute in parallel and both have child activities currently in progress.