Add Gatling load test suite for overpass.deflock.org

[dougborg]

Summary

• Adds a Gatling (Scala) load test suite in load-tests/ to validate overpass.deflock.org performance before switching app users to it
• Four simulation scenarios: baseline (deterministic single-user), concurrent (ramp to 50), stress (spike to 500), and burst (realistic app session waves)
• Queries use the exact same per-profile tag filters as the app's NodeProfile.getDefaults() (all 11 built-in profiles)
• Manual-trigger GitHub Actions workflow with scenario picker dropdown, parallel matrix runs, and downloadable HTML report artifacts
• Includes shared source set for testable pure logic, ScalaTest unit tests (22 tests), dev container, and documentation

Scenarios

Scenario	Users	Duration	Purpose
Baseline	1	~2 min	Deterministic zoom progression (6 zooms × 6 cities = 36 requests)
Concurrent	1→50	4 min	Find the degradation inflection point
Stress	500	5 min	Exceed ~512 Overpass compute slots
Burst	Waves of 20→50→100→80	~3 min	Realistic app sessions (10-20 requests each)

Baseline results (with full 11-profile tag filters)

36 requests, 0 failures:

Metric	Value
p50	1,655ms
p75	3,311ms
p95	6,309ms
p99	9,891ms
Error rate	0%

Project structure

load-tests/src/
├── shared/   — Pure logic (OverpassQuery, TestData) — no Gatling dependency
├── gatling/  — Simulations + HTTP request def — depends on shared
└── test/     — ScalaTest unit tests — depends on shared

The shared source set avoids a circular Gradle dependency between gatling and test.

Test plan

• ./gradlew compileGatlingScala — all 4 simulations compile
• ./gradlew test — 22 unit tests pass
• ./gradlew gatlingRun — baseline passes (36/36, 0 errors)
• ./gradlew gatlingRun --simulation deflock.ConcurrentSimulation — runs, 434 requests at 50 users, 0 errors
• GitHub Actions workflow triggers and uploads report artifact
• Dockerfile pins Coursier v2.1.24 with SHA256 checksum verification

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a standalone Gatling/Scala load-testing project under load-tests/ plus a manual GitHub Actions workflow to generate and upload HTML performance reports for the overpass.deflock.org Overpass instance.

Changes:

• Introduces Gatling simulations/request builders and test data for a single-user zoom progression scenario.
• Adds Gradle wrapper/build config, Gatling/logback config, and contributor docs (README + dev container).
• Adds a manually triggered GitHub Actions workflow to run the load test and upload reports.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
load-tests/src/gatling/scala/deflock/TestData.scala	Defines city centers, zoom viewport sizes, and feeders for request parameterization.
load-tests/src/gatling/scala/deflock/OverpassSimulation.scala	Implements the baseline Gatling scenario and global assertions.
load-tests/src/gatling/scala/deflock/OverpassRequests.scala	Defines Overpass query construction, timeouts, and HTTP request checks.
load-tests/src/gatling/resources/logback-test.xml	Sets default logging level for simulations.
load-tests/src/gatling/resources/gatling.conf	Configures report charting thresholds.
load-tests/settings.gradle.kts	Sets the Gradle root project name.
load-tests/build.gradle.kts	Adds Scala + Gatling Gradle plugin and Maven Central repository.
load-tests/README.md	Documents purpose, running locally/CI, and interpreting reports.
load-tests/.gitignore	Ignores Gradle outputs and caches within load-tests/.
load-tests/.devcontainer/devcontainer.json	Defines a VS Code dev container for running the load tests.
load-tests/.devcontainer/Dockerfile	Builds the dev container image (JDK 21 + Coursier).
load-tests/gradlew	Adds Gradle wrapper script (POSIX).
load-tests/gradlew.bat	Adds Gradle wrapper script (Windows).
load-tests/gradle/wrapper/gradle-wrapper.properties	Configures Gradle wrapper distribution and settings.
load-tests/gradle/wrapper/gradle-wrapper.jar	Adds the Gradle wrapper JAR.
.github/workflows/load-test.yml	Adds a manual workflow to run Gatling and upload the HTML report artifact.
.gitignore	Fixes formatting/indentation for the windows/ ignore entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

[dougborg]

I worked on this with some excellent input from T on the server. I think this will really help us tune things and make sure we can support the load, etc.

---

Open for discussion

This PR establishes the test harness and four initial scenarios, but the tuning numbers are starting points based on assumptions — not measurements. Happy to adjust any of these based on what Thomas knows about the server and what we learn from runs.

Tuning knobs

Parameter	Current value	Rationale	Question
Concurrent user cap	50	Conservative — stay below assumed 512 slots	Is 50 too timid? Should we push to 100-200?
Stress spike	500 users total	Designed to exceed 512 slots	Is 512 actually the slot count? Should we go higher?
Burst wave sizes	20→50→100→80	Gut feel for "bursty app traffic"	Do we have real traffic data to calibrate against?
Burst session length	10-20 requests	Rough estimate of a map browsing session	What does actual app telemetry say?
Pause between requests	200-800ms (burst), 500ms (concurrent), 100ms (stress)	Simulates pan/zoom interaction speed	Too fast? Too slow?
Weighted zoom distribution	80% z13-z15, 20% z10-z12	Assumption that most users are zoomed in	Do we have zoom level analytics?
Assertion thresholds	p99<30s baseline, p95<45s concurrent, p95<30s burst	Generous — exploring, not enforcing SLA	What response times are actually acceptable for the app UX?
City set	6 US cities	High surveillance camera density	Should we add international cities? Low-density areas?

What we can easily add

Gatling is flexible — new scenarios are ~30 lines of Scala. Some ideas:

• Soak test — moderate load (20-30 users) sustained for 30-60 minutes to catch memory leaks or slow degradation
• Geographic sweep — random lat/lng worldwide instead of fixed cities, to stress different parts of the Overpass dataset
• Cache effectiveness — repeat the same queries to measure how much the server's internal caching helps
• Ramp-to-failure — start at 10 users, add 10 every minute, keep going until error rate exceeds 50%. Automatically finds the ceiling.
• Single-profile queries — test individual profiles in isolation (just ALPR, just gunshot detectors) to see if query complexity affects latency differently
• Realistic daily curve — model a full 24-hour traffic pattern compressed into 15 minutes
• Traffic replay — in the future, we could record anonymized query patterns from the app (zoom levels, bbox sizes, request timing) and replay them through Gatling to model scenarios based on real user behavior rather than assumptions

Open questions

1. What's the actual server capacity? The 512 compute slot number came from early discussion — is that still accurate? Does nginx have its own connection limits in front of Overpass?
2. What does "good" look like? The baseline shows p501.7s, p9910s with the full 11-profile query. Is that acceptable for the app UX, or do we need it faster?
3. Should the load test workflow run on a schedule? We could add a nightly or weekly cron trigger for the baseline to catch regressions after server updates.
4. Multiple geographic regions? Running from GitHub Actions (US-East) means we're measuring US latency. Worth adding a runner in EU to test from there too?

[dougborg]

This will not be integrated here - we will be migrating this over to the infra repo on gitlab.