Tutorial: Creating your first Workload in Faban

Introduction
Basic Faban Concepts
The CoreHttp Workload
The SampleWeb Application
Building the Workload
Editing the Driver
Editing the Configuration File
Build and Deploy
Run_the_Workload
Learning More

Introduction

Faban provides a framework for developing workloads (called the Driver Framework) and a mechanism for run execution and management (called the Harness). We assume that you have already installed faban and gone through the Quick Start Tutorial that shows you how to deploy and run a workload test. This tutorial goes through the steps of creating a workload using faban. Faban is written completely in Java and provides APIs to access the framework. We will use the CoreHttp workload as a starting point and modify it to test a web application that has three pages - a home page (home.html), a products page (products.html) and a contacts page (contacts.html). This workload was used as an example in the Workload Design paper.

We will refer to the root directory of faban as $FABAN_HOME. This is the directory that contains the bin, lib, samples and other sub-directories. Please set your environment variable FABAN_HOME on your driver system and make that your current working directory. If you will be installing the web application on another system (that runs the apache server), you will have to install Faban on that machine as well in the same $FABAN_HOME location.

You will need the following software installed on the driver system :

JDK 1.6 (not just the JRE)
Ant 1.7.1 or higher

and Apache httpd server on the system you want to test.

Basic Faban Concepts

Master: The Faban Master refers to the primary Faban application that you interact with through a browser. Master may also refer to the system running the Faban Master.
Driver : This is the load generator and is responsible for implementing the workload definition, including operation mixes (the ratio in which various types of requests are made), cycle times (the rate at which requests are submitted), generate the operations and process responses from the server application. The Driver typically runs on the Master system but can run on any number of additional systems as required.
Run Configuration: Typically named run.xml, it describes the run parameters associated with this workload.

The CoreHTTP Workload

Although, it is possible to develop a new Faban workload from scratch, it is better to start with an existing one and edit it to fit our needs. For this tutorial, we will start with the CoreHTTP workload which tests a web server serving a "Hello World" html file. CoreHTTP is part of the workloads repository on this site. Download and install it now. The steps below install it in the same directory as faban :

$ ls

              corehttp.tar.gz    faban

              $ 

              $ tar xf corehttp.tar.gz

                $ 

              $ ls

              corehttp   corehttp.tar.gz   
              faban

              $ 

              $ cd corehttp

                $

              $ ls

              README       
                 
                        

              license.txt

              build       
                 
                         

              nbproject

              build.properties.template    src

              build.xml       
                         

              webapp

              deploy

              $

The source code for driver (CoreHttpDriver.java) resides in the com.testnscale.corehttp package under the src sub-directory. The configuration file run.xml resides in the deploy sub-directory. We will be editing these files in the following sections.

The SampleWeb Application

Download the SampleWeb application, samplewebapp.tar The first step is to setup the web application. To do this, you will need an apache http server and privileges to start/stop the server as well as add files to it's DocumentRoot. Most Unix distributions come with some version of apache pre-installed. If not, you can easily install your own as apache distributions are freely available for most platforms. Locate the DocumentRoot directory - it can be found from the apache configuration file, httpd.conf. The following snippet assumes that you are in the 'DocumentRoot' directory and shows how to deploy the SampleWeb application :

$ tar xf samplewebapp.tar

              $ ls samplewebapp

              home.html   
              products.html    contacts.html

              $

Make a note of the port number the server is listening on, usually port 80.

$ grep
                'Listen ' /etc/apache2/httpd.conf

              # Change this to Listen on specific IP addresses as shown
              below to 

              #Listen 12.34.56.78:80

              Listen 80

              $

Start apache httpd server and check if you can connect to it from your browser using the Listen address displayed above (http://localhost:80 if your browser is running on the same machine):

$ apachectl

                start

              $ tail
                /var/logs/apache2/error_log

              $ Sun Aug 16 15:27:19 2009] [warn] Init: Session Cache is
              not configured [hint: SSLSessionCache]

              [Sun Aug 16 15:27:20 2009] [notice] Digest: generating
              secret for digest authentication ...

              [Sun Aug 16 15:27:20 2009] [notice] Digest: done

              $

Building the Workload

Start by creating a copy of the corehttp workload directory that was installed previously.

$ cp -rp corehttp sampleweb

              $ cd sampleweb

              $ ls

README       
                 
                        

              license.txt

              build       
                 
                         

              nbproject

              build.properties.template    src

              build.xml       
                         

              webapp

              deploy

              $

We will first change all the package/file names and references from corehttp to sampleweb. Do the following :

$ cd src/com/testnscale

              $ mv corehttp sampleweb

              $ cd sampleweb

              $ mv CoreHttpDriver.java SampleWebDriver.java

              $ cd ../../..

The directory includes a Netbeans project in 'nbproject'. If you use Netbeans as your IDE, you can open this project. Change the Project name to 'SampleWeb Workload'. Go to 'Project Properties' and set all the paths to reflect your environment. For any other IDE, create a project for sampleweb specifying the ant build script as 'build.xml' - do not use the IDE generated ant script. For this simple project, you can also choose to hand-edit the files.

Edit

build.properties.template,
      src/com/testnscale/sampleweb/SampleWebDriver.java

and

deploy/run.xml

to change the following references :

Old Value	New Value
corehttp	sampleweb
CoreHttp	SampleWeb
coreHttp	sampleWeb

Be careful with the upper and lowercase letters and double-check that you've changed all references in these files. With the re-factoring done, we can now edit the files.

Editing the Driver

Open the driver source in src/com/testnscale/sampleweb/SampleWebDriver.java.

Defining the Operation Mix

The operation mix defines the navigation between the pages and the proportion in which each page will be visited. The mix was defined in the Workload Design document as a Matrix Mix (modeling a Markov chain) as follows :

From	To home.html	To products.html	To contacts.html
home.html	0%	80%	20%
products.html	20%	39%	41%
contacts.html	60%	19%	21%

To specify this mix in Faban, add the following code after the FixedTime annotation :

@MatrixMix (

                  operations = {"HomePage", "ProductsPage",
              "ContactsPage"},

                  mix = { @Row ({ 0, 80, 20 }),

                         
@Row
({20,

              39, 41 }),

                         
@Row
({60,

              19, 21 })

                        }

              )

For example, if an emulated user is currently on the Products page, there is a 20% probability that he will visit the Home page, 39% probability to visit the Products page and 41% probability to visit the Contacts page.

Retrieving the Parameters

The next step is to modify the constructor to retrieve the additional parameters we need for this workload. Notice that a parameter contextPath is defined. For our workload, we need three paths, one each for the 3 pages. Define these on line 70 where url is defined :

private String url, homeUrl, productsUrl,
              contactsUrl;

Modify lines 102-17 (where contextPath is parsed and url is built) as follows :

       
              

                      url =
              urlBuilder.toString();

              

                      s =
              ctx.getProperty("homePath");

                      if (s.charAt(0)
              == '/')

                         
homeUrl

              = url + s;

                      else

                         
homeUrl

              = url + '/' + s;

                      s =
              ctx.getProperty("productsPath");

                      if (s.charAt(0)
              == '/')

                         
productsUrl

              = url + s;

                      else

                         
productsUrl

              = url + '/' + s;

                      s =
              ctx.getProperty("contactsPath");

                      if (s.charAt(0)
              == '/')

                         
contactsUrl

              = url + s;

                      else

                         
contactsUrl

              = url + '/' + s;

Defining the Operations

In the corehttp workload, a single operation called Request is defined. We need to change this to 3 different operations, but all doing the same thing with just the url being different.

    @BenchmarkOperation (

                     
              name    = "HomePage",

                      max90th = 250,
              // 250 millisec

                      timing  =
              Timing.AUTO

                  )

                  public void doHomePage() throws
              IOException {

                      int size =
              http.readURL(homeUrl);

                      if
              (ctx.isTxSteadyState())

                         
contentStats.sumContentSize[ctx.getOperationId()]

              += size;

                  }

   @BenchmarkOperation (

                     
              name    = "ProductsPage",

                      max90th = 250,
              // 250 millisec

                      timing  =
              Timing.AUTO

                  )

                  public void doProductsPage() throws
              IOException {

                      int size =
              http.readURL(homeUrl);

                      if
              (ctx.isTxSteadyState())

                         
contentStats.sumContentSize[ctx.getOperationId()]

              += size;

                  }

    @BenchmarkOperation (

                     
              name    = "ContactsPage",

                      max90th = 250,
              // 250 millisec

                      timing  =
              Timing.AUTO

                  )

                  public void doProductsPage() throws
              IOException {

                      int size =
              http.readURL(contactsUrl);

                      if
              (ctx.isTxSteadyState())

                         
contentStats.sumContentSize[ctx.getOperationId()]

              += size;

                  }

Save the file. The driver code is now done.

Editing the Configuration File

The next step is to edit the run configuration file in deploy/run.xml.
This file specifies the parameters that the user will enter values for when submitting a test run. For our workload, the only parameters we need are the values of the 3 URL's of the application. We replace the <contextPath> element under <driverConfig> :

<driverConfig name="SampleWeb">

              ...

                             

              <property>

                                 

              <name>homePath</name>

                                 

              <value>/samplewebapp/home.html</value>

                             

              </property>

                             

              <property>

                   

              <name>productsPath</name>

                                 

              <value>/samplewebapp/products.html</value>

                             

              </property>

<property>

                   

              <name>contactsPath</name>

                                 

              <value>/samplewebapp/contacts.html</value>

                             

              </property>

...

              </driverConfig>

Scroll down and look at the parameters under <webServer>. You can change the default value of <hostPorts> to the server on which apache will be running for this workload. Alternatively, you can change this when scheduling a run. The next element is <enabled> - this specifies whether to allow Faban to start an Agent on this host. Since we want Faban to monitor performance on this host, change the default value to <true>.

    <webServer>

                     
              <fa:hostConfig 

                          
xmlns="http://faban.sunsource.net/ns/fabanharness"


              

                          

              xmlns:fa="http://faban.sunsource.net/ns/faban">

                         

              <fa:hostPorts>sampleWebHost:80</fa:hostPorts>

                         

              <enabled>true</enabled>

Save the run.xml file.

Build and Deploy

We are now ready to deploy the workload. This can be done using the ant target 'deploy'. Before we do that, make sure the faban master is up. Edit build.properties and set 'faban.home' and 'faban.url' to the appropriate hostname of the master/driver system. First cleanup the build directory to remove the corehttp files. These steps are shown below :

$ cat
                build.properties

              bench.shortname=sampleweb

              faban.home=/opt/faban

              faban.url=http://localhost:9980/

              deploy.user=deployer

              deploy.password=adminadmin

              deploy.clearconfig=true

              compiler.target.version=1.5

              $ 

              $ rm -rf build/*

              

              $ ant deploy

              Buildfile: build.xml

it:

              

              compile:

              Compiling 1 source file to
              /Users/testnscale/sampleweb/build/classes



              bench.jar:

                    [jar] Building jar:
              /Users/testnscale/sampleweb/build/lib/sampleweb.jar

              

              deploy.jar:

                    [jar] Building jar:
              /Users/testnscale/sampleweb/build/sampleweb.jar

              

              deploy:

              

              BUILD SUCCESSFUL

              Total time: 14 seconds

If you run into problems, you can download the sampleweb kit and compare your code against it.

Run the Workload

Point your browser at the Faban master (http://host:9980) and Schedule a Run. You should see the first JVM parameters form. If instead you see an error, compare your code against the sampleweb kit (or simply deploy and run it !) Tab through the forms and once you have all the correct parameters, submit the run. Good luck !

Next Steps

You can do any (or all) of the following :

Do runs at different load levels (by changing the Scale parameter) to see how the response time and throughput changes.

Learning More

See the Faban Driver Framework Developers Guide for more information on the framework offered to write drivers.
See the Faban Harness Developers Guide for more advanced information on how you can hook into the harness.
Faban API JavaDocs