This is a guide to get you started with SPECj. We have created a custom JBoss kit to make it easier to setup SPECj, however, you should still be familiar with the official SPECj documentation. It will be invaluable to your tuning efforts.
Firstly, you will need a license to run Specj2004 from Spec.org.
JBoss Application server.
You can download this from www.jboss.com. Our SPECj configuration requires at least Jboss-4.0.2+. Don't use JBoss-4.0.2-RC1.
There are some required changes in JBoss-4.0.2 related to the default classloader model.
This thread shows a workaround.
JBoss SPECj kit
You can grab our latest kit from here http://jira.jboss.com/jira/browse/JBBENCH-21. This is used to build the custom JBoss descriptors for SPECj, and configure the app server with some reasonable default values.
PLEASE NOTE! This kit is provided in the hopes that it will help ease the pain of configuring SpecJ. It should not be expected to work on all versions of the app server, and some manual steps may be needed for your particular version.
Installation and Setup
You should have your directory tree setup as follows:
specj |- jboss-x.x.x - JBoss Application server |- jboss-specj-kit - Current JBoss kit for SPECj |- SPECjAppServer - SPECj application. Contact SPEC to obtain a license.
Scripts to setup your database are in jboss-specj-kit/schema/$DB_NAME. We use mysql as the example here:
Create the specj and jms users. You must use a mysql admin user to do this step.
mysql -u username -p -h dbhost < createUser.sql
Create the specj2004 database and tables. The jms database is created empty. It will be populated with tables on jboss startup.
mysql -u username -p -h dbhost < create_specj_tables.sql
Now, to populate the db run the following command in the jboss-specj-kit directory.replacing xx with your transaction rate:
ant -DSCALE=xx loaddb
If you have a multiprocessor machine, the threads option can decrease loading time. This example loads the db using 8 threads:
ant -DSCALE=xx -DTHREADS=8 loaddb
If you are using MySQL, you will need to set the following options in your my.cnf:
lower_case_table_names = 1 # MySQL is case-sensitive by default sql-mode = IGNORE_SPACE # Allow spaces between function names and the '(' character
After you have extracted these archives into a directory, go into the jboss-specj-kit directory. There are two properties files: One for mysql and one for oracle. You will need to edit one of these files to match your environment. The main variables are documented below:
location where Specj2004 is located
SPECj Transaction Rate
Driver output directory for results
Directory used to dump temporary data during a run
Time in seconds for the driver to wait for threads to start
Ramp up time in seconds. See specj documentation.
Steady state time in seconds.
Ramp down time in seconds.
Location where Jboss is installed
basic URL for the application server
IP portion from the application server's URL
Http Port used by the application server
The name of the server to be created under JbossAS
Home of JBoss that will contains Emulator packages
Address of the emulator
Http Port for the emulator
Name of the server to be created under $/server
connection URL to JDBC used by SpecjDB
class name of the used driver into SpecjDB
Database User Name for SpecjDB
Database Password for SpecjDB
Datasourcename used for SpecjDB
URL for JDBC used by JMS
Driver for JMS
Database user for JMS
Database Password for JMS
Datasource name used by JMS
The schema used from standardjboss-jdbc.xml
Specific Java parameters sent to jboss.env used in the driver. This is useful for setting MaxMemory for example.
The database name we are using (this has to match a directory under /configs. So, only change this variable if you want to create database specific deployment descriptors like datasources)
After you have edited the files to your liking, you run the command 'ant' in the jboss-specj-kit directory. This does a few things
Creates the jboss deployment archives for specj
Creates the specj and emulator server directories under $JBOSS_HOME/server
Creates the driver configuration files in $SPECJ_HOME/config to match your environment.
The first steps are to start the emulator and SUT. It is possible to run both the emulator and SUT in the same jboss instance by setting the variables 'server-name' and 'JBOSS_EMULATOR_SERVER_NAME' documented
above to the same value. This would not be a valid run for submission, but it is fine if you are just testing. If you do things this way, you only need to start one jboss intance.
Start the JBoss instance on the Emulator
cd $JBOSS_HOME/bin ./run.sh -c $JBOSS_EMULATOR_SERVER_NAME -b $JBOSS_EMULATOR_HOST
The '-b' is optional, but useful for binding jboss to a specific interface rather than all of them.
Start the JBoss instance on the SUT
cd $JBOSS_HOME/bin ./run.sh -c $server-name -b $APPLICATION_HOST
Start the Driver
cd SPECjAppServer/bin ./driver.sh
Now, if you have set everything up correctly, you should see the driver go through various stages (Starting threads, Ramp Up, Steady State, Ramp Down) and output a summary. You can now view the results of the run in
$OUTDIR/xxx (replace xxx with the run number output by the driver). The meanings of the files in this directory are explained thoroughly in the SPECj documentation.
You can find the official SPECj documentation at:
Reset the DB between runs
If you are repeatedly doing runs with the same transaction rate, there is no need to reload the db in between every run. To reset a loaded DB back to its clean state, you can simply drop all rows from the table 'm_largeorder'. This is exactly the same as if you had reloaded the db and is even mentioned in the official SPECj documentation. The following example uses mysql:
mysql $SPECJ_DB_NAME delete from m_largeorder where 1=1;
Reset the JMS DB between runs
Occasionally, if jboss is not shut down correctly, it can leave stale messages in the JMS database. These will cause tons of error messages to be spammed to the console when starting JBoss. To fix this problem, simply drop the jms database and re-add it. JBoss will recreate the JMS tables on startup. MySQL example below:
mysql drop database $JMS_DB_NAME create database $JMS_DB_NAME;
Please let us know about your experience. You can contact us at firstname.lastname@example.org or through the benchmark forums.