Tutorial DBPSB 2012

At first you need to download IGUANA.

A simple way is by using the docker container, the recommend way is to download the shaded jar files, but we will use the github clone method instead as it provides the ability to change the code if you want to. Please keep in mind, that the modules should be run as daemons and thus will be started in the background. The diffrence between the shaded jar and the github is simply that instead of the classpath option you directly use the jar. f.e.:

java -cp "target/lib/*" ...

will be

java -jar MODULE.jar ... 

but for now...

Lets start

Clone the repository and go into the git directory by using the following commands in your terminal

git clone -b master --single-branch https://github.com/dice-group/IGUANA
cd IGUANA/

now execute your rabbitmq server (if not downloaded already please download and install rabbitMQ)

sudo rabbitmq-server & 

if done you can create IGUANA using maven

mvn clean install

or a faster way without testing if everything is setup correct:

mvn clean install -Dmaven.test.skip=true

Iguana consists of three modules. The core, the resultprocessing and the web module. The core controller will handle the actual benchmark, processing the queries and execute each benchmark task. The resultprocessor will then gain the query execution time through out the benchmark, will calculate each metric and save it in a triple store or NT file. To use a triple store you need to have one started yourself! In this tutorial we will use an ntriple file. The web module is just a handy optional(!) frontend to create a configuration and create charts if the result processor is used with a triple store. We will not handle the web module here!

now to start the corecontroller execute the following

cd iguana.corecontroller/
cp target/iguana.corecontroller-2.0.0.jar target/lib/
java -Xmx2G -cp "target/lib/*" org.aksw.iguana.cc.controller.MainController &
cd ..

As said we will change the result processor configuration to do this open the file iguana.resultprocessor/src/main/resources/iguana.properties with a text editor of your choice. Change the line

iguana.rp.storages=blazegraph

to

iguana.rp.storages=ntfile

and add the following line at the end of the file

ntfile.class=org.aksw.iguana.rp.storage.impl.NTFileStorage

Now start the resultprocessor module

cd iguana.resultprocessor/
cp target/iguana.resultprocessor-2.0.0.jar target/lib/
java -Xmx2G -cp "target/lib/*" org.aksw.iguana.rp.controller.MainController &
cd ..

Create the configuration

We will now create a benchmark Config. This is the the configration of the actual benchmark! We will create a single task, which will be a stresstest using 16 simualted SPARQL users with no warmup and it will be executed for 1 hour, the timeout for a query is 3 minutes (180s), no simulated network latency and the queries in the queries file queries.txt will be used.

##### TRIPLE STORE CONFIG ####
iguana.cc.connections=connection1
# The Readable Name you want to give the triple store
connection1.name=Blazegraph
# The sparql Endpoint of the triple store
connection1.service=http://localhost:9999/blazegraph/sparql
# The update Endpoint of the triple store (this is optional, if not provided Iguana will use the service address)
connection1.update.service=http://localhost:9999/blazegraph/sparql

##### DATASET CONFIG #####
iguana.cc.datasets=dataset1
# The Readable Name you want to give your Dataset
dataset1.name=DBpedia 100 percent



##### TASK CONFIG #####
stresstest.constructorArgs=stresstestArg.timeLimit,stresstestArg.warmupTime,stresstestArg.warmupQueries,stresstestArg.warmupUpdates,stresstestArg.workers,stresstestArg.queryHandler

#end restricition
stresstestArg.timeLimit=360000
#stresstestArg.noOfQueryMixes=1000

#warmup, We do not add a warmup here, but you should get the drill, time is in MS
stresstestArg.warmupTime=0
stresstestArg.warmupQueries=warmupQueries.txt
stresstestArg.warmupUpdates=warmupUpdates.txt

stresstestArg.workers=sparqlConfig1

#sparqlConfig1=#OF SIMULATED USERS, CLASS, TIMEOUT, QUERIES FILE, SIMUALTED FIXED NETWORK LATENCY, SIMULATED GAUSSIAN RANDOM NETWORK LATENCY

sparqlConfig1=16, "org.aksw.iguana.tp.tasks.impl.stresstest.worker.impl.SPARQLWorker", 180000, queries.txt, 0, 0

stresstestArg.queryHandler=org.aksw.iguana.tp.query.impl.InstanceBasedQueryHandler
# or if your Query handler has Constructor Arguments
# stresstestArg.queryHandler=org.example.com.MyQueryHandler, arg1, arg2,...

#e.g. if you want to use query patterns using the dbpedia dataset as a background
# stresstestArg.queryHandler=org.aksw.iguana.tp.query.impl.PatternQueryHandler, http://dbpedia.org/sparql

iguana.cc.tasks = stresstest

If you use query patterns visit: Query Handling

Save this file as iguana.config in the main IGUANA folder.

The queries file has to contain a query per line. Each line represents the index in the final results file (e.g. the query in line 1 is query0 the query in lined 100 is query99)

FOR MORE CONFIGURATION, E.G. HOW TO USE MORE THAN ONE TRIPLE STORE VISIT: https://github.com/dice-group/IGUANA/wiki/config#iguana-config

Now Download the DBPSB 2012 queries (or any other queries you want, only thing they have to be one query per line) into the IGUANA main folder and change the name to queries.txt

Finally execute the benchmark using the following command:

java -cp "iguana.corecontroller/target/lib/*" org.aksw.iguana.cc.config.ConfigSender localhost iguana.config

whereas localhost may the IP of the rabbitmq server

Thats it!

How to read the results? https://github.com/dice-group/IGUANA/wiki/Result-Processing

How to obtain statistics? https://github.com/dice-group/IGUANA/wiki/Obtaining-Statistics