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