Skip to content

Gatling Architecture

Gatling is a high-efficiency load-testing-as-code engine built on the JVM and Netty's asynchronous, non-blocking event loops. Unlike legacy load generators that allocate one OS thread per virtual user, Gatling models virtual users as lightweight state machines—allowing a single developer laptop or CI runner to drive tens of thousands of concurrent connections with minimal CPU and memory overhead.


Event-Loop Engine vs. Thread-Per-User Tools

Understanding why Gatling scales requires contrasting its non-blocking architecture with traditional blocking load tools (such as classic JMeter thread groups):

flowchart TB
    subgraph Legacy["Thread-Per-User Model (Blocking I/O)"]
        direction LR
        T1["OS Thread 1 (1MB Stack)<br/>Blocked waiting on socket..."] --> S1["Target API"]
        T2["OS Thread 2 (1MB Stack)<br/>Sleeping in pause(10)..."] --> S1
        TN["OS Thread 10,000 (10GB RAM!)<br/>Heavy kernel context switching"] --> S1
    end

    subgraph Gatling["Gatling Event-Loop Model (Async Non-Blocking)"]
        direction LR
        Pool["2 × CPU Cores<br/>Netty Event-Loop Threads"] -->|"Multiplexes 50,000+ sockets<br/>Zero blocking during pause/wait"| S2["Target API"]
        Users["Virtual Users = Lightweight<br/>Immutable Session State (~few KB)"] --> Pool
    end
Architectural Aspect Thread-Per-User (Blocking) Gatling (Event-Loop / Non-Blocking)
Virtual User Representation Dedicated OS / platform thread (~1 MB stack each) Lightweight in-memory Session message (~few KB)
Behavior During pause(10) Thread sits parked in memory Scheduled timer callback; zero thread held
Behavior Waiting for HTTP Response Thread blocks on socket read Async Netty NIO selector callback wakes state machine on arrival
Context-Switch Overhead at 10k Users Severe %sys kernel thrashing & scheduling jitter Handful of pinned event-loop threads (2 × cores), near-zero jitter
Coordinated Omission Resistance Vulnerable when thread pool saturates High accuracy under injectOpen scheduling

Golden Rule of Gatling Custom Code

Because thousands of virtual users share a small pool of Netty event-loop threads, never call Thread.sleep(...) or perform slow blocking file/DB I/O inside .exec(session -> ...)! Blocking an event-loop thread freezes hundreds of other virtual users sharing that core. Use Gatling's non-blocking pause() DSL and preload files at class initialization.


Core Engine Pipeline

flowchart LR
    Sim["Simulation Class<br/>Protocol • Scenario • setUp()"] --> Scheduler["Injection Scheduler<br/>Open / Closed / Throttle"]
    Scheduler --> Engine["Scenario State Machine<br/>Feeders • Exec • Checks"]
    Engine <-->|"Async NIO"| Netty["Netty Protocol Client<br/>HTTP/1.1 • HTTP/2 • WS • SSE"]
    Engine --> Stats["StatsEngine (HdrHistogram)<br/>Lock-free metric aggregation"]
    Stats --> Report["HTML Report + Assertions<br/>target/gatling/.../index.html"]

The Three Building Blocks of Every Simulation

Every Gatling Simulation class combines three declarative components:

public class ArchitectureDemoSimulation extends Simulation {

    // 1. PROTOCOL — Shared transport & connection settings
    HttpProtocolBuilder httpProtocol = http
        .baseUrl("https://jsonplaceholder.typicode.com")
        .acceptHeader("application/json")
        .contentTypeHeader("application/json")
        .warmUp("https://jsonplaceholder.typicode.com/posts/1"); // (1)!

    // 2. SCENARIO — Sequential state machine executed by each Virtual User
    FeederBuilder<String> userFeeder = csv("data/users.csv").circular();

    ScenarioBuilder journey = scenario("Reader Journey")
        .feed(userFeeder)                                        // (2)!
        .exec(http("List Posts").get("/posts?userId=#{userId}")
            .check(status().is(200), jsonPath("$[0].id").saveAs("postId")))
        .pause(Duration.ofSeconds(1), Duration.ofSeconds(3))     // (3)!
        .exec(http("Read Post").get("/posts/#{postId}")
            .check(status().is(200)));

    // 3. SETUP — Workload model, protocols & pass/fail SLO assertions
    {
        setUp(
            journey.injectOpen(
                constantUsersPerSec(20).during(Duration.ofSeconds(60)) // (4)!
            )
        )
        .protocols(httpProtocol)
        .assertions(
            global().responseTime().percentile(95.0).lt(800),
            global().successfulRequests().percent().gte(99.0)
        );
    }
}
  1. Pre-warms Gatling's internal Netty HTTP client and DNS/TLS machinery before user injection starts.
  2. Pulls the next CSV record into this virtual user's private Session.
  3. Non-blocking timer pause—releases the worker thread immediately to serve other virtual users.
  4. Spawns 20 independent virtual users per second for 60 seconds (1,200 users total). Each injected user executes journey once from top to bottom and exits (unless you explicitly wrap steps in .repeat(...) or .forever().on(...)).

Supported Protocols

Protocol Support Model Typical Use Case
HTTP/1.1 & HTTP/2 Built-in HttpDsl REST APIs, GraphQL, BFFs, web apps
WebSocket & SSE Built-in HttpDsl (ws, sse) Live chat, real-time notifications, streaming tickers
JMS Official Gatling JMS module ActiveMQ, Artemis, IBM MQ enterprise messaging
gRPC Official Gatling gRPC plugin Low-latency Protobuf east-west microservices
Kafka Custom exec() / Community plugins High-throughput event streaming (covered in Labs 6 & 7)

Knowledge Check

#

Why must you never write Thread.sleep(2000) inside a Gatling .exec(session -> ...) block?

#

In journey.injectOpen(constantUsersPerSec(10).during(60)), how many times does each spawned virtual user execute journey if no loop (repeat / forever) is present in the scenario?


Next Steps

  • Read next: Simulation Lifecycle — Trace every phase of a Gatling run from JVM startup to HTML report generation.