Flow icon
Commands icon
Script icon
Log icon
If icon
Fail icon

Locust Load Test SLO Gate

Run a Locust load test after every staging deploy, keep per-endpoint stats, and block the release when p95 latency or the error rate breaks your SLO.

Categories
Infrastructure

Functional tests pass with one user; production has hundreds. Latency regressions and errors that only appear under concurrency (a lock, a missing index, a race when two requests write the same record) slip through until real traffic finds them. This blueprint runs Locust headless against a staging API after every deploy, keeps the per-endpoint statistics on the execution, and turns them into a pass/fail gate on p95 latency and failure rate that a release flow can wait on.

How it works

  1. after_staging_deploy (io.kestra.plugin.core.trigger.Flow) starts the test when the deploy_staging flow ends in SUCCESS. It ships disabled: true; you can also run the flow by hand.
  2. load_test (io.kestra.plugin.scripts.python.Commands) installs a pinned locust==2.46.7 in a python:3.12-slim container, writes a small locustfile from inputFiles (each simulated user calls every path in paths with the extra_header, pausing 0.5 to 1.5 s), and runs locust --headless for run_time at up to users users. Locust exits non-zero as soon as one request fails, so the exit code is captured and run_stats.csv and run_failures.csv are always kept as output files.
  3. evaluate_slo (io.kestra.plugin.scripts.python.Script) reads the Aggregated row for the request count, failures, requests per second and the 95th percentile, builds one line per endpoint and per error type, and marks the run BREACHED when the p95 is above p95_limit_ms, the failure rate is above max_failure_pct, or no request completed.
  4. log_results (io.kestra.plugin.core.log.Log) logs the verdict, the numbers, each endpoint and each error, for example GET /api/state: 187 req, 4 failed, p95 15 ms.
  5. gate (io.kestra.plugin.core.flow.If) fails the execution through io.kestra.plugin.core.execution.Fail when the SLO is breached, otherwise logs a pass. The verdict flow output exposes the result.

What you get

  • A repeatable load test on every staging deploy, with the same users, ramp-up and duration each time.
  • A PASSED / BREACHED / NO_DATA verdict and a failed execution with the exact reason when the release should stop.
  • Locust's statistics and failure CSVs attached to every execution, so results can be compared deploy to deploy.
  • Errors grouped by endpoint and type, which points straight at the endpoint that breaks under concurrency.

Who it's for

  • Backend and platform teams that want a performance check between staging and production.
  • SRE teams who own latency and error-rate SLOs.

Why orchestrate this with Kestra

A load test run from a laptop is run once, before launch, and never again. In Kestra it runs on every staging deploy through a Flow trigger, the statistics are kept with the execution history, the thresholds are typed inputs, and a breached SLO stops the downstream release with a clear error instead of a chart nobody opened.

Prerequisites

  • A staging or preview API you are allowed to load test, and the GET endpoints to exercise.
  • A Kestra worker that can run containers (Docker or Kubernetes task runner) and reach the API and PyPI.
  • Optional: a deploy_staging flow in company.team for the trigger, or point the trigger at your own deploy flow.

Secrets

  • None are required for a public staging API. For an authenticated one, add a secret such as API_TOKEN and set extra_header to an Authorization: Bearer header whose value is the Pebble expression secret('API_TOKEN'), so the token stays masked in logs.

Quick start

  1. Set host, paths and, if needed, extra_header.
  2. Execute the flow with a small load (users: 5, run_time: 20s) and read log_results.
  3. Set p95_limit_ms and max_failure_pct from that baseline, then raise users and run_time to your real target.
  4. Point after_staging_deploy at your deploy flow and enable it.

How to extend

  • Replace the generated locustfile with your own from a namespace file to add POST requests, login and weighted tasks.
  • Add a per-endpoint p95 limit for critical paths such as checkout or login.
  • Store each run's p95 in a KV entry and fail on a regression of more than a set percentage against the last green run.
  • Post log_results to Slack or open an incident with the notification plugins.

Links

Share this Blueprint
See How

New to Kestra?

Use blueprints to kickstart your first workflows.