In a Gatling assertion, what does the `percentile3` response-time metric measure, and what can change its meaning without the simulation code changing?

## The four numbered slots are configuration, not constants Gatling's response-time metric link offers `percentile1`, `percentile2`, `percentile3` and `percentile4` alongside the explicit `percentile(value)`. The numbered four look like fixed percentiles and are almost always described as p50, p75, p95 and p99. They are not fixed. Each one reads a configuration key: | method | configuration key | default | |---|---|---| | `percentile1` | `gatling.charting.indicators.percentile1` | `50` | | `percentile2` | `gatling.charting.indicators.percentile2` | `75` | | `percentile3` | `gatling.charting.indicators.percentile3` | `95` | | `percentile4` | `gatling.charting.indicators.percentile4` | `99` | So `global().responseTime().percentile3().lt(500)` asserts that the **95th** percentile response time over all requests is under 500 ms *with the shipped defaults*. Change that one key in `gatling.conf` and the same unedited line of simulation code now asserts something else entirely. ## Why the slots exist at all These four keys were not invented for assertions. They are the four percentile columns of the HTML report's statistics table and of the console summary printed once the run is over, and the assertion methods reuse them so that the number you gate on is necessarily one of the numbers your report shows. That is a real benefit: a team that wants p90 and p99.9 in its statistics table gets assertions that can name those same figures without a second knob. The cost is the coupling. The percentile the assertion means lives in a different file from the assertion, and the key that moves it is filed under `charting` — a word that gives no hint that a pass rule depends on it. A reader of the simulation alone cannot tell what `percentile3()` means. ## How the resolution actually happens The slot is resolved **when the assertion object is built**, not when it is evaluated. `percentile3()` is defined as a call to `percentile(v)` with `v` read from the loaded configuration, so the assertion that ends up registered on `setUp` carries a literal percentile number in it. Gatling's own DSL test pins this: building `global.responseTime.percentile3.is(300)` under a test configuration produces an assertion whose target is the 95th percentile as a plain value. Two practical consequences follow: - The configuration that matters is the one loaded by the JVM running the simulation. `gatling.conf` is resolved from the **classpath**, and a system property overrides it, so `-Dgatling.charting.indicators.percentile3=99` on the command line silently changes what every `percentile3()` assertion in the suite means for that run. - Regenerating a report from an existing run does not re-resolve anything the assertion already fixed at build time; the percentile was chosen when the simulation was constructed. ## `percentile(value)` is the version that says what it means The explicit form takes the percentage directly, as a value between 0 and 100: ```java global().responseTime().percentile(95.0).lt(500); // always p95 global().responseTime().percentile(99.9).lt(3000); // p99.9, which no numbered slot reaches by default ``` Two things are worth noting about it. First, the argument is a **percentage**, so p99.9 is written `99.9` and not `0.999`; passing a fraction asks for a percentile below the first percent of the distribution. Second, `percentile(v)` is not limited to the four configured values, which is the only way to assert on a percentile your report's statistics table does not list. ## The same four keys drive what you can see Because the indicator keys also select the percentile columns of the generated HTML report's statistics table and of the console summary printed at the end of the run, the four slots tie three things together: - which percentiles the report lists in its **statistics table**; - which percentiles the final console summary prints after the run — and which therefore disappear entirely when report generation is switched off, since that summary is printed by the report generator; - which percentiles `percentile1` through `percentile4` assert on. Two things they do **not** reach are worth knowing, because both are commonly assumed. The "Response Time Percentiles over Time" chart plots a fixed ladder — min, p25, p50, p75, p80, p85, p90, p95, p99, max — computed without ever consulting the indicator keys, so retuning `percentile3` moves the statistics table and the assertion and leaves that chart exactly as it was. And the live console ticker printed while the simulation is running carries no percentiles at all: it shows elapsed time, the global and per-request OK/KO counters, errors and the per-scenario user-progression bar, and nothing else. That is useful when you want them aligned and awkward when you do not. A team that widens its reported percentiles to include p99.9 for diagnosis has, in the same edit, changed what a `percentile4()` assertion means for every simulation in the repository. Nothing about the change looks like a change to a pass rule, and code review of the simulation files will not surface it because no simulation file was touched. ## Which to use The choice is a genuine trade-off rather than a rule: 1. Use `percentile(95.0)` when the assertion must mean the same thing to anyone who reads the file, and in any suite where the configuration is not controlled by the same people who own the simulations. It is self-documenting and immune to a configuration change or a stray system property. 2. Use `percentile3()` when you deliberately want the gate and the report to move together — a team that re-tunes its reported percentiles and wants the pass rules to follow automatically. If you take the numbered form, state the resolved percentile in a comment beside it, and treat the four keys as part of the suite's public contract rather than as a display preference. The failure mode is quiet: nothing errors, nothing warns, and the run simply starts judging a different percentile than the one everybody believes is being judged.