Load Injection Patterns¶
Gatling's injection DSL gives you precise control over how virtual users arrive or concurrency scales over time. Selecting the right load shape determines whether your test validates baseline SLOs, pinpoints the exact capacity ceiling, or proves resilience under sudden viral surges.
Visual Guide to the Core Load Shapes¶
flowchart TB
subgraph Constant["1. Constant Load (Baseline & Soak)"]
direction LR
C1["Warm-up Ramp"] --> C2["Flat Steady Rate (e.g., 100 users/s for 30m)"]
end
subgraph Ramp["2. Continuous Ramp (Breaking Point Discovery)"]
direction LR
R1["10 users/s"] --> R2["Linearly climb to 500 users/s over 20m"]
end
subgraph Step["3. Step / Staircase Load (Threshold & USL Analysis)"]
direction LR
S1["50/s (5m)"] --> S2["100/s (5m)"] --> S3["200/s (5m)"] --> S4["400/s (5m)"]
end
subgraph Spike["4. Spike Load (Burst Resilience & Recovery)"]
direction LR
P1["Baseline 50/s"] --> P2["Instant 2,500/s Surge (1m)"] --> P3["Recovery 50/s (5m)"]
end
1. Constant Load (constantUsersPerSec)¶
Injects new virtual users at a steady arrival rate to measure baseline SLO compliance (15–30 minutes) or long-term Soak stability (8–24 hours).
setUp(
userScenario.injectOpen(
rampUsersPerSec(1).to(100).during(Duration.ofMinutes(2)), // (1)!
constantUsersPerSec(100).during(Duration.ofMinutes(20)) // (2)!
)
).protocols(httpProtocol);
- Always precede constant load with a short warm-up ramp so cold JIT compilation and empty caches don't skew your steady-state assertions.
- Sustains 100 new user arrivals/sec (120,000 total users over 20 minutes). Add
.randomized()to model Poisson-like random inter-arrival spacing instead of evenly spaced ticks!
What healthy telemetry looks like:
- P95 & P99: Flat horizontal band throughout the 20-minute hold.
- Post-GC Heap: Clean sawtooth returning to the same memory floor after every GC cycle.
- Throughput: Matches injection rate $\times$ requests-per-user with < 0.1% errors.
2. Ramp Load (rampUsersPerSec)¶
Smoothly increases the arrival rate from a low floor to a high ceiling, sweeping across utilization levels to reveal the Latency Knee where queuing begins.
setUp(
userScenario.injectOpen(
rampUsersPerSec(10).to(500).during(Duration.ofMinutes(20))
)
).protocols(httpProtocol);
How to Read a Ramp Test Graph
Plot Active Requests / RPS on the X-axis against P95 & P99 Latency on the Y-axis: - Zone 1 (Flat): Plenty of spare CPU and pool capacity. - Zone 2 (Gentle Slope — Knee): Utilization reaches ~70–80%; mild queuing begins. Your max safe production operating point sits just below this knee. - Zone 3 (Vertical Wall): Utilization hits ~95–100%; queues explode exponentially and timeouts begin.
3. Step / Staircase Load (incrementUsersPerSec)¶
While a continuous ramp moves too quickly to tell whether a load level is truly stable over several minutes, Step Load holds each plateau long enough for caches, GC cycles, and DB checkpoints to settle.
setUp(
userScenario.injectOpen(
incrementUsersPerSec(50.0) // (1)!
.times(5) // (2)!
.eachLevelLasting(Duration.ofMinutes(5)) // (3)!
.separatedByRampsLasting(Duration.ofSeconds(30)) // (4)!
.startingFrom(50.0) // (5)!
)
).protocols(httpProtocol);
- Add +50 users/sec at each step.
- Run 5 steps total (
50 → 100 → 150 → 200 → 250 users/sec). - Hold each plateau steady for 5 minutes to verify stability at that tier.
- Smooth 30-second transition ramp between plateaus.
- Begin Step 1 at 50 users/sec.
setUp(
userScenario.injectOpen(
constantUsersPerSec(25).during(Duration.ofMinutes(5)),
constantUsersPerSec(50).during(Duration.ofMinutes(5)),
constantUsersPerSec(100).during(Duration.ofMinutes(5)),
constantUsersPerSec(250).during(Duration.ofMinutes(5)),
constantUsersPerSec(500).during(Duration.ofMinutes(5))
)
).protocols(httpProtocol);
4. Spike Load (stressPeakUsers / Rapid rampUsersPerSec)¶
Simulates flash sales, breaking-news push notifications, or cron-herd thundering herds—and critically keeps running at normal load afterward to prove the system recovers cleanly without manual restarts!
setUp(
userScenario.injectOpen(
constantUsersPerSec(50).during(Duration.ofMinutes(3)), // 1. Normal baseline
rampUsersPerSec(50).to(2000).during(Duration.ofSeconds(15)), // 2. 40x flash surge!
constantUsersPerSec(2000).during(Duration.ofSeconds(60)), // 3. Hold peak burst
rampUsersPerSec(2000).to(50).during(Duration.ofSeconds(15)), // 4. Surge subsides
constantUsersPerSec(50).during(Duration.ofMinutes(5)) // 5. Verify full recovery!
)
).protocols(httpProtocol);
Never End a Spike Test at Peak!
Always include Phase 5 (Post-Spike Baseline). Many broken systems appear to "survive" the 60-second spike, only to remain deadlocked with stuck DB transactions, tripped circuit breakers that never half-open, or exhausted thread pools long after traffic returns to 50 RPS!
5. Closed Concurrent Profiles (injectClosed)¶
When testing bounded-concurrency systems—such as internal call-center workstations, worker queues, or fixed connection pools—use Gatling's closed injection blocks:
setUp(
agentWorkstationScenario.injectClosed(
incrementConcurrentUsers(25)
.times(4)
.eachLevelLasting(Duration.ofMinutes(5))
.separatedByRampsLasting(Duration.ofSeconds(20))
.startingFrom(25) // Steps: 25 → 50 → 75 → 100 concurrent users
)
).protocols(httpProtocol);
(Review Workload Models & Coordinated Omission to ensure you never misuse injectClosed for open internet traffic.)
Pattern Selection Cheat Sheet¶
| Engineering Question | Recommended Profile | Gatling Building Block |
|---|---|---|
| "Did my PR break script correlations?" | Smoke | atOnceUsers(1) |
| "Do we meet P95/P99 SLOs at Tuesday peak?" | Constant Open | constantUsersPerSec(rate).during(30m) |
| "Where is our breaking point?" | Continuous Ramp | rampUsersPerSec(min).to(max).during(20m) |
| "What is our exact Max Sustainable Throughput?" | Step Staircase | incrementUsersPerSec(step).times(k)... |
| "Do we survive & recover from a 30x flash sale?" | Spike + Recovery | Baseline $\rightarrow$ Surge $\rightarrow$ Baseline |
| "Is there a slow memory or socket leak?" | Soak (Endurance) | constantUsersPerSec(rate).during(12h) |
Knowledge Check¶
Why is a Step Load test often preferred over a fast Continuous Ramp when determining Maximum Sustainable Throughput (MST)?
Why must a Spike Test always include a 5-minute normal-load phase after the spike drops?
Next Steps¶
- Read next: SLIs, SLOs, SLAs & Error Budgets — Turn raw metrics into rigorous reliability engineering targets and error budgets.