skip to content

In Gatling's Java DSL, what do deploymentInfo.indexOfLoadGeneratorInRun and deploymentInfo.numberOfLoadGeneratorsInRun return when the simulation is not running on Gatling Enterprise?

level: seniorimportance: nice to knowfreq 18%

answer

  1. an Enterprise deployment helper
  2. constants, not measurements
  3. index 0, count 1
  4. runId is null off Enterprise
  5. added in Gatling 3.11

basics

~20 s

0 and 1, as hardwired constants rather than measurements. Every injector outside Gatling Enterprise reports that it is generator 0 of 1, so code that branches or slices on those values behaves identically on every machine.

solid answer

~40 s

`deploymentInfo` is a helper added in Gatling 3.11 that reports where a load generator sits inside a Gatling Enterprise deployment. Outside Enterprise its values are fixed: `numberOfLoadGeneratorsInRun` is `1`, `indexOfLoadGeneratorInRun` is `0`, and the Location-scoped pair is hardwired the same way. `runId` and `locationName` come back `null` in Java and `None` in Scala, and `logFiles()` is empty. So a guard such as `if (indexOfLoadGeneratorInRun == 0)` fires on every hand-launched machine instead of one of them, and slicing input by `numberOfLoadGeneratorsInRun` hands every machine the whole set. Nothing warns you, because the values look perfectly valid. The helper exists in the Java, Kotlin and Scala APIs; Gatling's documentation marks it not supported for the JavaScript and TypeScript SDK.

code

java · 21 lines
java
import static io.gatling.javaapi.core.CoreDsl.*;
import static io.gatling.javaapi.http.HttpDsl.*;

import io.gatling.javaapi.core.ScenarioBuilder;
import io.gatling.javaapi.core.Simulation;

public class GeneratorAwareSimulation extends Simulation {

  private final int index = deploymentInfo.indexOfLoadGeneratorInRun;
  private final int total = deploymentInfo.numberOfLoadGeneratorsInRun;

  private final ScenarioBuilder scn =
      scenario("slice " + index + " of " + total)
          .exec(http("home").get("/"));

  {
    System.out.println("generator " + index + " of " + total);
    setUp(scn.injectOpen(atOnceUsers(100 / total)))
        .protocols(http.baseUrl("https://example.com"));
  }
}

go deeper

for a junior

Recall that deploymentInfo describes a Gatling Enterprise deployment, and that outside it the counts are fixed at one generator with index zero.

for a middle

Be ready to name the fields and their off-Enterprise values, and to explain why dividing input by numberOfLoadGeneratorsInRun is a division by one on a developer machine.

for a senior

Be ready to spot the failure in review: a once-per-run side effect guarded on generator index zero fires on every hand-launched injector, because every one of them reports index zero.

for a principal

Own the position on run-scoped side effects inside a load simulation at all, given that the only signal that would make them safe is supplied by a product you may not be running.

## What `deploymentInfo` is `deploymentInfo` is a small helper, added in **Gatling 3.11**, that lets a simulation ask where it is running inside a **Gatling Enterprise** deployment. In the Java API it is a static member of `CoreDsl`, so a simulation that static-imports `io.gatling.javaapi.core.CoreDsl.*` can read its fields directly; in Scala it is an object reachable through `io.gatling.core.Predef._`. It exposes six values and one method: | member | meaning on Gatling Enterprise | value off Enterprise | |---|---|---| | `runId` | the UUID of the run | `null` in Java, `None` in Scala | | `locationName` | the Location this generator sits in | `null` in Java, `None` in Scala | | `numberOfLoadGeneratorsInLocation` | generators in this Location | `1` | | `indexOfLoadGeneratorInLocation` | this generator's index in the Location | `0` | | `numberOfLoadGeneratorsInRun` | generators in the whole run | `1` | | `indexOfLoadGeneratorInRun` | this generator's index in the run | `0` | | `logFiles()` | this generator's log files | empty list | ## The answer, and why it is a constant rather than a measurement Off Gatling Enterprise, `indexOfLoadGeneratorInRun` returns **0** and `numberOfLoadGeneratorsInRun` returns **1**. They are not "unknown", not `-1`, and not derived from anything the JVM can observe about its neighbours. They are **hardwired constants** in the Community Edition, and Gatling's documentation states the whole helper is *"only effective when running with Gatling Enterprise Edition, otherwise it's just a noop."* That is the crux: the values are perfectly valid-looking. Nothing throws, nothing logs a warning, and no branch reports that the fleet information is unavailable. Every hand-launched injector sincerely reports that it is generator **0 of 1**. ## The two failure shapes this produces Both are silent, and both look correct in review. 1. **The "leader" guard.** A simulation that does something once per run — seed reference data, truncate a table, register a webhook — behind `if (deploymentInfo.indexOfLoadGeneratorInRun == 0)`. On Gatling Enterprise exactly one generator takes that branch. On four hand-launched injectors, **all four** take it, because all four are index 0. The side effect happens four times, concurrently, at the start of a load run. 2. **The slice.** Code that carves its input with `records.size() / numberOfLoadGeneratorsInRun`, or that offsets into a list by the generator index. Divided by 1 and offset by 0, every machine receives the **whole** set — which is precisely the overlap the code was written to prevent. Note that the Location-scoped pair, `indexOfLoadGeneratorInLocation` and `numberOfLoadGeneratorsInLocation`, is hardwired the same way, to `0` and `1`. Falling back to those fields does not rescue either shape. ## The SDK boundary The helper exists in **Java, Kotlin and Scala**. Gatling's documentation shows it in all three, and the JavaScript/TypeScript sample for the very same documentation section is marked `NOT SUPPORTED`. So a simulation that has to be generator-aware has to be written in one of the JVM SDKs; there is nothing in the JavaScript or TypeScript surface to read. This is worth stating explicitly whenever the helper comes up, because most of the injection and DSL vocabulary really is shared across all the SDKs and it is easy to assume this one is too. ## What to use instead when you are not on Enterprise If you are hand-running several injectors, the node index and node count have to come from you, because Gatling cannot supply them: - Pass them in as **system properties** or environment variables, one distinct value per machine, and read them in the simulation as ordinary code. - Prefer them to be **loud**. A machine that was launched without its index should fail fast rather than default to 0, otherwise you have rebuilt the exact bug `deploymentInfo` produces. - Better still, avoid run-scoped side effects inside the simulation altogether. Seeding, truncating and registering are pipeline steps that run once before the fan-out; putting them inside a simulation makes correctness depend on a fleet signal that the edition you are running does not provide. ## Version framing The helper landed in **3.11** and is unchanged in behaviour on the **3.15.x** line: still Enterprise-scoped, still hardwired to index `0` of `1` generator everywhere else. A candidate who remembers "there is a way to find out which injector you are" is half right; the other half is that the answer is only true where a product is supplying it.

  • What does Gatling's deploymentInfo.runId hold on a run that is not deployed on Gatling Enterprise?
    Nothing usable: it is `null` in the Java API and `None` in Scala. There is no run-wide identifier stamped into a Community Edition run's artefacts, so several machines launched together carry no shared id you could correlate their results directories by.
  • Is deploymentInfo available in every Gatling SDK?
    No. Gatling's documentation shows the helper for Java, Kotlin and Scala, while the JavaScript and TypeScript sample for the same documentation section is marked NOT SUPPORTED. Generator-aware code has to be written in one of the JVM SDKs, or not at all.

saying these in an interview costs you the question

  • Thinking indexOfLoadGeneratorInRun distinguishes hand-launched injectors
  • Using a generator-index guard to make one machine seed data
  • Expecting deploymentInfo.runId to correlate several machines' results
  • Assuming the JavaScript and TypeScript SDK exposes deploymentInfo