Record HTTP Traffic into Gatling Simulations with the Proxy Recorder (2026)

The Gatling Proxy Recorder lets you capture HTTP traffic and turn it into a performance test simulation, but it’s not about just recording; it’s about transforming raw network chatter into structured, executable test scenarios.

Let’s see this in action. Imagine you’re testing a simple API endpoint that fetches user data. First, you start the recorder:

./bin/recorder --port 8000 --output-dir src/test/scala/simulations

Now, configure your browser or application to use localhost:8000 as its HTTP proxy. Navigate to your target URL, say http://localhost:8080/users/123. The recorder intercepts this request. Inside your src/test/scala/simulations directory, a file like RecordedSimulation.scala will start to populate.

Here’s a snippet of what it might look like after you’ve made a few requests:

import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._

class RecordedSimulation extends Simulation {

  val httpProtocol = http
    .baseUrl("http://localhost:8080")
    .inferHtmlResources()
    .acceptHeader("text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
    .acceptEncodingHeader("gzip")
    .acceptLanguageHeader("fr,en-us;q=0.7,en;q=0.3")
    .doNotTrackHeader("1")
    .userAgentHeader("Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36")

  val scn = scenario("RecordedScenario")
    .exec(http("request_0")
      .get("/users/123")
      .check(status.is(200))
      .check(jsonPath("$.id").is("123")))
    .pause(7)

  setUp(scn.inject(atOnceUsers(1))).protocols(httpProtocol)
}

This isn’t just a log; it’s a Gatling simulation. The recorder automatically identifies the base URL, infers resources (like CSS, JS, images), sets common headers like Accept and User-Agent, and even attempts to generate basic checks for status codes and JSON paths. The pause(7) is a crucial addition, representing the time Gatling observed between requests, which is vital for realistic load testing.

The core problem Gatling’s recorder solves is the tedious manual translation of user interactions into code. Instead of writing http("request_name").get("/path") for every single request and meticulously managing headers, you browse your application, and Gatling handles the heavy lifting of generating the initial simulation structure. It provides a tangible starting point, drastically reducing the ramp-up time for creating performance tests for existing applications.

Internally, the recorder acts as an HTTP proxy. It sits between your client (browser/app) and the target server. It inspects every request and response passing through it. For each request, it extracts the method, URL, headers, and body. For responses, it notes the status code and headers. It then uses this information to construct the corresponding Gatling DSL (Domain Specific Language) code. The inferHtmlResources() part is particularly clever: if a request for an HTML page returns a 200 OK, the recorder will then make subsequent requests for all linked resources (CSS, JS, images) found within that HTML and group them into a single Gatling HTTP request for efficiency, mimicking how a browser would load a page.

You have several levers to control this process. The --port flag sets the listening port for the proxy. --output-dir specifies where the generated Scala files will be saved. More advanced options include --follow-redirects, --max-connections, and --mask to obscure sensitive data like session IDs or passwords from the generated simulation. You can also use --filter-regex to exclude specific types of requests (e.g., static assets) from being recorded.

What most people don’t realize is that the recorder’s automatic check generation is often too basic. While it might correctly identify a 200 status, it rarely captures meaningful assertions about the content of the response. For instance, it might record a jsonPath("$.some_field") but not know what value some_field is supposed to have. This means you’ll always need to manually review and enhance the generated checks to ensure your tests are validating the actual business logic and not just that the server responded.

Once you’ve recorded your traffic, the next step is to understand how to inject realistic user loads using Gatling’s setUp and inject methods.