Measure relay load

Use BlitzRelay.LoadHarness to compare relay changes or test a deployment with a repeatable workload. The harness creates rooms with simulated hosts and clients, sends traffic in both directions, and reports message delivery and latency.

Before you run the examples, install the .NET 10 SDK and Task. Run the commands from the relay repository’s root directory. task load runs the harness in Release configuration. The harness is a source project, not part of the server release executable.

Start with a local run

Simulate 10 rooms with four clients each:

task load -- --rooms 10 --clients 4 --tick-rate 30 --payload-size 128 --channel Unreliable

If you omit --relay-address, the harness starts an in-process relay on an available local UDP port. You do not need a separate relay process or the server’s environment variables.

On each tick, every host broadcasts a message, and every client sends a message to its host. This example runs at 30 ticks per second. In the delivery results, each host broadcast counts once per recipient.

Target a separate relay process

Start a test relay with its usual configuration. Then pass its UDP endpoint and connection key to the harness:

task load -- --relay-address 127.0.0.1 --relay-port 7770 --connection-key your-connection-key --rooms 50 --clients 8 --channel UnreliableSequenced

If you pass --relay-address, you must also pass --connection-key. The harness creates ephemeral rooms on that relay without using the HTTP API or admin token.

To measure the server’s resource use independently of the simulated peers, use a separate relay process. Collect CPU, memory, and allocation data for that process separately. The harness’s resource measurements do not include an external relay.

Choose the workload

Configure the simulated traffic with the following options:

Option	Default	Meaning
--rooms	50	Number of simulated rooms.
--clients	8	Clients per room.
--tick-rate	30	Sends per second from each host and client.
--payload-size	128	Game-payload bytes, including the send timestamp; minimum 8.
--channel	Unreliable	Reliable, Unreliable, or UnreliableSequenced.
--warmup	5	Warm-up seconds before measurement.
--duration	30	Measured seconds.
--threads	At least 1, normally processor count / 4	Threads driving the simulated peers, limited to the room count.

Keep payloads at or below 1,343 bytes for Unreliable and 1,340 bytes for UnreliableSequenced. These limits account for both relay hops at the current maximum transmission unit (MTU). The harness rejects a larger --payload-size before starting the run.

When comparing results, change one workload setting at a time. Keep the machine, relay configuration, channel, and measurement interval the same.

Read the results

The harness runs a warm-up period, a measurement interval, and a one-second period to receive pending traffic. Only messages sent during the measurement interval count towards the results.

Interpret the reported measurements as follows:

• Delivered and expected message counts show how much traffic arrived in each direction. Unreliable traffic can be lost, and sequenced delivery can discard older packets.
• Messages per second measures delivered messages, not attempted sends.
• Latency percentiles show the distribution of delivery times. Compare the high percentiles and the median.
• Disconnected peers can indicate that recipients reached the relay’s reliable-backlog limit. Check the relay logs to identify the cause.
• Allocations and garbage collection (GC) counts describe the harness process during measurement. Local mode includes the relay and simulated peers. External mode includes only the harness.

The harness threads poll continuously to timestamp messages, so the harness does not report CPU use. To measure the relay’s CPU use, run it as a separate process and monitor that process while the harness targets it with --relay-address.

The harness measures simulated traffic, not your game’s full workload. Before you use a load result to estimate player capacity, test a session with your game and expected update sizes.