Skip to content

Load testing (locust)

Find the endpoints that exceed 1 s under realistic concurrency. Locally first; then against dev, whose DB is ~10× slower. Design and delivered scope: implementation plan 2295.

One-time setup (local)

Point backend/.env at the local database first — the seeder refuses non-local hosts:

DB_URL=postgresql://co2_user:co2_password@localhost:5432/co2_calculator?sslmode=disable

Then, from the repo root and backend/:

make run-db                # compose Postgres on :5432
cd backend
make db-migrate
make seed-data             # locations, rooms, factors (needs INPUT_DATA/)
make perf-seed             # backdrop: 600 units × 2021–2025 × 0.1 ceilings ≈ 6M rows
make perf-csvs             # upload CSVs sampled from real factor data
make perf-db-dump          # snapshot the backdrop for cheap re-runs

Re-runs: make perf-db-restore instead of re-seeding. Knobs: SEED_NUM_UNITS, SEED_YEARS, SEED_CEILING_SCALE (1 = the full #2161 worst case, ≈63M rows — plan for a long seed), SEED_CEILING_UNITS_PREFIX (default U0: only the fake perf units get ceiling data, so a DB that also holds real accred-synced units doesn't balloon).

If your host pg_dump/pg_restore is older than the server (compose runs Postgres 18), dump through the container instead: docker exec co2-calculator-postgres pg_dump -U co2_user -Fc co2_calculator > dump.

Running

Start the backend with several workers — one worker benchmarks a single Python process, not the app:

cd backend && uv run uvicorn app.main:app --workers 4 --port 8000

Then:

make perf-load PERF_USERS=50 PERF_CLASSES=ExplorerReadUser   # one stage
make perf-sweep                                              # full ladder
make perf-report                                             # p95 > 1s table

perf-sweep runs reads at 50/100/200/500/1000 users, plan and explore-report creation at 10/20/30/40, and parallel CSV uploads at 5/10/20. Each stage writes a CSV + HTML report to backend/tests/performance/reports/ (gitignored). Read the p95/p99 columns, not averages.

Scenarios

Pick with PERF_CLASSES (class names in backend/tests/performance/locustfile.py):

Class Simulates
ExplorerReadUser Dashboard/explorer read mix: workspace home, merged modules-stats, unit totals
ModuleReadUser Module + paginated submodule page reads
ExploreCreateUser Parallel Simulator-Explore report creation
PlanUser Project-plan lifecycle: create → year range + prefill job → read → delete
CsvUploadUser CSV upload → dispatch → poll ingestion pipeline to completion

Multi-request flows (plan lifecycle, upload-to-ingested) also report their total wall time as FLOW rows in the stats.

Roles and the order of creation

Uploads require an opened year configuration — normally the backoffice admin's bootstrap-years; make perf-seed stamps it directly for the DEFAULT and TEST providers, so login-test users see the seeded years.

Merged stats, module reads and uploads are scoped to the caller's unit memberships and modules.* permissions, so the unit roles are the drivers: calco2.user.principal (default) and calco2.user.standard. Their login-test scopes cover the four TEST leaf units; the perf seeder maps its first four fake units onto those iids so both roles own ceiling-loaded units. Note the permission split: a standard user carries only .../own permissions on travel and cloud/AI plus planner.plans, so module reads and bulk uploads run as principal; rerun the read/plan ladders as standard with PERF_ROLE=calco2.user.standard make perf-load ....

The backoffice admin (calco2.backoffice.admin) has no memberships and no modules.* permissions — use it only for workspace-home/totals reads across the full seeded pool: make perf-load auto-derives PERF_UNIT_IDS from the local DB (or pass ranges like PERF_UNIT_IDS=4403-5002).

Knobs (env)

PERF_HOST, PERF_USERS, PERF_TIME, PERF_ROLE (default calco2.user.principal), PERF_UNIT_IDS (explicit unit-id pool for roles without memberships), PERF_MERGED_UNITS, PERF_JOB_TIMEOUT, PERF_AUTH_COOKIE.

Against dev

cd backend
make perf-dev                                          # 50 × ExplorerReadUser
make perf-dev PERF_USERS=200 PERF_CLASSES=ModuleReadUser
make perf-report

perf-dev points locust at https://co2-calculator-dev.epfl.ch/api (the /api prefix is required — the bare host is the SPA), logs every VU in via login-test (dev is a DEBUG build), and refuses the write scenarios (PlanUser, ExploreCreateUser, CsvUploadUser) unless PERF_ALLOW_WRITES=1 — they create real data and jobs on the shared environment, so coordinate first.

For a target without login-test (stage, prod), copy the auth_token cookie from a logged-in browser tab and export PERF_AUTH_COOKIE=<jwt> before make perf-load PERF_HOST=https://<host>/api ...; the cookie takes precedence over seeded-user minting and login-test. See the suite README for the remote-DB checklist.

Interpreting results

  • The budget: p95 under 1 s per endpoint at the target concurrency (guardrails' normal-load budget is stricter — see guardrails).
  • A stage where everything degrades together usually means a saturated resource (worker CPU, DB pool), not one slow endpoint — check pool size and worker count before filing per-endpoint issues.
  • Known measurement caveats (placeholder emissions in the backdrop, one shared test user per role) are listed in the implementation plan.