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)
);
}
}
- Pre-warms Gatling's internal Netty HTTP client and DNS/TLS machinery before user injection starts.
- Pulls the next CSV record into this virtual user's private
Session. - Non-blocking timer pause—releases the worker thread immediately to serve other virtual users.
- Spawns 20 independent virtual users per second for 60 seconds (1,200 users total). Each injected user executes
journeyonce 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.