faban.org

Tutorial: Creating your first Workload in Faban


Table Of Contents

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 :

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

Basic Faban Concepts

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

init:

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 :

Learning More



All Rights Reserved. See Terms and Conditions.