TKperf Installation Manual

This article deals with the installation of the performance measurement tool TKperf. The installation requirements as well as the taken steps from installation to a first test run are described.

Requirements

A Fio installation > version 2.0.3 is required. TKperf checks with which fio if Fio is available. A How-To on installing Fio can be found at Compiling Fio.
hdparm
To run the Python scripts the following Pyhton packages must be installed:
- logging, json, lxml, subprocess, datetime, argparse, copy, collections, numpy, matplotlib

Under Ubuntu it is sufficient to install the following packages from the Ubuntu repositories:

sudo apt-get install python-matplotlib python-lxml python-numpy hdparm

Installation

Ubuntu Repository

TKperf and Fio can be installed from the Thomas Krenn Repo (cf. Thomas Krenn Ubuntu Repository):

:~$ sudo apt-get install tkperf
[sudo] password for gschoenb: 
Reading package lists... Done
Building dependency tree
[...]

Manually

To install TKperf run the following command:

$ sudo python setup.py install

Attention: If the sources are updated (via downloading a new tar.gz. archive or Git) the install command has to be run again.

To install Fio manually please refer to the article Compiling Fio.

TKperf Test Run

Attention: All data is lost on the target test device. The device becomes overwritten with random data multiple times, for SSDs a Secure Erase is carried out also.

Important Information: Due to the fact that the performance tests take a long time to complete, it is recommended to start a new test in a screen session.^[1] After the installation a first test run can be started (root privileges are required):

$ sudo tkperf

Without specifying any parameters the following output is returned:

$ sudo tkperf
usage: tkperf [-h] [-v] [-d] [-q] [-nj NUMJOBS] [-iod IODEPTH] [-xml] [-rfb]
              [-dsc DESC_FILE] [-ft] [-fm FEATURE_MATRIX] [-hddt {iops,tp}]
              [-ssdt {iops,lat,tp,writesat}]
              {hdd,ssd} testname device
tkperf: error: too few arguments

The next step is to provide TKperf the desired parameters:

Test type (SSD oder HDD)
Free to choose test name (e.g. Intel320)
Test device path (e.g. /dev/sda)

These three parameters are the basic ones to start a test (with sudo):

$ sudo tkperf ssd Intel320 /dev/sdb
!!!Attention!!!
All data on /dev/sdb will be lost!
Are you sure you want to continue? (In case you really know what you are doing.)
Press 'y' to continue, any key to stop:

or directly as root:

# tkperf ssd Intel320 /dev/sdb

As seen above the user must accept that all data is lost on the test device. Is the target test device is currently mounted the test run will not start!

Other useful Parameters

Most of the times the standard parameters are not sufficient for SSDs. It is good practice to add the following options to a test run:

-nj 2 -iod 16

With these options at least 2 parallel processes with 16 outstanding I/Os each are used by Fio (cf. Fio Basics).

For SSDs with data compression (such as an Intel 520 Series SSD) on more parameter is important. The option -rfb adds refill_buffers to Fio, which guarantees randomness of the data used during a test run:

-nj 2 -iod 16 -rfb

During a Test Run

A log file named '[Free-choosen-test-name].log' contains information about the Fio test runs an occurring errors. Beside the Fio Terse Output at the end of each test a matrix is included in the log file. This matrix is used as a basis for the graphs and reports. Moreover if a test is one of the tests with a steady state, information about how the steady state was reached is printed to the log.

If any doubts about the test results exist it is advisable to check the results in the log file. According the Fio terse output the Fio HOWTO^[2] describes how this output must be interpreted.

After a Test Run

After a test run some graphics, a XML and a RST file are located in the current directory:

# ls
intel320-avg-LAT-mes2DPlt.png    intel320.pdf
intel320-IOPS-mes2DPlt.png       intel320.rst
intel320-IOPS-mes3DPlt.png       intel320-TP-mes2DPlt.png
intel320-IOPS-stdyStConvPlt.png  intel320-TP-RW-stdyStConvPlt.png
intel320-IOPS-stdyStVerPlt.png   intel320-TP-stdyStVerPlt.png
intel320-LAT-mes3DPlt.png        intel320-writeSatIOPSPlt.png
intel320-LAT-stdyStConvPlt.png   intel320-writeSatLatPlt.png
intel320-LAT-stdyStVerPlt.png    intel320.xml
intel320-max-LAT-mes2DPlt.png    intel320.log

TKperf XML File

The XML contains all the results of each test run. Normally it is not necessary to edit this file but in some cases a user can edit custom information to the file. Here is a short extract of an XML test file:

<intel320>
<testdate>"2012-09-26"</testdate>
<devinfo>
"\tModel Number:       INTEL SSDSA2CW160G3                     \n
\tSerial Number:      CVPR1462071K160DGN  
\n\tFirmware Revision:  4PC10362
\n\tdevice size with M = 1000*1000:      160041 MBytes (160 GB)\n"
</devinfo>
<ioperfversion>"1.0"</ioperfversion>
<lat><fioversion>"fio 2.0.7\n"</fioversion><numjobs>2</numjobs><iodepth>16</iodepth>
<roundmat>
[...]
</roundmat>
<tp><fioversion>"fio 2.0.7\n"</fioversion><numjobs>2</numjobs><iodepth>16</iodepth>
<roundmat>
[...]
</roundmat>
<stdyrounds>[0, 1, 2, 3, 4]</stdyrounds>
<stdyvalues>[128655, 122786, 126858, 125772, 126053]</stdyvalues>
<stdyslope>[-221.80000000001655, 126468.40000000001]</stdyslope>
<stdyavg>126024.8</stdyavg>
<reachstdystate>true</reachstdystate>
<rndnr>4</rndnr>
</tp>
</intel320>

Generate TKperf Report

The RST file is used to generate a PDF report file. RST is a markup language restructured Text (wikipedia.org). Another short excerpt:

# head -20 intel320.rst 
.. |logo| image:: TK_Logo_RGB.png
	:height: 70px
.. footer::
	|logo| http://www.thomas-krenn.com - Page ###Page### of ###Total###

====================
IO perf test report
====================

.. contents::
.. sectnum::
.. include:: <isonum.txt>

Device Information
===================
[...]

The command line toole rst2pdf can generate PDFs from RST files:

# rst2pdf intel320.rst

Error Handling

Frozen State

The SSD is in a frozen state, a Secure Erase can not be carried out. Hot-plugging the device should resolve the problem. To check the state:

# hdparm -I /dev/sdb|grep frozen
	not	frozen

Help Output

TKperf supports printing a help text (-h|--help):

$ tkperf -h
usage: tkperf [-h] [-v] [-d] [-q] [-nj NUMJOBS] [-iod IODEPTH] [-xml] [-rfb]
              [-dsc DESC_FILE] [-ft] [-fm FEATURE_MATRIX] [-hddt {iops,tp}]
              [-ssdt {iops,lat,tp,writesat}]
              {hdd,ssd} testname device

positional arguments:
  {hdd,ssd}             specify the test mode for the device
  testname              name of the fio job, corresponds to the result output
                        file
  device                device to run fio test on

optional arguments:
  -h, --help            show this help message and exit
  -v, --version         get the version information
  -d, --debug           get detailed debug information
  -q, --quiet           turn off logging of info messages
  -nj NUMJOBS, --numjobs NUMJOBS
                        specify number of jobs for fio
  -iod IODEPTH, --iodepth IODEPTH
                        specify iodepth for libaio used by fio
  -xml, --fromxml       don't run tests but load test objects from xml file
  -rfb, --refill_buffers
                        use Fio's refill buffers option to circumvent any
                        compression of devices
  -dsc DESC_FILE, --desc_file DESC_FILE
                        use a description file for the tested device if hdparm
                        doesn't work correctly
  -ft, --force_test     skip checks if the used device is mounted, don't print
                        warnings and force starting the test
  -fm FEATURE_MATRIX, --feature_matrix FEATURE_MATRIX
                        add a feature matrix of the given device to the report
  -hddt {iops,tp}, --hdd_type {iops,tp}
                        choose which tests are run
  -ssdt {iops,lat,tp,writesat}, --ssd_type {iops,lat,tp,writesat}
                        choose which tests are run

References

↑ Screen man-Page (linux.die.net)
↑ Fio HOWTO (git.kernel.dk)

Author: Georg Schönberger

[1] Screen man-Page (linux.die.net)

[2] Fio HOWTO (git.kernel.dk)

[1]

[2]