Gatling simulations

By the end of this chapter Gatling is wired into the Gradle build and you have four complete simulations covering the four workloads this series needs: read-heavy, mixed read/write, paginated search, and a stepped stress test that pushes past the SLOs from chapter 01. Along the way: feeders, session state, request correlation, the open-versus-closed model decision, and assertions that make a run fail loudly.

Add the Gatling plugin

Add one line to the plugins block of build.gradle.kts (chapter 03):

1
plugins {
2
    java
3
    id("org.springframework.boot") version "4.1.1"
4
    id("io.spring.dependency-management") version "1.1.7"
5
    id("io.gatling.gradle") version "3.15.1.3"   // brings Gatling 3.15.1
6
}

The plugin adds a gatling source set — simulations live in src/gatling/java, test resources (feeder CSVs) in src/gatling/resources — and a gatlingRun task. With several simulation classes present, pick one by fully-qualified name (gatlingRun alone is interactive, and fails outright when CI=true):

1
./gradlew gatlingClasses                                           # compile check only
2
./gradlew gatlingRun --simulation in.o612.eng.orders.load.ReadHeavySimulation
3
./gradlew gatlingRun --all                                         # every simulation, sequentially

Gatling does not need the application as a dependency — it is a pure HTTP client. That separation is deliberate: the load generator must never share a JVM, a connection pool, or a class path with the system under test.

Open model, closed model — pick deliberately

Gatling’s injection API splits in two, and the choice determines what your numbers mean:

Open model (injectOpen): you control the arrival rate — new virtual users start at the configured rate regardless of whether earlier requests finished. If the server slows down, in-flight requests pile up, which is exactly what real traffic does.
Closed model (injectClosed): you control concurrency — a fixed number of virtual users, each starting a new iteration only after finishing the last. If the server slows, the arrival rate drops automatically.

Principle: for a user-facing HTTP API, the open model is the honest one. Real visitors do not politely wait for earlier visitors to finish. The closed model hides saturation: as response times grow, the offered load silently shrinks to what the server can handle — this is coordinated omission, covered fully in chapter 07, and it is why a closed-model test can report “stable throughput” while every user is queued. Use closed models only when the real callers genuinely are bounded — a fixed fleet of batch workers, a thread pool of internal consumers — which is rare for REST APIs.

All four simulations below use the open model.

A note on feeders, headers, and auth

Feeders inject per-request data into the virtual user’s session — the CSV exports from chapter 05. circular() re-reads from the top when exhausted (right for read IDs); queue() consumes each row once and fails the run if exhausted (right for placed_orders.csv — a PATCHed order is consumed, and reusing it would generate 409s).
Session attributes are referenced in URLs and bodies with #{name} — the CSV column name.
Headers belong on HttpProtocolBuilder when they are universal (Accept, Content-Type), on the request otherwise.
Authentication: this lab API is unauthenticated. When yours is not, the pattern is a one-shot exec that posts credentials and .check(jsonPath("$.token").saveAs("accessToken")), followed by .header("Authorization", "Bearer #{accessToken}") on each request — fetch tokens in a before hook or once per user, never inside a measured request chain unless token issuance is itself in scope:

1
// Illustrative — not used by the lab API. Pattern for token-bearing APIs:
2
//   .exec(http("authenticate").post("/auth/token")
3
//       .body(StringBody("{\"client\":\"load-test\"}"))
4
//       .check(status().is(200), jsonPath("$.token").saveAs("accessToken")))
5
// then on each request:
6
//   .header("Authorization", "Bearer #{accessToken}")

Store real credentials in environment variables (System.getenv("LOADTEST_TOKEN")), never in the repository — a simulation with a committed token is a credential leak.

Simulation 1 — read-heavy

The dominant real-world shape: mostly fetches, some searches, no writes. Traffic distribution is 70% GET /api/orders/{id}, 30% search — deliberately unequal, because equal-weight endpoints are a lab fiction.

1
package in.o612.eng.orders.load;
2

3
import static io.gatling.javaapi.core.CoreDsl.*;
4
import static io.gatling.javaapi.http.HttpDsl.*;
5

6
import io.gatling.javaapi.core.*;
7
import io.gatling.javaapi.http.*;
8
import java.time.Duration;
9

10
public class ReadHeavySimulation extends Simulation {
11

12
    HttpProtocolBuilder httpProtocol = http
13
        .baseUrl(System.getProperty("baseUrl", "http://localhost:8080"))
14
        .acceptHeader("application/json")
15
        .shareConnections();
16

17
    FeederBuilder<String> orders = csv("data/orders.csv").circular();
18
    FeederBuilder<String> customers = csv("data/customers.csv").circular();
19

20
    ChainBuilder getOrder = feed(orders)
21
        .exec(http("GET /api/orders/{id}")
22
            .get("/api/orders/#{order_id}")
23
            .check(status().is(200)));
24

25
    ChainBuilder searchOrders = feed(customers)
26
        .exec(http("GET /api/orders?customer")
27
            .get("/api/orders?customerId=#{customer_id}&size=20")
28
            .check(status().is(200)));
29

30
    ScenarioBuilder readHeavy = scenario("read-heavy")
31
        .randomSwitch().on(
32
            percent(70.0).then(getOrder),
33
            percent(30.0).then(searchOrders));
34

35
    {
36
        setUp(readHeavy.injectOpen(
37
            // phase 1: warm-up — arrival rate ramps, results discarded
38
            rampUsersPerSec(1).to(30).during(Duration.ofMinutes(1)),
39
            // phase 2: steady state — the measurement window
40
            constantUsersPerSec(30).during(Duration.ofMinutes(3)),
41
            // phase 3: ramp-down — watches recovery, kept out of assertions
42
            rampUsersPerSec(30).to(0).during(Duration.ofSeconds(30))
43
        ).protocols(httpProtocol))
44
        .assertions(
45
            details("GET /api/orders/{id}").responseTime().percentile(99.0).lt(150),
46
            details("GET /api/orders?customer").responseTime().percentile(99.0).lt(300),
47
            global().failedRequests().percent().lt(0.1)
48
        );
49
    }
50
}

shareConnections() makes virtual users share the underlying HTTP connection pool like real browsers and API clients behind keep-alive — without it, each virtual user gets a private connection and you benchmark TCP setup instead of your API. The assertions are the SLOs from chapter 01, expressed per request name: this run fails (non-zero exit, KO in the report) if p99 on fetches exceeds 150 ms.

Simulation 2 — mixed read/write

Adds create and status-update traffic in a realistic ratio. The chain that matters is createThenRead: the POST response’s id is saved into the session and immediately used in a follow-up GET — request correlation, the pattern for “create then fetch the thing you created”.

1
package in.o612.eng.orders.load;
2

3
import static io.gatling.javaapi.core.CoreDsl.*;
4
import static io.gatling.javaapi.http.HttpDsl.*;
5

6
import io.gatling.javaapi.core.*;
7
import io.gatling.javaapi.http.*;
8
import java.time.Duration;
9

10
public class MixedWorkloadSimulation extends Simulation {
11

12
    HttpProtocolBuilder httpProtocol = http
13
        .baseUrl(System.getProperty("baseUrl", "http://localhost:8080"))
14
        .acceptHeader("application/json")
15
        .contentTypeHeader("application/json")
16
        .shareConnections();
17

18
    FeederBuilder<String> orders = csv("data/orders.csv").circular();
19
    FeederBuilder<String> customers = csv("data/customers.csv").circular();
20
    FeederBuilder<String> placed = csv("data/placed_orders.csv").queue();
21

22
    ChainBuilder getOrder = feed(orders)
23
        .exec(http("GET /api/orders/{id}")
24
            .get("/api/orders/#{order_id}").check(status().is(200)));
25

26
    ChainBuilder search = feed(customers)
27
        .exec(http("GET /api/orders?customer")
28
            .get("/api/orders?customerId=#{customer_id}&size=20")
29
            .check(status().is(200)));
30

31
    ChainBuilder createThenRead = feed(customers)
32
        .exec(http("POST /api/orders")
33
            .post("/api/orders")
34
            .body(StringBody("""
35
                {"customerId":#{customer_id},
36
                 "items":[{"sku":"SKU-LT-1","quantity":2,"unitPrice":19.99},
37
                          {"sku":"SKU-LT-7","quantity":1,"unitPrice":4.50}]}
38
                """)).asJson()
39
            .check(status().is(201), jsonPath("$.id").saveAs("createdOrderId")))
40
        .pause(Duration.ofMillis(300))
41
        .exec(http("GET created order")
42
            .get("/api/orders/#{createdOrderId}").check(status().is(200)));
43

44
    ChainBuilder advanceStatus = feed(placed)
45
        .exec(http("PATCH /api/orders/{id}/status")
46
            .patch("/api/orders/#{order_id}/status")
47
            .body(StringBody("{\"status\":\"PAID\"}")).asJson()
48
            .check(status().is(200)));
49

50
    ScenarioBuilder mixed = scenario("mixed").randomSwitch().on(
51
        percent(55.0).then(getOrder),
52
        percent(25.0).then(search),
53
        percent(12.0).then(createThenRead),
54
        percent(8.0).then(advanceStatus));
55

56
    {
57
        setUp(mixed.injectOpen(
58
            rampUsersPerSec(1).to(20).during(Duration.ofMinutes(1)),
59
            constantUsersPerSec(20).during(Duration.ofMinutes(3))
60
        ).protocols(httpProtocol))
61
        .assertions(
62
            global().responseTime().percentile(95.0).lt(250),
63
            global().failedRequests().percent().lt(0.5)
64
        );
65
    }
66
}

Two details are load-bearing. First, placed uses queue() — each PLACED order can be transitioned to PAID exactly once, and if the feeder exhausts, the run fails rather than silently generating 409s. 12% of 20 users/s is 2.4 creations per second; the status-update pool (~120,000 PLACED orders) is far deeper than any single run consumes, which is why chapter 05’s template-reset strategy exists for repeated write runs. Second, every write is checked — a silent 500 on 8% of traffic would contaminate every latency percentile while looking like “the server held up”.

Why these weights? Example assumption: reads dominate e-commerce order traffic by roughly 5:1 in this fictional system. Your real ratio comes from production access logs — pull a day of traffic, count by route shape, and weight randomSwitch accordingly. The method is the deliverable, not the numbers.

Simulation 3 — paginated search

Search with pagination is where deep OFFSET and index quality show up. Each virtual user pages through three pages of results for one customer.

1
package in.o612.eng.orders.load;
2

3
import static io.gatling.javaapi.core.CoreDsl.*;
4
import static io.gatling.javaapi.http.HttpDsl.*;
5

6
import io.gatling.javaapi.core.*;
7
import io.gatling.javaapi.http.*;
8
import java.time.Duration;
9

10
public class SearchSimulation extends Simulation {
11

12
    HttpProtocolBuilder httpProtocol = http
13
        .baseUrl(System.getProperty("baseUrl", "http://localhost:8080"))
14
        .acceptHeader("application/json")
15
        .shareConnections();
16

17
    FeederBuilder<String> customers = csv("data/customers.csv").circular();
18

19
    ScenarioBuilder search = scenario("paginated search")
20
        .feed(customers)
21
        .exec(session -> session.set("page", 0))
22
        .repeat(3).on(
23
            exec(http("GET /api/orders search page #{page}")
24
                .get(s -> "/api/orders?customerId=" + s.getString("customer_id")
25
                    + "&page=" + s.getInt("page") + "&size=20")
26
                .check(status().is(200)))
27
            .pause(Duration.ofMillis(800))
28
            .exec(session -> session.set("page", session.getInt("page") + 1))
29
        );
30

31
    {
32
        setUp(search.injectOpen(
33
            rampUsersPerSec(1).to(15).during(Duration.ofMinutes(1)),
34
            constantUsersPerSec(15).during(Duration.ofMinutes(3))
35
        ).protocols(httpProtocol))
36
        .assertions(
37
            global().responseTime().percentile(99.0).lt(300),
38
            global().failedRequests().percent().lt(0.1)
39
        );
40
    }
41
}

exec(session -> ...) is the escape hatch for session arithmetic — here, a page counter incremented per iteration. pause(800ms) models a human reading a page; in the open model it does not reduce the arrival rate, it only changes how long each virtual user stays active — which raises the concurrent-in-flight count by Little’s law. Both effects are intended.

Simulation 4 — stepped stress

This one’s job is to break the SLO on purpose, in controlled steps, so you can see where the knee is and what saturates first.

1
package in.o612.eng.orders.load;
2

3
import static io.gatling.javaapi.core.CoreDsl.*;
4
import static io.gatling.javaapi.http.HttpDsl.*;
5

6
import io.gatling.javaapi.core.*;
7
import io.gatling.javaapi.http.*;
8
import java.time.Duration;
9

10
public class StressSimulation extends Simulation {
11

12
    HttpProtocolBuilder httpProtocol = http
13
        .baseUrl(System.getProperty("baseUrl", "http://localhost:8080"))
14
        .acceptHeader("application/json")
15
        .contentTypeHeader("application/json")
16
        .shareConnections();
17

18
    FeederBuilder<String> orders = csv("data/orders.csv").circular();
19
    FeederBuilder<String> customers = csv("data/customers.csv").circular();
20

21
    ScenarioBuilder probe = scenario("stepped stress").randomSwitch().on(
22
        percent(60.0).then(feed(orders).exec(
23
            http("GET /api/orders/{id}")
24
                .get("/api/orders/#{order_id}").check(status().is(200)))),
25
        percent(30.0).then(feed(customers).exec(
26
            http("GET /api/orders?customer")
27
                .get("/api/orders?customerId=#{customer_id}&size=20")
28
                .check(status().is(200)))),
29
        percent(10.0).then(feed(customers).exec(
30
            http("POST /api/orders")
31
                .post("/api/orders")
32
                .body(StringBody("""
33
                    {"customerId":#{customer_id},
34
                     "items":[{"sku":"SKU-ST","quantity":1,"unitPrice":9.99}]}
35
                    """)).asJson()
36
                .check(status().is(201)))));
37

38
    {
39
        setUp(probe.injectOpen(
40
            // 25 → 150 req/s in six 2-minute steps, 30 s ramps between.
41
            // Widen the range until the SLO assertions fail; that level
42
            // IS the finding.
43
            incrementUsersPerSec(25.0)
44
                .times(6)
45
                .eachLevelLasting(Duration.ofMinutes(2))
46
                .separatedByRampsLasting(Duration.ofSeconds(30))
47
                .startingFrom(25.0)
48
        ).protocols(httpProtocol))
49
        .assertions(
50
            global().responseTime().percentile(99.0).lt(300),
51
            global().failedRequests().percent().lt(0.5)
52
        );
53
    }
54
}

The assertions here are not pass/fail gates — they are the tripwire that tells you which step crossed the line. Read the report’s “response time over time” graph against the injection profile: the step where p99 bends sharply upward is the knee, and the level just below it is the service’s honest capacity under this profile. Chapter 08 shows how to correlate that knee with the saturation metrics from chapter 03.

Injection profiles, briefly

DSL	Shape	Use for
`rampUsersPerSec(a).to(b)`	arrival rate linear a→b	warm-up, ramp-down
`constantUsersPerSec(r).during(t)`	flat arrival rate	steady-state measurement
`incrementUsersPerSec(step).times(n).eachLevelLasting(t)`	staircase	stress / capacity tests
`nothingFor(t)`	silence	cool-down
`constantConcurrentUsers(n)` / `rampConcurrentUsers`	fixed concurrency	closed model only — bounded caller pools
`atOnceUsers(n)`	all at once	spike tests (chapter 11)

Common failure: forgetting .protocols(httpProtocol) — the scenario runs against no HTTP config and fails cryptically. And naming requests ("GET /api/orders/{id}") is not cosmetic: the report and the details(...) assertions are keyed by those names, so use the route template, not a friendly sentence.

Milestone

1
./gradlew gatlingClasses                                       # compiles
2
./gradlew gatlingRun --simulation in.o612.eng.orders.load.ReadHeavySimulation

A full run takes ~4.5 minutes including warm-up and ramp-down. The console ends with a path to an HTML report under build/reports/gatling/. Open it — chapter 07 is about making sure the numbers in it are trustworthy.

Spring BootJavaPerformanceTesting