Benchmark syntax

← Back to Documentation

We're going to go through all of the benchmark options to understand all possibilities.

This is a basic benchmark with 2 requests, run 4 plans concurrently against http://example.com servers, executed 5 times. 40 requests in total.

---
concurrency: 4
base: 'http://example.com'
iterations: 5
rampup: 5

plan:
  - name: Fetch users
    request:
      url: /api/users.json

  - name: Fetch organizations
    request:
      url: /api/organizations

Benchmark main properties

  • base: Base url for all relative URL's in your plan. (Optional)
  • iterations: Number of loops is going to do (Optional, default: 1)
  • concurrency: Number of concurrent iterations. (Optional, default: max)
  • rampup: Amount of time it will take to start all iterations. (Optional)
  • plan: List of items to do in your benchmark. (Required)

Plan items

  • include: Include all requests in the given file.
  • request: Execute a HTTP request.
  • assign: Assign a value in the context to be interpolated later.

All those three items can be combined with name property to be show in logs.

Request item properties

  • url: Url to be request for this item
  • headers: List of custom headers you want to add in the requests.
  • method: HTTP method in the requests. Valid methods are GET, POST, PUT, PATCH, HEAD or DELETE. (default: GET)
  • body: Request body for methods like POST, PUT or PATCH.
  • with_items: List of items to be interpolated in the given request url.
  • with_items_range: Generates items from an iterator from start, step (optional, default: 1), stop.
  • with_items_from_csv: Read the given CSV values and go through all of them as items.
  • shuffle: Shuffle given items randomly (default: false).
  • pick: Number of items to pick and perform requests with.
  • assign: Save the response in the context to be interpolated later.
  • tags: List of tags for that item.

with_items_from_csv item properties

This item can be specified one of two ways. First, as a simple string specifying the csv file name.

Second, it can be a hash with the following properties:

  • file_name: csv file containing the records to be used as items
  • quote_char: character to use as quote in csv parsing. Defaults to "\"", but can be set to "'". If your csv file has quoted strings that contain commas and that causes parse errors, make sure this value is set correctly.

body item properties

The body property can be specified in different ways depending on the type of data you want to send in the request. Here are three variants:

  1. body: "string with {{ templates }}"
  • This variant allows you to use a string with templates that can be interpolated with values from the context.
  1. body: { hex: 65 78 61 6D 70 6C 65 }
  • This variant allows you to send a raw byte string value in the request body.
  1. body: { file: path/to/file.txt }
  • This variant allows you to specify a file path, and the content of the file will be used as the request body.

tags item properties

Ansible-like tags.

If you assign list of tags, e.g [tag1, tag2], this item will be executed if tag1 OR tag2 is passed.

Special tags: always and never.

If you assign the always tag, driller will always run that item, unless you specifically skip it (--skip-tags always).

If you assign the never tag to item, driller will skip that item unless you specifically request it (--tags never).

Built-in interpolation variables

In addition to anything you assign, a few variables are always available to {{ }} templates in URLs, headers, and bodies:

  • base: the base URL from the plan (or --base-url).
  • index: a 0-based counter. Inside a with_items / with_items_range / with_items_from_csv / with_items_from_file request it is the position of the current item in that list; in any other request it is the current iteration number. Useful for generating unique paths or payloads per request, e.g. url: /users/{{ index }}. (The value lives in the request context shared by a plan's steps, so a plain request that runs after an items-expanded step in the same plan keeps that step's last item position rather than the iteration number.)
  • iteration: the current iteration number.
  • item: the current item, inside a with_items / with_items_range / with_items_from_csv / with_items_from_file request.