Tutorial

This section provides tutorial guides to benchmarking data store performance with NDBench.

Please note that this is a work-in-progress.

First we describe the generic set-up steps that need to be done for every data store. Separate sections then describe steps that are data store-specific. Each tutorial assumes you are using Linux and have curl, Gradle (4.1+), and Docker(1.12.6+) installed (steps for Mac development environments will be similar, but probably not identical -- please feel free to add additional documentation for other environments!)

Generic (Data Store Independent) Set-up Steps

The diagram below illustrates how you would setup up Ndbench to run within a Docker container targeting read-write operations at one of the supported data stores, also running within Docker. Of course it is unlikely you would want to deploy mission critical services to Docker containers running on a random laptop. This tutorial is only intended to get you up and running in the simplest, most generic environment so that you can then move on to trying things out in a more realistic setting.

We first provide a high level overview of the steps, and then list the specific commands you need to run.

Generic Set-up Steps Overview

0. Download source code from github

1. Issue gradle commands to build the Ndbench .war archive from source

2. Download Docker container images from the central public Docker registry.

3. Launch the Docker images you downloaded (actually this step and the previous one are performed using one command.) Note that in this step you run whatever data store you are launching in a named Docker container. Then when you launch Tomcat in Docker you link the Tomcat container to the named container (using whatever name you decided on) so that Tomcat can reach the exposed port in the Docker container running your data store.

   Note that when you launch Tomcat in Docker you will mount a host-side directory and map that to a path in the container such that on the host side you can copy files and they will then be visible in the container.

4. Deploy the ndbench .war to the directory on the host that is mounted to be visible in the container.

5. Issue REST commands to initialize the driver for the data source you are benchmarking, then start reads or writes, or both.

Generic Set-up Steps Details

0. Follow the 'Initial Set-up' steps corresponding to your particular datastore in order to

   • download the Docker container for your datastore from the public Docker registry, and launch it with the name 'datastore'.
   • set up environment variables particular to your container that will be referred to in subsequent generic steps beow.
   • For example, if Elasticsearch was your datastore, you would follow the Initial Setup steps here.

1. Clone the repository and build the .war file as follows:

 clone git@github.com:Netflix/ndbench.git
 cd ndbench
 ./gradlew   clean build    # this will build the .war
 cp ./ndbench-web/build/libs/*.war /tmp/ndbench.war    #  copy .war to easy to remember spot

2. Start tomcat in Docker (with a host-resident directory mounted, to ease copying of the .war)

• You will link to the Docker instance running your data store via the hostname 'datastore', which Docker will kindly set up for you.

mkdir /tmp/deploy_dir
docker run -d -p 8080:8080  --link datastore -e CATALINA_OPTS="$CONTAINER_SPECIFIC_SETTINGS" -v /tmp/deploy_dir:/usr/local/tomcat/webapps/ tomcat:latest
tomcatContainerId=`docker ps -a | grep tomcat | sed -e's/tomcat.*//'`     
docker logs -f $tomcatContainerId      # tail the logs so you can see the progress of deployment

3. In another terminal from where you are tailing the tomcat logs, do the following

cp /tmp/ndbench.war /tmp/deploy_dir/ROOT.war

4. The output of the tailed tomcat logs should contain some lines like this:

    Deploying web application archive [/usr/local/tomcat/webapps/ROOT.war]
       ...<more lines>...
    Installing NdBenchClientPlugin: com.netflix.ndbench.plugin.es.EsRestPlugin with Annotation: ES_REST
       ...<more lines>...
    Deployment of web application archive [/usr/local/tomcat/webapps/ROOT.war] has finished...

5. Verify the .war deployed successfully

 curl localhost:8080/REST/ndbench/driver/getserverstatus

• You should see output like this:

{"ClientDrivers":["CassJavaDriverPlugin","DynoExtFunc","DynoGetSetPipeline",
   "DynoJedis","GeodeCloudPlugin","ES_REST","LocalDynomiteProxyPlugin","InMemoryTest".... more ...

6. Initialize client and start writing

• Run the following command:

curl http://localhost:8080/REST/ndbench/driver/init/ES_REST

• You should see this output in the terminal window where you ran curl:

{"isSuccess":true,"message":"NdBench client initiated!"}

• And in the tailed log output of tomcat you should see lines like this:

07:13:05,533  INFO NdBenchDriver:495 - Read RPS: 0, Write RPS: 0, total RPS: 0, Success Ratio: 0%

• Run the following command:

curl http://localhost:8080/REST/ndbench/driver/startWrites

• You should see this output in the terminal window where you ran curl:

 java.util.concurrent.TimeoutException  (a couple of these will appear initially, this is a known bug which will cause your initial success ratio to be slightly less than 100%)
08:56:40,417  INFO NdBenchDriver:495 - Read RPS: 0, Write RPS: 35, total RPS: 35, Success Ratio: 98%
08:56:45,417  INFO NdBenchDriver:495 - Read RPS: 0, Write RPS: 35, total RPS: 35, Success Ratio: 98%
 

7. Verify that data is being written into your datastore via the steps in the section corresponding to your datastore.

• • For example, if Elasticsearch was your datastore, you would follow the Verification steps here.

8. < TO BE WRITTEN - show how ndbench statistics for total written match up with elastic search's count >

---

Feel free to contribute more tutorials !