Choosing the Right Injection Profile in Gatling: Ramp‑Up vs. Constant Load

Problem: How to model realistic traffic in Gatling

When you run a Gatling simulation you control the virtual users (VUs) that send requests to your service. But the way those VUs arrive can dramatically alter the outcome of a test. A sudden burst can expose a system’s breaking point, while a gradual increase is more representative of real‑world growth. Choosing the correct injection profile is the first step in turning a simulation into a meaningful load test.

Thesis: Use ramp‑up for growth scenarios and constant‑rate for stability tests

Gatling’s injection profiles let you specify exactly how users are introduced. The two most common patterns are rampUsers (gradual increase) and constantUsersPerSec (steady throughput). Understanding when to use each, and how to verify that the load matches the intent, will help you avoid misleading results.

1. The Injection API in a Nutshell

All injection profiles are defined in the setUp block. The syntax is concise and declarative:

setUp(
  scn.inject( rampUsers(100).during(60) )
).protocols(httpProtocol)

In this example the scenario scn receives 100 users over 60 seconds. The framework calculates the user arrival rate and schedules the VUs accordingly.

Key Profiles

• atOnceUsers(n) – all n users start immediately. Useful for stress tests or cold‑start checks.
• rampUsers(n).during(t) – users are added linearly over t seconds.
• constantUsersPerSec(rate).during(t) – a fixed rate of users per second for t seconds, maintaining a steady state.

2. Ramp‑Up vs. Constant Load: When to Use Which?

Ramp‑Up (rampUsers)

Ramp‑up is ideal when you want to observe how a system behaves as traffic grows. Auto‑scaling groups, database connection pools, and circuit breakers often react to sustained load rather than an instant spike. A short ramp can trigger false positives: a circuit breaker might trip because the system never had time to warm up.

Constant Load (constantUsersPerSec)

Constant load is the backbone of soak or endurance tests. By maintaining a steady throughput you can identify memory leaks, resource exhaustion, or gradual performance degradation. It also provides a stable baseline for measuring latency under sustained pressure.

3. A Worked Example: Simulating 100 Users Over 60 Seconds

Below is a minimal simulation that demonstrates a ramp‑up of 100 users over one minute. Replace <httpProtocol> with your actual protocol configuration.

import io.gatling.core.Predef._
import io.gatling.http.Predef._

class RampExample extends Simulation {
  val httpProtocol = http
    .baseUrl("https://example.com")
    .acceptHeader("application/json")

  val scn = scenario("Ramp‑Up Test")
    .exec(http("Get Home").get("/")
      .check(status.is(200)))

  setUp(
    scn.inject(rampUsers(100).during(60))
  ).protocols(httpProtocol)
}

After running the simulation, open the generated target/gatling/html/<timestamp>/index.html report. The Active Users graph should display a straight line that starts at 0, climbs to 100 at the 60‑second mark, and stays flat thereafter.

Verification Checklist

• Run the simulation from a machine with sufficient CPU and memory; otherwise the client may become the bottleneck.
• In the report, locate the Active Users chart under the Load tab.
• Confirm that the curve matches the linear slope defined by rampUsers(100).during(60).
• Check the Iterations and Requests per second tables to ensure they reflect the expected load.

4. Trade‑offs and Limitations

• Client‑Side Bottleneck: If the machine running Gatling cannot keep up, you’ll see a lower than expected Active Users count. Monitor CPU usage and Memory consumption during the test.
• Short Ramp Duration: A ramp that is too brief may not give the system enough time to reach a steady state, leading to misleading circuit‑breaker or rate‑limiter behaviour.
• Non‑linear Traffic: Real traffic often follows a bursty pattern that neither pure ramp nor constant load captures. Consider combining profiles or using custom injection functions for more realistic scenarios.

5. Actionable Takeaways

1. Match the injection profile to your test goal: rampUsers for growth studies, constantUsersPerSec for stability or soak tests.
2. Always validate the Active Users chart to confirm the load matches the intended profile.
3. Run the test on a machine whose resources exceed the expected load; otherwise client‑side throttling will skew results.
4. For production‑grade realism, layer multiple injection profiles (e.g., a ramp followed by a constant plateau) to simulate a real traffic curve.
5. Document the chosen profile, its parameters, and the verification steps so future runs can be compared reliably.

By carefully selecting and validating your injection profile, you turn Gatling from a generic load generator into a precise instrument for uncovering performance bottlenecks and ensuring your system scales as expected.