diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/release/release-notes/index.rst | 8 | ||||
| -rw-r--r-- | docs/release/release-notes/release-notes.rst | 73 | ||||
| -rwxr-xr-x | docs/testing/user/installation.rst | 38 | ||||
| -rw-r--r-- | docs/testing/user/introduction.rst | 229 | ||||
| -rw-r--r-- | docs/testing/user/test-usage.rst | 257 |
5 files changed, 530 insertions, 75 deletions
diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst index bf71c6c..6122cf0 100644 --- a/docs/release/release-notes/index.rst +++ b/docs/release/release-notes/index.rst @@ -1,11 +1,13 @@ .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 -**************************** +.. _storperf-releasenotes: + +********************** StorPerf Release Notes -**************************** +********************** .. toctree:: :maxdepth: 2 - release-notes + release-notes.rst diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index 91e5666..0303fb4 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -2,7 +2,7 @@ .. http://creativecommons.org/licenses/by/4.0 -This document provides the release notes for Fraser 2.0 of StorPerf. +This document provides the release notes for Iruya 1.0 of StorPerf. .. contents:: :depth: 3 @@ -17,7 +17,7 @@ Version history | **Date** | **Ver.** | **Author** | **Comment** | | | | | | +--------------------+--------------------+--------------------+--------------------+ -| 2018-06-29 | Fraser 3.0 | Mark Beierl | | +| 2020-01-10 | Iruya 1.0 | Mark Beierl | | | | | | | +--------------------+--------------------+--------------------+--------------------+ @@ -25,11 +25,14 @@ Version history Important notes ---------------- -StorPerf has added the ability to specify the number of Cinder Volumes per -agent VM to test. The name of the device that the volume is attached to -has been appended to the host IP address in the metrics so that it can be -tracked independently. +Heat stack support is being sunsetted in StorPerf Iruya. Once Kali is released, +StorPerf will no longer support the following APIs: +/configurations +/quota + +Additionally, the stack_name parameter will no longer be used. This also means +that all tests must run using IP addresses. Summary -------- @@ -38,22 +41,10 @@ StorPerf is a standalone framework that uses OpenStack to measure Cinder volume performance. If desired, it can push results to the OPNFV Test Results DB, or the embedded Graphite web interface can be used to perform ad hoc queries. -This release allows for changing of stack attributes from the OpenStack CLI. -Using a command such as - -.. code-block:: - heat stack-update StorPerfAgentGroup --existing -P "agent_count=6" - -will change the existing stack to use 6 agents. Note that StorPerf can take -up to 1 minute after the stack update is complete before detecting the new -values. Please use a GET of the configurations API to test for updated -values prior to submitting a new test. - -The following command changes the number of volumes per agent: - -.. code-block:: - heat stack-update StorPerfAgentGroup --existing -P "volume_count=2" - +This release provides the ability to use existing servers (virtual or physical) +as the targets for workload execution. All that is required is the IP address +and the SSH key or username/password for StorPerf to be able to log in and +start FIO workloads. Release Data ------------- @@ -62,17 +53,17 @@ Release Data | **Project** | StorPerf | | | | +--------------------------------------+--------------------------------------+ -| **Repo/tag** | opnfv-6.2.0 | +| **Repo/tag** | opnfv-9.0.0 | | | | +--------------------------------------+--------------------------------------+ -| **Release designation** | Fraser 6.2 | +| **Release designation** | Iruya.9 | | | | +--------------------------------------+--------------------------------------+ -| **Release date** | June 29 2018 | +| **Release date** | Jan 10, 2020 | | | | +--------------------------------------+--------------------------------------+ -| **Purpose of the delivery** | Improvements to stack detection | -| | speed. | +| **Purpose of the delivery** | Regular release | +| | | +--------------------------------------+--------------------------------------+ Version change @@ -81,24 +72,23 @@ Version change Module version changes ----------------------- -No changes to any modules. +All modules have been upgraded to use python3. Reason for version =================== -* Loading stack properties from OpenStack could take minutes or longer - depending on the stack size. This version includes changes from SNAPS - to take advantage of parallel OpenStack object lookups. +* Timed release schedule Features additions ------------------- -* STORPERF-239 - Add IP addresses of slaves to configurations API -* STORPERF-245 - Change to use multithreaded SNAPS +* STORPERF-268 Allow user to specify list of IP addresses for StorPerf test Bug Fixes ---------- +None + Deliverables ============= @@ -106,25 +96,28 @@ Software --------- - `StorPerf master image <https://hub.docker.com/r/opnfv/storperf-master/>`_ - (tag: x86_64-fraser.2.0 or aarch64-fraser.2.0) + (tag: x86_64-opnfv-8.0.0 or aarch64-opnfv-8.0.0) - `StorPerf swaggerui <https://hub.docker.com/r/opnfv/storperf-swaggerui/>`_ - (tag: x86_64-fraser.2.0 or aarch64-fraser.2.0) + (tag: x86_64-opnfv-8.0.0 or aarch64-opnfv-8.0.0) - `StorPerf graphite image <https://hub.docker.com/r/opnfv/storperf-graphite/>`_ - (tag: x86_64-fraser.2.0 or aarch64-fraser.2.0) + (tag: x86_64-opnfv-8.0.0 or aarch64-opnfv-8.0.0) - `StorPerf reporting image <https://hub.docker.com/r/opnfv/storperf-reporting/>`_ - (tag: x86_64-fraser.2.0 or aarch64-fraser.2.0) + (tag: x86_64-opnfv-8.0.0 or aarch64-opnfv-8.0.0) - `StorPerf Http-Frontend image <https://hub.docker.com/r/opnfv/storperf-httpfrontend/>`_ - (tag: x86_64-fraser.2.0 or aarch64-fraser.2.0) + (tag: x86_64-opnfv-8.0.0 or aarch64-opnfv-8.0.0) Documentation -------------- - :ref:`User Guide <storperf-userguide>` +Note: The quotas and configurations apis are being sunsetted with the next +release. + Known Limitations, Issues and Workarounds ------------------------------------------ @@ -148,7 +141,3 @@ Known issues --property hw_disk_bus=scsi --property hw_scsi_model=virtio-scsi -Test Result -=========== - -- `OPNFV Test Results DB <http://testresults.opnfv.org/reporting/fraser/storperf/status-apex.html>`_ diff --git a/docs/testing/user/installation.rst b/docs/testing/user/installation.rst index c129fee..7f56244 100755 --- a/docs/testing/user/installation.rst +++ b/docs/testing/user/installation.rst @@ -8,11 +8,20 @@ StorPerf Installation Guide OpenStack Prerequisites =========================== -If you do not have an Ubuntu 16.04 image in Glance, you will need to add one. -You also need to create the StorPerf flavor, or choose one that closely -matches. For Ubuntu 16.04, it must have a minimum of a 4 GB disk. It should -also have about 8 GB RAM to support FIO's memory mapping of written data blocks -to ensure 100% coverage of the volume under test. +StorPerf can be instructed to use OpenStack APIs in order to manage a +Heat stack of virtual machines and Cinder volumes, or it can be run in +stackless mode, where it does not need to know anything about OpenStack. + +When running in OpenStack mode, there will need to be an external network +with floating IPs available to assign to the VMs, as well as a Glance image +that can be used to boot the VMs. This can be almost any Linux based +image, as long as it can either accept OpenStack metadata for injecting +the SSH key, or it has known SSH credentials as part of the base image. + +The flavor for the image should provide enough disk space for the initial +boot, along with additional space if profiling of the Glance backing is +desired. It should also provide at least 8 GB RAM to support FIO's memory +mapping of written data blocks. There are scripts in storperf/ci directory to assist, or you can use the follow code snippets: @@ -34,9 +43,10 @@ code snippets: OpenStack Credentials ~~~~~~~~~~~~~~~~~~~~~ -You must have your OpenStack Controller environment variables defined and passed to -the StorPerf container. The easiest way to do this is to put the rc file contents -into a clean file called admin.rc that looks similar to this for V2 authentication: +Unless running in stackless mode, the OpenStack Controller environment +variables must be defined and passed to the StorPerf container. The easiest +way to do this is to put the rc file contents into a clean file called +admin.rc that looks similar to this for V2 authentication: .. code-block:: console @@ -89,7 +99,7 @@ Requirements: * Host has access to the OpenStack Controller API * Host must have internet connectivity for downloading docker image * Enough OpenStack floating IPs must be available to match your agent count -* A local directory for holding the Carbon DB Whisper files +* Optionally, a local directory for holding the Carbon DB Whisper files Local disk used for the Carbon DB storage as the default size of the docker container is only 10g. Here is an example of how to create a local storage @@ -117,7 +127,7 @@ http://storperf:5000/graphite Running StorPerf Container ========================== -**As of Euphrates (development) release (June 2017), StorPerf has +**As of Euphrates release (June 2017), StorPerf has changed to use docker-compose in order to start its services.** Docker compose requires a local file to be created in order to define the @@ -146,8 +156,12 @@ which should result in: To run, you must specify two environment variables: -* ENV_FILE, which points to your OpenStack admin.rc as noted above. -* CARBON_DIR, which points to a directory that will be mounted to store the raw metrics. +* ENV_FILE, which points to your OpenStack admin.rc as noted above. If running + in stackless mode only, it is possible to remove the ENV_FILE reference from + the docker-compose.yaml file. +* CARBON_DIR, which points to a directory that will be mounted to store the + raw metrics. If desired, the CARBON_DIR can be removed from the + docker-compose.yaml file, causing metrics to be kept in the container only. * TAG, which specified the Docker tag for the build (ie: latest, danube.3.0, etc). The following command will start all the StorPerf services: diff --git a/docs/testing/user/introduction.rst b/docs/testing/user/introduction.rst index 49e3220..c864edc 100644 --- a/docs/testing/user/introduction.rst +++ b/docs/testing/user/introduction.rst @@ -25,18 +25,18 @@ performance metrics in the shortest reasonable time. How Does StorPerf Work? ======================= -Once launched, StorPerf presents you with a ReST interface, along with a +Once launched, StorPerf presents a ReST interface, along with a `Swagger UI <https://swagger.io/swagger-ui/>`_ that makes it easier to -form HTTP ReST requests. Issuing an HTTP POST to the configurations API -causes StorPerf to talk to your OpenStack's heat service to create a new stack -with as many agent VMs and attached Cinder volumes as you specify. +form HTTP ReST requests. -After the stack is created, you can issue one or more jobs by issuing a POST -to the jobs ReST API. The job is the smallest unit of work that StorPerf -can use to measure the disk's performance. +StorPerf enables us to run FIO on multiple VMs, containers or bare +metal servers by providing a recent release of FIO, copying it to the +target system and running I/O workloads specified. It also provides a +simple API to initialize the target device and fill it with random data +to ensure that performance is measured against real data, not blank media. -While the job is running, StorPerf collects the performance metrics from each -of the disks under test every minute. Once the trend of metrics match the +While an FIO job is running, StorPerf collects the performance metrics from +each of the jobs every minute. Once the trend of metrics match the criteria specified in the SNIA methodology, the job automatically terminates and the valid set of metrics are available for querying. @@ -45,8 +45,210 @@ measured start to "flat line" and stay within that range for the specified amount of time, then the metrics are considered to be indicative of a repeatable level of performance. -What Data Can I Get? -==================== +With OpenStack Heat +~~~~~~~~~~~~~~~~~~~ + +StorPerf provides an API to interact with OpenStack Heat to automatically +create a set of target VMs and Cinder volumes. The Configurations API is +used to specify how many VMs and volumes to create, as well as the size of +each Cinder volume. + +Without OpenStack Heat +~~~~~~~~~~~~~~~~~~~~~~ + +StorPerf can also use IP addresses or DNS names to connect to systems that +have already been provisioned by any external provider, including OpenStack. +By specifying a stack name of 'null' in the JSON payload, StorPerf will look +for a list of IP addresses and credentials to use in order to SSH to the +target systems. In this way, StorPerf can be used to profile bare metal, +containers that have SSH enabled, or VMs running under OpenStack, WMware ESXi, +VIO, Microsoft Hyper-V, or anything else. The only requirement is that +the target be capable of accepting and authenticating SSH connections, and that +it is Linux based, as currently the FIO supplied by StorPerf is not compiled +to run under Microsoft Windows or other non-Linux operating systems. + + +StorPerf Testing Guidelines +=========================== + +First of all, StorPerf is not able to give pointers on how to tune a +Cinder implementation, as there are far too many backends (Ceph, NFS, LVM, +etc), each with their own methods of tuning. StorPerf is here to assist in +getting a reliable performance measurement by encoding the test +specification from SNIA, and helping present the results in a way that makes +sense. + +Having said that, there are some general guidelines that we can present to +assist with planning a performance test. + +Workload Modelling +------------------ + +This is an important item to address as there are many parameters to how +data is accessed. Databases typically use a fixed block size and tend to +manage their data so that sequential access is more likely. GPS image tiles +can be around 20-60kb and will be accessed by reading the file in full, with +no easy way to predict what tiles will be needed next. Some programs are +able to submit I/O asynchronously where others need to have different threads +and may be synchronous. There is no one size fits all here, so knowing what +type of I/O pattern we need to model is critical to getting realistic +measurements. + +System Under Test +----------------- + +The unfortunate part is that StorPerf does not have any knowledge about the +underlying OpenStack itself – we can only see what is available through +OpenStack APIs, and none of them provide details about the underlying +storage implementation. As the test executor, we need to know +information such as: the number of disks or storage nodes; the amount of RAM +available for caching; the type of connection to the storage and bandwidth +available. + +Measure Storage, not Cache +-------------------------- + +As part of the test data size, we need to ensure that we prevent +caching from interfering in the measurements. The total size of the data +set in the test must exceed the total size of all the disk cache memory +available by a certain amount in order to ensure we are forcing non-cached +I/O. There is no exact science here, but if we balance test duration against +cache hit ratio, it can be argued that 20% cache hit is good enough and +increasing file size would result in diminishing returns. Let’s break this +number down a bit. Given a cache size of 10GB, we could write, then read the +following dataset sizes: + +* 10GB gives 100% cache hit +* 20GB gives 50% cache hit +* 50GB gives 20% cache hit +* 100GB gives 10% cache hit + +This means that for the first test, 100% of the results are unreliable due to +cache. At 50GB, the true performance without cache has only a 20% margin of +error. Given the fact that the 100GB would take twice as long, and that we +are only reducing the margin of error by 10%, we recommend this as the best +tradeoff. + +How much cache do we actually have? This depends on the storage device being +used. For hardware NAS or other arrays, it should be fairly easy to get the +number from the manufacturer, but for software defined storage, it can be +harder to determine. Let’s take Ceph as an example. Ceph runs as software +on the bare metal server and therefore has access to all the RAM available on +the server to use as its cache. Well, not exactly all the memory. We have +to take into account the memory consumed by the operating system, by the Ceph +processes, as well as any other processes running on the same system. In the +case of hyper-converged Ceph, where workload VMs and Ceph run on the systems, +it can become quite difficult to predict. Ultimately, the amount of memory +that is left over is the cache for that single Ceph instance. We now need to +add the memory available from all the other Ceph storage nodes in the +environment. Time for another example: given 3 Ceph storage nodes with +256GB RAM each. Let’s take 20% off to pin to the OS and other processes, +leaving approximately 240GB per node This gives us 3 x 240 or 720GB total RAM +available for cache. The total amount of data we want to write in order to +initialize our Cinder volumes would then be 5 x 720, or 3,600 GB. The +following illustrates some ways to allocate the data: + +* 1 VM with 1 3,600 GB volume +* 10 VMs each with 1 360 GB volume +* 2 VMs each with 5 360 GB volumes + +Back to Modelling +----------------- + +Now that we know there is 3.6 TB of data to be written, we need to go back to +the workload model to determine how we are going to write it. Factors to +consider: + +* Number of Volumes. We might be simulating a single database of 3.6 TB, so + only 1 Cinder volume is needed to represent this. Or, we might be + simulating a web server farm where there are hundreds of processes + accessing many different volumes. In this case, we divide the 3.6 TB by + the number of volumes, making each volume smaller. +* Number of Virtual Machines. We might have one monster VM that will drive + all our I/O in the system, or maybe there are hundreds of VMs, each with + their own individual volume. Using Ceph as an example again, we know that + it allows for a single VM to consume all the Ceph resources, which can be + perceived as a problem in terms of multi-tenancy and scaling. A common + practice to mitigate this is to use Cinder to throttle IOPS at the VM + level. If this technique is being used in the environment under test, we + must adjust the number of VMs used in the test accordingly. +* Block Size. We need to know if the application is managing the volume as a + raw device (ie: /dev/vdb) or as a filesystem mounted over the device. + Different filesystems have their own block sizes: ext4 only allows 1024, + 2048 or 4096 as the block size. Typically the larger the block, the better + the throughput, however as blocks must be written as an atomic unit, larger + block sizes can also reduce effective throughput by having to pad the block + if the content is smaller than the actual block size. +* I/O Depth. This represents the amount of I/O that the application can + issue simultaneously. In a multi-threaded app, or one that uses + asynchronous I/O, it is possible to have multiple read or write requests + outstanding at the same time. For example, with software defined storage + where there is an Ethernet network between the client and the storage, + the storage would have a higher latency for each I/O, but is capable of + accepting many requests in parallel. With an I/O depth of 1, we spend + time waiting for the network latency before a response comes back. With + higher I/O depth, we can get more throughput despite each I/O having higher + latency. Typically, we do not see applications that would go beyond a + queue depth of 8, however this is not a firm rule. +* Data Access Pattern. We need to know if the application typically reads + data sequentially or randomly, as well as what the mixture of read vs. + write is. It is possible to measure read by itself, or write by itself, + but this is not typical behavior for applications. It is useful for + determining the potential maximum throughput of a given type of operation. + +Fastest Path to Results +----------------------- + +Once we have the information gathered, we can now start executing some tests. +Let’s take some of the points discussed above and describe our system: + +* OpenStack deployment with 3 Control nodes, 5 Compute nodes and 3 dedicated + Ceph storage nodes. +* Ceph nodes each have 240 GB RAM available to be used as cache. +* Our application writes directly to the raw device (/dev/vdb) +* There will be 10 instances of the application running, each with its own + volume. +* Our application can use block sizes of 4k or 64k. +* Our application is capable of maintaining up to 6 I/O operations + simultaneously. + +The first thing we know is that we want to keep our cache hit ratio around +20%, so we will be moving 3,600 GB of data. We also know this will take a +significant amount of time, so here is where StorPerf helps. + +First, we use the configurations API to launch our 10 virtual machines each +with a 360 GB volume. Next comes the most time consuming part: we call the +initializations API to fill each one of these volumes with random data. By +preloading the data, we ensure a number of things: + +* The storage device has had to fully allocate all of the space for our + volumes. This is especially important for software defined storage like + Ceph, which is smart enough to know if data is being read from a block that + has never been written. No data on disk means no disk read is needed and + the response is immediate. +* The RAM cache has been overrun multiple times. Only 20% of what was + written can possibly remain in cache. + +This last part is important as we can now use StorPerf’s implementation of +SNIA’s steady state algorithm to ensure our follow up tests execute as +quickly as possible. Given the fact that 80% of the data in any given test +results in a cache miss, we can run multiple tests in a row without having +to re-initialize or invalidate the cache again in between test runs. We can +also mix and match the types of workloads to be run in a single performance +job submission. + +Now we can submit a job to the jobs API to execute a 70%/30% mix of +read/write, with a block size of 4k and an I/O queue depth of 6. This job +will run until either the maximum time has expired, or until StorPerf detects +steady state has been reached, at which point it will immediately complete +and report the results of the measurements. + +StorPerf uses FIO as its workload engine, so whatever workload parameters we +would like to use with FIO can be passed directly through via StorPerf’s jobs +API. + +What Data Can We Get? +===================== StorPerf provides the following metrics: @@ -57,4 +259,9 @@ StorPerf provides the following metrics: These metrics are available for every job, and for the specific workloads, I/O loads and I/O types (read, write) associated with the job. +For each metric, StorPerf also provides the set of samples that were +collected along with the slope, min and max values that can be used for +plotting or comparison. + As of this time, StorPerf only provides textual reports of the metrics. + diff --git a/docs/testing/user/test-usage.rst b/docs/testing/user/test-usage.rst index 41cbbbd..0fb3a6c 100644 --- a/docs/testing/user/test-usage.rst +++ b/docs/testing/user/test-usage.rst @@ -31,8 +31,17 @@ The typical test execution follows this pattern: #. Execute one or more performance runs #. Delete the environment -Configure The Environment -========================= +OpenStack or Stackless +====================== +StorPerf provides the option of controlling the OpenStack environment +via a Heat Stack, or it can run in stackless mode, where it connects +directly to the IP addresses supplied, regardless of how the slave +was created or even if it is an OpenStack VM. + +Note: Stack support in StorPerf will be deprecated as of the next release. + +Configure The Environment for OpenStack Usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following pieces of information are required to prepare the environment: @@ -51,12 +60,12 @@ The following pieces of information are required to prepare the environment: VMs from properly attaching Cinder volumes. There are two known workarounds: #. Create the environment with 0 Cinder volumes attached, and after the VMs - have finished booting, modify the stack to have 1 or more Cinder volumes. - See section on Changing Stack Parameters later in this guide. + have finished booting, modify the stack to have 1 or more Cinder volumes. + See section on Changing Stack Parameters later in this guide. #. Add the following image metadata to Glance. This will cause the Cinder - volume to be mounted as a SCSI device, and therefore your target will be - /dev/sdb, etc, instead of /dev/vdb. You will need to specify this in your - warm up and workload jobs. + volume to be mounted as a SCSI device, and therefore your target will be + /dev/sdb, etc, instead of /dev/vdb. You will need to specify this in your + warm up and workload jobs. .. code-block: --property hw_disk_bus=scsi --property hw_scsi_model=virtio-scsi @@ -83,6 +92,52 @@ takes a JSON payload as follows. This call will block until the stack is created, at which point it will return the OpenStack heat stack id as well as the IP addresses of the slave agents. + +Configure The Environment for Stackless Usage +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To configure the environment for stackless usage, the slaves must be +fully operational (ie: a Linux operating system is running, are reachable +via TCP/IP address or hostname). + +It is not necessary to use the Configurations API, but instead define the +stack name as 'null' in any of the other APIs. This instructs StorPerf not to +gather information about the stack from OpenStack, and to simply use the +supplied IP addresses and credentials to communicate with the slaves. + +A slave can be a container (provided we can SSH to it), a VM running in any +hypervisor, or even a bare metal server. In the bare metal case, it even +allows for performing RADOS or RDB performance tests using the appropriate +FIO engine. + +If the slave SSH server is listening to a port other than 22, the port number +can be specified as part of the address as follows: + +IPv4 example for port 2222: + +.. code-block:: + 192.168.1.10:2222 + +IPv6 example for port 2222: + +.. code-block:: + [1fe80::58bb:c8b:f2f2:c888]:2222 + +Helper Container Image for Workloads +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A new docker container is provided with StorPerf that can be used to test +under docker or Kubernetes environments. It has hard coded credentials +of root/password with an SSH server built it, so be cautious about security +concerns when using this image. It listens internally on port 22, so that +port must be exposed to a free port on the host in order for StorPerf to +reach the synthetic workload container. + +.. code-block:: bash + + docker run --name=storperf-workloadagent -p 2222:22 + opnfv/storperf-workloadagent:latest + Initialize the Target Volumes ============================= Before executing a test run for the purpose of measuring performance, it is @@ -120,6 +175,137 @@ This will return a job ID as follows. This job ID can be used to query the state to determine when it has completed. See the section on querying jobs for more information. +Authentication and Slave Selection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +It is possible to run the Initialization API against a subset of the slaves +known to the stack, or to run it in stackless mode, where StorPerf +connects directly to the IP addresses supplied via SSH. The following +keys are available: + +slave_addresses + (optional) A list of IP addresses or hostnames to use as targets. If + omitted, and StorPerf is not running in stackless mode, the full list of + IP addresses from the OpenStack Heat stack is used. + +stack_name + (optional) Either the name of the stack in Heat to use, or null if running + in stackless mode. + +username + (optional) The username to supply to SSH when logging in. This defaults to + 'storperf' if not supplied. + +password + (optional) The password to supply to SSH when logging in. If omitted, the + SSH key is used instead. + +ssh_private_key + (optional) The SSH private key to supply to SSH when logging in. If omitted, + the default StorPerf private key is used. + +This shows an example of stackless mode going against a single bare metal +server reachable by IP address: + +.. code-block:: json + + { + "username": "labadmin", + "ssh_private_key": "-----BEGIN RSA PRIVATE KEY----- \nMIIE...X0=\n-----END RSA PRIVATE KEY-----", + "slave_addresses": [ + "172.17.108.44" + ], + "stack_name": null, + } + + +Filesystems and Mounts +~~~~~~~~~~~~~~~~~~~~~~ + +It is also possible to instruct StorPerf to create a file system on a device +and mount that as the target directory. The filesystem can be anything +supported by the target slave OS and it is possible to pass specific arguments +to the mkfs command. The following additional keys are available in the +Initializations API for file system control: + +mkfs + The type and arguments to pass for creating a filesystem + +mount_device + The target device on which to make the file system. The file system will + be mounted on the target specified. + +The following example shows the forced creation (-f) of an XFS filesystem +on device /dev/sdb, and mounting that device on /storperf/filesystem. + +**Note** If any of the commands (mkfs, mount) fail for any reason, the +Initializations API will return with a 400 code and the body of the response +will contain the error message. + +.. code-block:: json + + { + "target": "/storperf/filesystem", + "mkfs": "xfs -f", + "mount_device": "/dev/sdb", + } + + +Initializing Filesystems +~~~~~~~~~~~~~~~~~~~~~~~~ + +Just like we need to fill Cinder volumes with data, if we want to profile +files on a mounted file system, we need to initialize the file sets with +random data prior to starting a performance run. The Initializations API +can also be used to create test data sets. + +**Note** be sure to use the same parameters for the number of files, sizes +and jobs in both the Initializations API and the Jobs API, or you will end +up with possibly incorrect results in the Job performance run. + +The following keys are available in the Initializations API for file creation: + +filesize + The size of each file to be created and filled with random data. + +nrfiles + The number of files per job to create. + +numjobs + The number of independent instances of FIO to launch. + +Example: + +.. code-block:: json + + { + "target": "/storperf/filesystem", + "filesize": "2G", + "nrfiles": 10, + "numjobs": 10 + } + +This would create 100 (10 nrfiles x 10 numjobs) 2G files in the directory +/storperf/filesystem. + + +.. code-block:: json + + { + "username": "labadmin", + "ssh_private_key": "-----BEGIN RSA PRIVATE KEY----- \nMIIE...X0=\n-----END RSA PRIVATE KEY-----", + "slave_addresses": [ + "172.17.108.44" + ], + "stack_name": null, + "target": "/storperf/filesystem", + "mkfs": "ext4", + "mount_device": "/dev/sdb", + "filesize": "2G", + "nrfiles": 10, + "numjobs": 10 + } + + Execute a Performance Run ========================= Performance runs can execute either a single workload, or iterate over a matrix @@ -221,6 +407,63 @@ StorPerf will also do a verification of the arguments given prior to returning a Job ID from the ReST call. If an argument fails validation, the error will be returned in the payload of the response. +File System Profiling +~~~~~~~~~~~~~~~~~~~~~ + +As noted in the Initializations API, files in a file system should be +initialized prior to executing a performance run, and the number of jobs, +files and size of files should match the initialization. Given the following +Initializations API call: + +.. code-block:: json + + { + "username": "labadmin", + "ssh_private_key": "-----BEGIN RSA PRIVATE KEY----- \nMIIE...X0=\n-----END RSA PRIVATE KEY-----", + "slave_addresses": [ + "172.17.108.44" + ], + "stack_name": null, + "target": "/storperf/filesystem", + "mkfs": "ext4", + "mount_device": "/dev/sdb", + "filesize": "2G", + "nrfiles": 10, + "numjobs": 10 + } + +The corresponding call to the Jobs API would appear as follows: + +.. code-block:: json + + { + "username": "labadmin", + "ssh_private_key": "-----BEGIN RSA PRIVATE KEY----- \nMIIE...X0=\n-----END RSA PRIVATE KEY-----", + "slave_addresses": [ + "172.17.108.44" + ], + "stack_name": null, + "target": "/storperf/filesystem", + "block_sizes": "4k", + "queue_depths": "8", + "workloads": { + "readwritemix": { + "rw": "rw", + "filesize": "2G", + "nrfiles": "10", + "numjobs": "10" + } + } + } + +**Note** the queue depths and block sizes as well as the I/O pattern (rw) +can change, but the filesize, nrfiles, numjobs and slave addresses must +match the initialization or the performance run could contain skewed results +due to disk initialization. StorPerf explicitly allows for the mismatch +of these so that it is possible to visualize performance when the files +or disks have not been properly initialized. + + Block Sizes ~~~~~~~~~~~ A comma delimited list of the different block sizes to use when reading and |