The most surprising thing about Gatling log files is that they’re not just logs; they’re a detailed, time-traveling blueprint of your system’s stress response.
Let’s see this blueprint in action. Imagine you’ve just run a Gatling simulation against your API, and you’re looking at the index.html report. This isn’t just a static page; it’s a dynamic dashboard generated from your simulation logs. You’ll see graphs showing request counts, response times, and error rates over time. For instance, a spike in "5xx" errors on the "Login API" endpoint, correlating with a sharp increase in response time for that same endpoint, tells a story: something broke under load.
This report is generated from the simulation.log file. It’s a plain text file, usually found in the results/<simulation-name>/ directory. Each line represents an event: a request sent, a response received, or an error encountered. Gatling parses this log to create the HTML report, but you can also analyze it directly for deeper insights.
The core problem Gatling simulations help you solve is understanding how your application behaves under concurrent user load. It answers questions like: "What happens to my database when 1000 users try to access it simultaneously?" or "Will my web server crash if we get a sudden traffic surge?"
Internally, Gatling works by simulating virtual users. Each user executes a scenario you define. These scenarios involve making HTTP requests, checking responses, and pausing. Gatling manages thousands of these users concurrently, meticulously recording every interaction. The simulation.log captures all these interactions as structured data.
Here’s a snippet of what a simulation.log line might look like:
2023-10-27T10:30:01.123Z | 127.0.0.1 | 1000 | my_scenario | 10000 | REQUEST | http://localhost:8080/api/users | 200 | OK | 1500 | 5000 | 0 | 0
Let’s break this down:
2023-10-27T10:30:01.123Z: Timestamp of the event.127.0.0.1: The IP address of the Gatling client.1000: The simulation ID.my_scenario: The name of the executed scenario.10000: The user ID within the scenario.REQUEST: The type of event (REQUEST, RESPONSE, etc.).http://localhost:8080/api/users: The URL being accessed.200: The HTTP status code of the response.OK: The status text.1500: The start time of the request in milliseconds since the simulation started.5000: The end time of the response in milliseconds since the simulation started.0: Number of bytes sent.0: Number of bytes received.
The true power comes from analyzing these logs programmatically. You can use tools like grep, awk, or even write custom scripts in Python or Scala to extract specific information. For example, to find all requests that took longer than 2 seconds (2000ms) and resulted in a 500 error, you could use:
grep 'REQUEST' results/my-simulation/simulation.log | awk '$8 ~ /500/ && ($10 - $9) > 2000 {print $0}'
This command filters for lines containing "REQUEST", then checks if the status code ($8) is "500" AND if the duration ($10 - $9) is greater than 2000 milliseconds.
The most common pitfall is treating the HTML report as the only source of truth. While excellent for high-level overviews, it aggregates data. If you need to understand the exact sequence of events leading to a specific failure for a single user, or identify intermittent, hard-to-reproduce issues, diving into the raw simulation.log is essential. You can reconstruct a user’s journey or pinpoint the precise request that caused a cascade of errors by following a specific user ID across multiple log lines.
Beyond request/response data, the simulation.log also captures finer-grained details like connection errors, SSL handshake failures, and timeouts, which are crucial for diagnosing infrastructure-level problems.
The next logical step after mastering log analysis is to integrate Gatling with your CI/CD pipeline, automatically running simulations on code changes and failing builds if performance regressions are detected.