A few years ago, I worked with a developer who had spent three weeks perfecting a complex reporting endpoint. In his local environment, the response time was a crisp 40ms. He was proud of it, and for good reason—the logic was elegant. But the moment we pushed it to the staging environment and ran a basic load test with just fifty concurrent users, the JVM started screaming. The response times didn't just climb; they spiked to 12 seconds, and then the service simply stopped responding. It turned out that while the code was fast, the database connection pool was being exhausted because of a tiny leak in how he handled the result sets. We didn't find this until an hour before the production release. That's why we don't guess about performance; we prove it.

When you're building APIs in Scala, you're often leveraging the power of non-blocking I/O and asynchronous patterns. However, that efficiency can be deceptive. You might be able to handle thousands of requests on the application layer, but your database, your cache, or a downstream microservice might be the bottleneck. This is where Gatling comes in. Unlike older tools that create one thread per virtual user—which kills your machine's memory very quickly—Gatling uses an asynchronous engine based on Akka and Netty. It allows you to simulate thousands of users on a single laptop because it doesn't block threads while waiting for the server to respond.

Modeling the User Journey with the Scala DSL

Gatling doesn't use a GUI for defining tests; it uses a Scala DSL. This is a huge advantage because you can use your existing Scala skills to parameterize your tests, create loops, or generate random data. Instead of thinking about "requests," you think about "scenarios." A scenario is a sequence of actions a user takes.

Let's say we're testing an Order API. You wouldn't just hit the /checkout endpoint a thousand times; that's not how real people use apps. A real user logs in, browses a product, adds it to a cart, and then checks out. In Gatling, you define this as a chain of exec calls. Here is how that looks in practice:

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

class OrderApiSimulation extends Simulation {

  val httpProtocol = http.baseUrl("http://api.store.local")
    .acceptHeader("application/json")
    .contentTypeHeader("application/json")

  val scn = scenario("Order Checkout Flow")
    .exec(http("Login")
      .post("/api/v1/login")
      .body(StringBody("""{"user": "test_user", "pass": "secret"}""")).asJson)
    .pause(2) // Simulate "think time"
    .exec(http("Get Product")
      .get("/api/v1/products/123"))
    .pause(1)
    .exec(http("Place Order")
      .post("/api/v1/orders")
      .body(StringBody("""{"productId": 123, "qty": 1}""")).asJson
      .check(status.is(201)))

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

Notice the pause calls. This is a detail many people miss. Real users don't click buttons every 10 milliseconds. If you omit pauses, you're not load testing; you're essentially performing a Denial of Service (DoS) attack on your own infrastructure, which gives you skewed results.

Ramping Up the Pressure

The most critical part of a load test isn't the "peak" load, but how you get there. If you slam a system with 1,000 users instantly (atOnceUsers), you might crash the system simply because the connection pools haven't had time to warm up or the JIT compiler hasn't optimized the hot paths. I always recommend a "ramp-up" period.

By using rampUsers(100).during(30), you're telling Gatling to gradually introduce users over 30 seconds. This allows you to watch the telemetry in real-time. You'll often see a "knee" in the graph—a specific point where the response time stops being linear and starts curving upward exponentially. That "knee" is your actual maximum capacity. Once you find that point, you know exactly where your bottleneck is, whether it's CPU saturation or a locking issue in your database.

Deciphering the Latency Percentiles

When Gatling finishes, it gives you a report. The first mistake I see developers make is looking at the "Average Response Time." Averages are liars. If 99 users have a 10ms response time and one user has a 10-second response time, your average is roughly 110ms. Everything looks "fine," but one of your customers had a miserable experience.

You need to look at the 95th and 99th percentiles (p95 and p99). The p99 tells you the worst-case scenario for 1% of your users. In a high-performance Scala API, your goal is to keep the p99 as close to the p50 (median) as possible. If there's a massive gap between the median and the p99, you likely have "stop-the-world" GC pauses or occasional lock contention that is killing performance for a small slice of your traffic.

📋 Practical Task

Exercise: Stress Testing the Inventory Stock API

You have been handed a Scala API that manages product inventory. There is a specific endpoint, GET /api/v1/inventory/{productId}, which is suspected of having a performance regression when the cache misses and it has to hit the database.

Your task is to create a Gatling Simulation class called InventoryStressTest that implements the following requirements:

• Base URL: http://inventory-service.internal
• The Scenario:
  • Perform a GET request to /api/v1/inventory/prod-100.
  • Verify that the response status is 200 OK.
  • Add a random pause between 1 and 3 seconds to simulate a user browsing different items.
  • Perform a GET request to /api/v1/inventory/prod-200.
• The Load Profile:
  • Slowly ramp up from 0 to 50 concurrent users over a period of 60 seconds.

Write the complete Scala code for this simulation. Ensure you include the necessary imports for Gatling's Core and HTTP modules.