Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Distributed Testing

Distributed Testing Architecture: Controller and Agents

Understand how JMeter distributed testing works: one controller, many agents, RMI communication, why total load multiplies, and when one machine is not enough.

One JMeter instance on a good machine can drive a few thousand virtual users against a simple HTTP service. Beyond that, the load generator itself becomes the bottleneck: CPU saturates, garbage collection pauses distort timings, or the network card runs out of bandwidth. When that happens, you spread the work across several machines. JMeter calls this distributed testing (older documentation says "master and slaves"; current terms are controller and agents, also called workers).

JMeter cannot run on this site. The commands below are the real ones; the runnable code is a Python stand-in that illustrates the arithmetic.

The roles

flowchart LR
    C["Controller<br/>(runs the GUI or CLI, sends the .jmx)"]
    A1["Agent 1<br/>jmeter-server"]
    A2["Agent 2<br/>jmeter-server"]
    A3["Agent 3<br/>jmeter-server"]
    T["System under test"]
    C -- "RMI: start, stop, results" --> A1
    C -- "RMI" --> A2
    C -- "RMI" --> A3
    A1 -- "HTTP load" --> T
    A2 -- "HTTP load" --> T
    A3 -- "HTTP load" --> T

The controller coordinates. The agents generate the load. Only the agents talk to the system under test.

  • The controller (client) holds the .jmx file. It tells every agent to start, stop or shut down, and it collects sample results.
  • Each agent (server) runs the jmeter-server script, which starts an RMI (Remote Method Invocation) service waiting for commands. It executes the full test plan with its own threads.
  • The system under test sees requests coming from every agent's IP address.

The rule everyone forgets: load multiplies

The controller sends the same plan to every agent, and each agent runs it in full. If the Thread Group has 200 threads and you use 5 agents, the system under test receives load from 1,000 threads. JMeter does not divide the threads for you.

Python Stand-in: total load across agents

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

So when you plan 3,000 users on 6 agents, set the Thread Group to 500 threads, not 3,000. The same applies to loop counts and throughput timers: a Constant Throughput Timer set to 600 requests per minute gives 600 per minute per agent unless you scale it.

What is sent over RMI

  • Test plan: transferred to the agents at start time. File data used by CSV Data Set Config is not transferred automatically: put the file in the same relative path on every agent.
  • Results: each agent streams sample results back to the controller, which writes them to its listeners. Sending everything puts a load on the controller and the network. The property mode in jmeter.properties controls this (Standard sends every sample; Batch and Statistical reduce traffic; StrippedBatch removes response bodies). The default StrippedBatch is usually fine; use as little listener output as you can.
  • Control messages: start, stop (graceful), shutdown, and exit.

Network requirements

  • Controller and agents must be able to reach each other on the RMI ports. By default the agent uses port 1099 for the registry plus a random port for the server object. Pin it with server.rmi.localport in jmeter.properties (for example 4000) so firewalls can be configured.
  • The controller also opens a port the agents call back to (client.rmi.localport), so firewalls must allow both directions.
  • NAT and cloud networks can break RMI because the agent advertises an unreachable address. Set java.rmi.server.hostname to the address the controller can reach.
  • Keep the agents and the controller in the same network, ideally the same cloud region, so network latency does not distort the controller link. The agents themselves can be anywhere if you want to test from several geographies.

Security

Since JMeter 4, RMI uses SSL by default. You create a keystore with the create-rmi-keystore.sh script (or .bat) in the bin folder and copy the resulting rmi_keystore.jks to every machine, controller included. For a throw-away lab you can disable it with server.rmi.ssl.disable=true, but do that only on a private network. An open agent port lets anyone who can reach it run code, because a JMeter test plan can contain scripts.

When do you really need distribution?

Try these first:

  1. Run in non-GUI mode. The GUI wastes a lot of resources.
  2. Remove heavy listeners and large assertions on huge bodies.
  3. Give the JVM enough heap (-Xms/-Xmx) and a modern garbage collector.
  4. Check whether your test can be expressed with fewer, more realistic threads (think times matter).

Use more agents when one machine is saturated (CPU above about 75 percent, or the network card near its capacity), or when you need load coming from several locations or IP addresses.

Alternatives to RMI distribution

Many teams run several independent non-GUI instances (for example one container per instance in Kubernetes) and merge their .jtl result files afterward. That avoids RMI problems and the controller bottleneck. Both approaches are covered in setting up remote agents and sizing and tuning agents.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A plan has a Thread Group with 100 threads and runs on 4 agents. How many virtual users hit the server?

    Every agent runs the full plan, so threads multiply by the number of agents.
  2. 2. Which machine sends HTTP load to the system under test?

    Agents execute the plan. The controller only coordinates and collects results unless it also runs its own threads in a non-distributed run.
  3. 3. What must you do with CSV data files in a distributed test?

    Only the test plan is sent; data files must already exist on every agent.
  4. 4. Which protocol do the controller and agents use to talk?

    JMeter distributed mode uses Java RMI, secured with SSL by default in current versions.

Summary

  • Distributed testing uses one controller and many agents running jmeter-server.
  • Every agent runs the full test plan, so the load multiplies by the number of agents.
  • Data files and plugins must exist on every agent; results flow back over RMI.
  • Pin RMI ports, set the hostname, and use the SSL keystore.
  • Before adding agents, make sure the single instance is not slowed down by the GUI or listeners.

Next: Setting Up Remote Agents