Getting started

Install

From crates.io, with a Rust toolchain:

cargo install driller

Or download a prebuilt binary for Linux, macOS, or Windows from the latest release.

To build from source:

git clone https://github.com/zoosky/driller.git && cd driller
cargo build --release
./target/release/driller --version

Driller links against OpenSSL for TLS. When building from source, install the development headers for your platform first:

Platform	Command
Debian / Ubuntu	apt install libssl-dev pkg-config
Fedora / RHEL	dnf install openssl-devel
macOS (Homebrew)	brew install openssl
Windows (vcpkg)	vcpkg install openssl:x64-windows-static-md

Run an ad-hoc test

Point driller at a URL. Without a plan file it sends a single GET request to the target:

driller run http://localhost:3000/health

Add concurrency, iterations, and statistics:

# 10 concurrent users, 100 iterations, latency percentiles at the end
driller run http://localhost:3000/api -p 10 -i 100 --stats

# Loop for 30 seconds instead of a fixed iteration count
driller run http://localhost:3000/api --duration 30s --concurrency 10 --stats

The URL must include a scheme (http:// or https://). Pass - in place of the URL to read the target from standard input.

Write a benchmark plan

A plan is a YAML file with a plan: list of steps. Create benchmark.yml:

---
concurrency: 4
base: 'http://localhost:9000'
iterations: 5
rampup: 2

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

  - name: Fetch account
    request:
      url: /api/account
    assign: account

  - name: Fetch manager
    request:
      url: /api/users/{{ account.body.manager_id }}

  - name: Assert status
    assert:
      key: account.status
      value: 200

  - name: Create order
    request:
      url: /api/orders
      method: POST
      body: '{"user": {{ account.body.id }}}'
      headers:
        Content-Type: application/json

Run it:

driller run --benchmark benchmark.yml --stats

Command-line flags override values from the file, so the same plan can run against another environment with more load:

driller run --benchmark benchmark.yml --base-url http://staging:3000 \
  --concurrency 20 --iterations 100 --stats

Read the output

Unless --quiet is set, driller prints one line per request with the step name, URL, HTTP status, and elapsed time. With --stats it closes with totals, a status-code breakdown, and mean, median, and p99, p99.5, and p99.9 latencies. --stats-format json writes the same numbers as a single JSON document for scripts and CI gates; the CLI reference documents the schema.

Try the examples

The repository ships runnable plans in example/ together with a small fixture server. They build up the plan features roughly in order of complexity: requests and assign, cookies, headers, iterations and throughput, tags, delays, and environment variables. The server is part of the git repository only, not of the published crate, so clone the repository to run them. Examples walks through starting the server and running each plan.

Next steps

• Benchmark syntax: every plan property, the with_items forms, and the interpolation rules.
• CLI reference: all flags, the statistics output, and the --worker-threads tuning guide.
• Proxies: running through a corporate proxy while keeping internal targets direct with NO_PROXY.