TestnScale.com
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
- 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 = {"Home", "Products",
"Contacts"},
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 :
- Do runs at different load levels (by changing the Scale parameter) to
see how the
response time and throughput changes.
- See the Cycle
Times
Tutorial to learn how to modify the workload to add
cycle/think
times to create a more realistic workload.
Learning More
All
Rights
Reserved. See Terms
and
Conditions.