Skip to main content

By clicking Submit, you agree to the developerWorks terms of use.

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

  • Close [x]

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerworks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

By clicking Submit, you agree to the developerWorks terms of use.

All information submitted is secure.

  • Close [x]

Select a language:

  • Close [x]
  • Close [x]

Add a dashboard view to Rational Build Forge

A step-by-step guide to using the Build Forge API to monitor and visualize server performance and other parameters

Alexandru Ciobanu (ciobanu@ca.ibm.com), Software Developer, IBM Canada
Alexandru Ciobanu
Alex is a software developer at IBM Canada, working on Rational Portfolio Manager. Among other things, he enjoys helping release engineers in his team by providing them with tools like this one. At the time of the writing, he was also a graduate student at McGill University, doing research in high-performance computing and error correction codes.

Summary:  A dashboard presents a collection of parameters in a highly structured, simplified, manner, which enables software release engineers and developers to check the state of a system at a glance. This article shows how to add a dashboard view to IBM Rational Build Forge and use it for monitoring servers. The procedure described is easily and safely deployed to production environments.

Date:  21 Jan 2010
Level:  Intermediate
PDF:  A4 and Letter (274KB | 17 pages)Get Adobe® Reader®
Also available in:   Portuguese

Activity:  16158 views
Comments:  

Overview and motivation

IBM® Rational® Build Forge® is often used to orchestrate complex processes, such as building, packaging, or testing software. In most nontrivial situations, these processes involve multiple servers. To avoid preventable failures, release engineers often perform a series of checks to make sure that all of the servers that are going to be involved in the process are ready. With increasing the number of servers, this can be both tedious and error-prone.

A solution that works well in practice is to use a dashboard, which is a tool that regularly checks on the servers and presents the aggregate information in an easy-to-read manner. It enables the user to review the health of all the relevant servers at a glance.

This article explains how to create such a dashboard for Build Forge. By the end of the article, you will end up with a running dashboard similar to the one shown in Figure 1.


Figure 1. Simple dashboard showing 5 servers, one of which is low on disk space
Five servers, one low on disk space

Back to top

Requirements

This article is based on the assumption that the following are available:

  • Build Forge Version 7.0.1 or later: A version of Build Forge that provides the API used in this article.
  • Java™ 5 or later (or Perl): The Build Forge API is offered in both Java™ and Perl. In this article Java is used, but all the concepts can be equally implemented in Perl.
  • (Recommended) Eclipse Version 3.3 or later: Eclipse project files are provided, along with the source code.

An implicit assumption that we make in this article is that, in your Build Forge Management Console, you have defined at least one server and installed the Build Forge agent on it.

Back to top

Architecture

The application presented in this article consists of these components:

  • Build Forge server
  • Dashboard application
  • (Optional) OSPerfMeter, a cross-platform performance measurement tool (see the Downloads section)

By default, the dashboard application polls the Build Forge server and displays the following information about each of the monitored servers:

  • Number of Build Forge jobs currently running
  • Current CPU load
  • Free memory available
  • Disk space available on the current partition

The list of parameters can be extended to meet your needs. See the section dedicated to custom parameters for details on how to achieve that.

OSPerfMeter can be used to provide alternative measurements to the default list. It is a cross-platform Java application. For more details see the OSPerfMeter section.

Back to top

Step 1. Create and configure the collector

  1. In the left menu of the Build Forge Management Console, select Servers and then Collectors.
  2. In the lower half of the main page, in the input box asking for a name, type the name for the new collector (for example, mydashboard) and click Save.
  3. Use the form in the lower half of the main window to add the ON_DASHBOARD variable with Set Value as the type, and the value set to true.
  4. Click Save. The upper-half of the main page will update and display the newly created variable.
  5. In the upper half of the main page, click Add Collector Variable button. In the lower-half, select the Built-in type, and then select CPU_LOAD. Click Save.
  6. Repeat the previous step for built-in variables: CPU_LOAD1, MEM_FREE, DISK_FREE, and OS_SYSNAME.

Figure 2. The collector configured
The collector configured with all of the needed variables

The newly created collector should look like Figure 2. Notice that order of variables is irrelevant.

Back to top

Step 2. Assign the collector to servers

Now that the collector is ready, you can assign it to the interesting servers (servers that will be monitored).

  1. In the Build Forge Management Console left menu, select Servers.
  2. In the upper half of the main page, click one of the servers. In the form in the lower half, in the Collector field, select the name of the collector that you created in the previous section, and then click Save.
  3. Repeat the previous step for all of the servers that are to be monitored and displayed on the dashboard.

Verify that all interesting servers have the correct collector specified in the Collector column in the server list.


Figure 3. Configured servers
The servers configured to use the sample dashboard

After the collector is assigned, the servers will start displaying additional information in their manifests. In our case the manifest will include the following fields: CPU_LOAD, CPU_LOAD1, MEM_FREE, DISK_FREE, and ON_DASHBOARD. In other words, by assigning a collector, you demand that the server starts reporting on additional parameters.

Here is how you can display the manifest of a server:

  1. In the Build Forge Management Console menu, on the left, select Servers.
  2. In the upper half of the main page, click one of the servers that has the dashboard collector assigned.
  3. In the lower half, click the Manifest tab.

Figure 4. Manifest described
The manifest of a server that uses the collector

What this server reports is that it has a 0% CPU load, 1760MB of free memory, and about 5.8GB of free disk space (on the partition specified for this particular server).

If the manifest is empty, it means that the server is in the process of updating it. Wait 20–30 seconds and redo the steps to display the manifest.

Notice that, in addition to the requested variables, there are a few others (BF_AGENT_VERSION, BF_JOBS, and others) These parameters, prefixed by BF_, are the default parameters and are found in the manifests of all servers.

Back to top

Step 3. Generate the HTML files

So far, you have set up the Build Forge Management Console to keep track of several parameters for your servers, namely: CPU load, available memory, and free disk space. Keep in mind that the list of parameters can be extended to include any parameter, as long as there is a command that can measure it.

Now you can run the dashboard application and generate the HTML files that comprise the dashboard. The following steps should be done on a computer that has Java 5 or later installed:

  1. Download the dashboard application and the accompanying files from the Downloads section of this article.
  2. Download the Build Forge API from your Build Forge server:
    1. Go to http://<yourBFserver>/clients/ and log in, if necessary (use your Build Forge Management Console credentials).
    2. Select the Services Layer Java Client JAR file.
    3. Save the JAR file in the same directory as the dashboard application
  3. Edit the buildforge.properties files to match the settings on your server. For now, use your own credentials. Later you can create a separate user ID for this task.
  4. Run the dashboard application:
    • update_dashboard.bat (on Microsoft® Windows® platforms)
    • update_dashboard.sh (on UNIX® or similar platforms)

If the execution is successful, the dashboard will generate several HTML files. In case of failure, analyze the error messages to pinpoint the issue: network problems, authentication problems, and so forth.

An HTML file will be generated for each server that uses the collector defined previously. The name of the files is of the form <FULL_HOSTNAME>.html (for example: myserv3.mydomain.com.html).

An additional file called lastupdate.html is generated. It contains the date and time when the dashboard was generated.

Back to top

Step 4. Edit the dashboard index.html file

The index.html file is structured similarly to a template with placeholders. It includes the HTML files generated by the dashboard application by using <iframe> HTML elements. This way, the index.html file needs to be edited only once. in the beginning (or when servers are added or removed), but the server HTML files can be generated often without causing conflicts.

For example, assume that you have five servers with the characteristics described in Table 1.


Table 1. Description of 5 hypothetical servers used as example
Server nameOperating SystemGenerated file
myserv1Linuxmyserv1.mydomain.com.html
myserv2Windowsmyserv2.mydomain.com.html
myserv3AIXmyserv3.mydomain.com.html
myserv4Linuxmyserv4.mydomain.com.html
myserv5AIXmyserv5.mydomain.com.html

By editing the index.html file to include the appropriate files, you get what the following code listing shows.


Listing 1. The modifications to be made to index.html file in to make it display the servers in Table 1
<tr>
        <td>
	<span class="stitle">Windows</span>
        </td>
        <td>
                <div class="boxes">
			<iframe class="sframe" frameborder="0" scrolling="no" 
				src="servers/myserv2.mydomain.com.html">
			</iframe>
                </div>
        </td>
</tr>


<tr>
        <td>
                <span class="stitle">Linux</span>
        </td>
        <td>
                <div class="boxes">
			<iframe class="sframe" frameborder="0" scrolling="no" 
				src="servers/myserv1.mydomain.com.html">
			</iframe>
			<iframe class="sframe" frameborder="0" scrolling="no" 
				src="servers/myserv4.mydomain.com.html">
			</iframe>        
                </div>
        </td>
</tr>


<tr>
        <td>
		<span class="stitle">AIX</span>
        </td>
        <td>
                <div class="boxes">
			<iframe class="sframe" frameborder="0" scrolling="no" 
				src="servers/myserv3.mydomain.com.html">
			</iframe>
			<iframe class="sframe" frameborder="0" scrolling="no" 
				src="servers/myserv5.mydomain.com.html">
			</iframe>        
                </div>
        </td>
</tr>

Now the dashboard view is ready to be displayed. If you open the index.html file in your browser, the dashboard should look like Figure 1.

Notice that MYSERV1 is low on disk space and has been color-coded accordingly. On the dashboard, the server can be in one of three states: OK (green), Warning (yellow), and Critical (red). To find more details read the help page of the dashboard.

Back to top

Step 5. Copy the dashboard files to a Web server

Now that the dashboard displays information about the servers, it is the time to publish it, meaning to copy the files to a Web server. There are two ways to do this:

  • Use the Build Forge built-in Web server
  • Use a dedicated Web server for the dashboard

The first method is simple:

  1. On the server where Build Forge Management Console is installed, create a directory:
    <BUILDFORGE_HOME>/webroot/public/dashboard/
  2. Move the content of the web/ directory (the updated dashboard files) to the newly created directory.
  3. Point the browser to http://<MY_BUILDFORGE_SERVER>/dashbard/ to see dashboard.

Notice that this page is public and anyone in your network will be able to access it.

For the second method, you must follow these steps:

  1. Install and configure a Web server on a separate server.
  2. Move the content of the directory web/ (the updated dashboard files) to a directory under the Web root of the server.
  3. Point the browser to http://<DASHBOARD_WEB_SERVER>/<PATH_TO_DASHBOARD>/ to see the dashboard.

Back to top

Step 6. Embed the dashboard in Build Forge (optional)

This step is optional and requires Build Forge V7.1 or later and administrative privileges.

  1. Log in to the Build Forge Management Console as an administrator.
  2. In the upper-right part, click the UI Config tab.

Figure 5. UI Config tab
The location of the UI Config tab

  1. Click Add Tab, and complete the fields in the Details section (see Figure 6):

Figure 6. Dashboard tab settings
The setting for the Dashboard tab

  1. Click Save to apply the changes.

Now all users will see a new tab called "Dashboard." When clicked it will load the dashboard page. Clicking on the "Console" tab takes the user back to the default Build Forge page.

Back to top

Update the dashboard automatically

To keep the dashboard up to date, a job can be scheduled to generate the HTML files and copy them to the appropriate location. On UNIX-like systems this can be done using cron, while on Windows the equivalent tool is Task Scheduler. An update interval of 5 minutes is suitable for most situations.

Scripts that perform this task (both for Windows and UNIX-like platforms) are included with the dashboard application. For example on a UNIX-like system the script is called update_dashboard.sh and has the following content:


Listing 2. The update_dashboard.sh script
#!/bin/sh

# add Java to PATH if not already done
# export PATH=$PATH:/opt/java1.5/jre/bin

#path to the directory that is under the web serer root
export WEBDIR=web

# put timestamp on top of log file
date > log.txt

# run dashboard updater to generate HTML files
java -cp dashboard.jar:rbf-services-client-java.jar \
         com.ibm.rational.dashboard.Main >> log.txt 2>&1

# move files to directory under web server root
mv *.html  $WEBDIR/servers/
mv log.txt $WEBDIR/servers/

Back to top

Custom parameters

So far, you have used built-in variables provided by Build Forge (CPU_LOAD, MEM_FREE, etc.). It is also possible to define custom parameters in the collectors. To do so, follow these steps:

  1. In the Build Forge Management Console left menu, select Servers and thenCollectors.
  2. Select an existing collector or create a new one.
  3. Use the form in the lower part of the screen to add a custom variable (see Figure 7).

For example you could add a JAVA_VERSION variable in the way that Figure 7 shows:

  • Type: Run Command
  • Variable: JAVA_VERSION
  • Command: java –version
  • Regular Expression: ^java version "([^"]+)

Figure 7. Adding custom command variable
Add a custom command variable to the collector

As you can see, the command java -version is executed and the output is captured by a regular expression. After adding this variable to the collector, the servers will include this new parameter in the manifest, as Figure 8 shows.


Figure 8. Updated manifest
The updated manifest displays the added variable

This approach can be used to get any server parameter that can be obtained by running a command and capturing the output.

In order to display this nonstandard parameter on the dashboard, relatively simple modifications should be made to the source code and templates.

Back to top

OSPerfMeter and alternative parameter measurements

This approach (mentioned previously) is useful in the situation when you need alternative measurements for the basic parameters: CPU load, free memory, free disk space, and so on. This can occur on systems where the Build Forge agent fails to read these parameters properly (older versions of HPUX, for example).

For this case, specifically, the dashboard application supports alternative parameter measurements:

  • CPU_LOAD_ALT (supersedes CPU_LOAD if present)
  • MEM_FREE_ALT (supersedes MEM_FREE if present)
  • DISK_FREE_ALT (supersedes DISK_FREE if present)

If the CPU_LOAD_ALT variable appears in the collector, the dashboard will use it rather than the standard CPU_LOAD. The same thing applies for MEM_FREE_ALT and DISK_FREE_ALT.

If you are not sure how to make alternative measurements on your servers, you can use OSPerfMeter, which is included with this article, in the Downloads section (source code and binary). The tool works on the following platforms:

  • Microsoft® Windows® (XP, 2003 and later)
  • Linux® (2.4 kernel and later)
  • Solaris (8 and later)
  • IBM® AIX® (Version 5.2 and later)
  • HPUX (11.11 and later)

Listing 3 shows how it is used.


Listing 3. Running OSPerfMeter from the command line (requesting all measurements)
        
$ java -jar OSPerfMeter.jar
CPU Usage:           1.6 %
RAM Available:       953 megabytes
Swap Usage:          0.5 %
HDD Space Available: 8109 megabytes

Alternatively, it can print individual values, as Listing 4 shows.


Listing 4. Running OSPerfMeter from the command line (requesting measurements separately)
$ java -jar OSPerfMeter.jar -cpu
CPU Usage:           1.6 %

$ java -jar OSPerfMeter.jar -mem
RAM Available:       953 megabytes

$ java -jar OSPerfMeter.jar -swap
Swap Usage:          0.5 %

$ java -jar OSPerfMeter.jar -hdd
HDD Space Available: 8109 megabytes

To import OSPerfMeter measurements in a Build Forge collector, use the information in Table 2.


Table 2. Build Forge collector parameters for alternative performance measurements with OSPerfMeter
Variable nameCommandRegular expression
CPU_LOAD_ALTjava -jar OSPerfMeter.jar -cpu^CPU Usage:(.*) %
MEM_FREE_ALTjava -jar OSPerfMeter.jar -mem^RAM Available:(.*) megabytes
DISK_FREE_ALTjava -jar OSPerfMeter.jar -hdd^HDD Space Available:(.*) megabytes

Back to top

Conclusion

This article describes a method of using the Build Forge API to extract, process, and display performance parameters of servers. The information thus obtained is used to create a dashboard, a tool that allows release engineers and developers to check the status of multiple servers at a glance before launching lengthy processes. From the author's experience having a dashboard in multiserver environments reduces the number of unexpected failures and makes the process more predictable.


Back to top

Downloads

DescriptionNameSizeDownload method
Dashboard application binary and required filesdashboard.zip50KBHTTP
Dashboard application source codedashboard_src.zip42KBHTTP
OSPerfMeter application binaryosperfmeter.zip12KBHTTP
OSPerfMeter application source codeosperfmeter_src.zip42KBHTTP

Information about download methods


Resources

Learn

  • More about Build Forge:
  • Learn about other applications in the IBM Rational Software Delivery Platform, including collaboration tools for parallel development and geographically dispersed teams, plus specialized software for architecture management, asset management, change and release management, integrated requirements management, process and portfolio management, and quality management.

  • Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.

  • Explore Rational computer-based, Web-based, and instructor-led online courses. Hone your skills and learn more about Rational tools with these courses, which range from introductory to advanced. The courses on this catalog are available for purchase through computer-based training or Web-based training. Additionally, some "Getting Started" courses are available free of charge.

  • Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.

  • Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.

  • Browse the technology bookstore for books on these and other technical topics.

Get products and technologies

Discuss

About the author

Alexandru Ciobanu

Alex is a software developer at IBM Canada, working on Rational Portfolio Manager. Among other things, he enjoys helping release engineers in his team by providing them with tools like this one. At the time of the writing, he was also a graduate student at McGill University, doing research in high-performance computing and error correction codes.

Close [x]

Report abuse help

Report abuse

Thank you. This entry has been flagged for moderator attention.

Close [x]

Report abuse help

Report abuse

Report abuse submission failed. Please try again later.

Close [x]

developerWorks: Sign in


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 

The first time you sign into developerWorks, a profile is created for you. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. You may update your IBM account at any time.

All information submitted is secure.

Close [x]

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 

All information submitted is secure.

Rate this article

Comments

Back to top

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Rational
ArticleID=463152
ArticleTitle=Add a dashboard view to Rational Build Forge
publish-date=01212010
author1-email=ciobanu@ca.ibm.com
author1-email-cc=

Table of contents

Next steps from IBM

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

IBM PureSystems on a kaleideoscope background

Unleash the power of hybrid cloud computing today!

Public and private solutions in one trial.

Special offers

On demand demos: An easy way to watch and learn

Get recognized! W Author Program

Cloud Computing resources for IT professionals

Trial software offers

Share this page:

  • Close [x]

Follow developerWorks:

  • Close [x]