docs/configguide/yardstick_testcases/Yardstick_task_templates.rst

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