diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/index.rst | 56 | ||||
| -rwxr-xr-x | docs/source/templates/Yardstick_task_templates.rst | 141 | ||||
| -rw-r--r-- | docs/source/templates/testcase_description_template.rst | 88 |
3 files changed, 285 insertions, 0 deletions
diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 000000000..072b179c8 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,56 @@ +.. OPNFV Yardstick documentation master file. + Add chapters and user guides using the + root `toctree` directive. + +.. image:: ../etc/opnfv-logo.png + :height: 40 + :width: 200 + :alt: OPNFV + :align: left + +================= +Yardstick Project +================= + +Welcome to Yardstick's documentation ! + +.. _Yardstick: https://wiki.opnfv.org/yardstick + +Yardstick_ is an OPNFV testing project. + +The project goal is to verify infrastructure compliance, from the perspective +of a VNF. + +The project scope is the development of a test framework, test cases and test +stimuli. + +This document introduces the methodology applied in Yardstick_ project, which +decomposes typical VNF work-load performance metrics into a number of +characteristics/performance vectors, each of them can be represented by +distinct test-cases. + +The user guides and test cases delivered for the release are included. + +Contents: + +Yardstick Project Description +============================= + +.. toctree:: + :numbered: + :maxdepth: 2 + +User Guides +=========== + +.. toctree:: + :maxdepth: 1 + +Indices +======= + +* :ref:`search` + +Revision: _sha1_ + +Build date: |today| diff --git a/docs/source/templates/Yardstick_task_templates.rst b/docs/source/templates/Yardstick_task_templates.rst new file mode 100755 index 000000000..538937fd7 --- /dev/null +++ b/docs/source/templates/Yardstick_task_templates.rst @@ -0,0 +1,141 @@ +Task Template Syntax +==================== + +Basic template syntax +--------------------- +A nice feature of the input task format used in Yardstick is that it supports the template syntax based on Jinja2. +This turns out to be extremely useful when, say, you have a fixed structure of your task but you want to +parameterize this task in some way. +For example, imagine your input task file (task.yaml) runs a set of Ping scenarios: + +:: + + # Sample benchmark task config file + # measure network latency using ping + schema: "yardstick:task:0.1" + + scenarios: + - + type: Ping + options: + packetsize: 200 + host: athena.demo + target: ares.demo + + runner: + type: Duration + duration: 60 + interval: 1 + + sla: + max_rtt: 10 + action: monitor + + context: + ... + +Let's say you want to run the same set of scenarios with the same runner/context/sla, +but you want to try another packetsize to compare the performance. +The most elegant solution is then to turn the packetsize name into a template variable: + +:: + + # Sample benchmark task config file + # measure network latency using ping + + schema: "yardstick:task:0.1" + scenarios: + - + type: Ping + options: + packetsize: {{packetsize}} + host: athena.demo + target: ares.demo + + runner: + type: Duration + duration: 60 + interval: 1 + + sla: + max_rtt: 10 + action: monitor + + context: + ... + +and then pass the argument value for {{packetsize}} when starting a task with this configuration file. +Yardstick provides you with different ways to do that: + +1.Pass the argument values directly in the command-line interface (with either a JSON or YAML dictionary): + +:: + + yardstick task start samples/ping-template.yaml --task-args '{"packetsize": "200"}' + +2.Refer to a file that specifies the argument values (JSON/YAML): + +:: + + yardstick task start samples/ping-template.yaml --task-args-file args.yaml + +Using the default values +------------------------ +Note that the Jinja2 template syntax allows you to set the default values for your parameters. +With default values set, your task file will work even if you don't parameterize it explicitly while starting a task. +The default values should be set using the {% set ... %} clause (task.yaml).For example: + +:: + + # Sample benchmark task config file + # measure network latency using ping + schema: "yardstick:task:0.1" + {% set packetsize = packetsize or "100" %} + scenarios: + - + type: Ping + options: + packetsize: {{packetsize}} + host: athena.demo + target: ares.demo + + runner: + type: Duration + duration: 60 + interval: 1 + ... + +If you don't pass the value for {{packetsize}} while starting a task, the default one will be used. + +Advanced templates +------------------ +Yardstick makes it possible to use all the power of Jinja2 template syntax, including the mechanism of built-in functions. +As an example, let us make up a task file that will do a block storage performance test. +The input task file (fio-template.yaml) below uses the Jinja2 for-endfor construct to accomplish that: + +:: + + #Test block sizes of 4KB, 8KB, 64KB, 1MB + #Test 5 workloads: read, write, randwrite, randread, rw + schema: "yardstick:task:0.1" + + scenarios: + {% for bs in ['4k', '8k', '64k', '1024k' ] %} + {% for rw in ['read', 'write', 'randwrite', 'randread', 'rw' ] %} + - + type: Fio + options: + filename: /home/ec2-user/data.raw + bs: {{bs}} + rw: {{rw}} + ramp_time: 10 + host: fio.demo + runner: + type: Duration + duration: 60 + interval: 60 + + {% endfor %} + {% endfor %} + context + ... diff --git a/docs/source/templates/testcase_description_template.rst b/docs/source/templates/testcase_description_template.rst new file mode 100644 index 000000000..899554dec --- /dev/null +++ b/docs/source/templates/testcase_description_template.rst @@ -0,0 +1,88 @@ +.. NOTE:: + Template to be used for test case descriptions in Yardstick Project. + Write one .rst per test case. + Upload the .rst for the test case in /docs directory. Review in Gerrit. + +****************** +Test Case <slogan> +****************** + +.. contents:: Table of Contents + :depth: 3 + +--------------------- +Test Case Description +--------------------- + +Yardstick Test Case ID +---------------------- + +OPNFV_YARDSTICK_TC<abc>_<slogan> + +where: + - <abc>: check Jira issue for the test case + - <slogan>: check Jira issue for the test case + + +Purpose +------- + +Describe what is the purpose of the test case + +Area +---- + +State the area and sub-area covered by the test case. + +Areas: Compute, Networking, Storage + +Sub-areas: Performance, System limit, QoS + +Metrics +------- + +What will be measured, attribute name or collection of attributes, behavior + +References +---------- + +Reference documentation + +-------------- +Pre-requisites +-------------- + +Tools +----- + +What tools are used to perform the measurements (e.g. fio, pktgen) + + +Configuration +------------- + +State the .yaml file to use. + +State default configuration in the tool(s) used to perform the measurements (e.g. fio, pktgen). + +State what POD-specific configuration is required to enable running the test case in different PODs. + +State SLA, if applicable. + +State test duration. + +------- +Results +------- + +Expected outcome +---------------- + +State applicable graphical presentation + +State applicable output details + +State expected Value, behavior, pass/fail criteria + + + |