docs/userguide/Yardstick_task_templates.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) OPNFV, Huawei Technologies Co.,Ltd and others.
   5
   6 Task Template Syntax
   7 ====================
   8
   9 Basic template syntax
  10 ---------------------
  11 A nice feature of the input task format used in Yardstick is that it supports
  12 the template syntax based on Jinja2.
  13 This turns out to be extremely useful when, say, you have a fixed structure of
  14 your task but you want to parameterize this task in some way.
  15 For example, imagine your input task file (task.yaml) runs a set of Ping
  16 scenarios:
  17
  18 ::
  19
  20   # Sample benchmark task config file
  21   # measure network latency using ping
  22   schema: "yardstick:task:0.1"
  23
  24   scenarios:
  25   -
  26     type: Ping
  27     options:
  28       packetsize: 200
  29     host: athena.demo
  30     target: ares.demo
  31
  32     runner:
  33       type: Duration
  34       duration: 60
  35       interval: 1
  36
  37     sla:
  38       max_rtt: 10
  39       action: monitor
  40
  41   context:
  42       ...
  43
  44 Let's say you want to run the same set of scenarios with the same runner/
  45 context/sla, but you want to try another packetsize to compare the performance.
  46 The most elegant solution is then to turn the packetsize name into a template
  47 variable:
  48
  49 ::
  50
  51   # Sample benchmark task config file
  52   # measure network latency using ping
  53
  54   schema: "yardstick:task:0.1"
  55   scenarios:
  56   -
  57     type: Ping
  58     options:
  59       packetsize: {{packetsize}}
  60     host: athena.demo
  61     target: ares.demo
  62
  63     runner:
  64       type: Duration
  65       duration: 60
  66       interval: 1
  67
  68     sla:
  69       max_rtt: 10
  70       action: monitor
  71
  72   context:
  73       ...
  74
  75 and then pass the argument value for {{packetsize}} when starting a task with
  76 this configuration file.
  77 Yardstick provides you with different ways to do that:
  78
  79 1.Pass the argument values directly in the command-line interface (with either
  80 a JSON or YAML dictionary):
  81
  82 ::
  83
  84  yardstick task start samples/ping-template.yaml
  85  --task-args'{"packetsize":"200"}'
  86
  87 2.Refer to a file that specifies the argument values (JSON/YAML):
  88
  89 ::
  90
  91  yardstick task start samples/ping-template.yaml --task-args-file args.yaml
  92
  93 Using the default values
  94 ------------------------
  95 Note that the Jinja2 template syntax allows you to set the default values for
  96 your parameters.
  97 With default values set, your task file will work even if you don't
  98 parameterize it explicitly while starting a task.
  99 The default values should be set using the {% set ... %} clause (task.yaml).
 100 For example:
 101
 102 ::
 103
 104   # Sample benchmark task config file
 105   # measure network latency using ping
 106   schema: "yardstick:task:0.1"
 107   {% set packetsize = packetsize or "100" %}
 108   scenarios:
 109   -
 110     type: Ping
 111     options:
 112     packetsize: {{packetsize}}
 113     host: athena.demo
 114     target: ares.demo
 115
 116     runner:
 117       type: Duration
 118       duration: 60
 119       interval: 1
 120     ...
 121
 122 If you don't pass the value for {{packetsize}} while starting a task, the
 123 default one will be used.
 124
 125 Advanced templates
 126 ------------------
 127
 128 Yardstick makes it possible to use all the power of Jinja2 template syntax,
 129 including the mechanism of built-in functions.
 130 As an example, let us make up a task file that will do a block storage
 131 performance test.
 132 The input task file (fio-template.yaml) below uses the Jinja2 for-endfor
 133 construct to accomplish that:
 134
 135 ::
 136
 137   #Test block sizes of 4KB, 8KB, 64KB, 1MB
 138   #Test 5 workloads: read, write, randwrite, randread, rw
 139   schema: "yardstick:task:0.1"
 140
 141    scenarios:
 142   {% for bs in ['4k', '8k', '64k', '1024k' ] %}
 143     {% for rw in ['read', 'write', 'randwrite', 'randread', 'rw' ] %}
 144   -
 145     type: Fio
 146     options:
 147       filename: /home/ubuntu/data.raw
 148       bs: {{bs}}
 149       rw: {{rw}}
 150       ramp_time: 10
 151     host: fio.demo
 152     runner:
 153       type: Duration
 154       duration: 60
 155       interval: 60
 156
 157     {% endfor %}
 158   {% endfor %}
 159   context
 160       ...