Configuring Loss Injection

Loss injection is how you stress the recovery path before production does it for you. The Java media driver lets you bake a loss rate into the driver at JVM startup through system properties — deterministic and reproducible, which is exactly what automated tests and CI need.

This page is about wiring up that static loss injection and reading its effect. For how Aeron actually detects gaps and retransmits, defer to The Aeron Files. For the same io.aeron.driver.ext mechanism alongside CUBIC congestion control, see Loss Injection & CUBIC Congestion Control.

Static configuration via system properties

Set loss parameters at JVM startup. These properties are consumed by DebugChannelEndpointConfiguration.

The rate properties do nothing on their own — the default channel endpoints never consult a loss generator. You must first swap in the debug endpoints, which is a separate property per side:

-Daeron.ReceiveChannelEndpoint.supplier=io.aeron.driver.ext.DebugReceiveChannelEndpointSupplier
-Daeron.SendChannelEndpoint.supplier=io.aeron.driver.ext.DebugSendChannelEndpointSupplier

Property	Description
aeron.debug.receive.data.loss.rate	Receive data loss rate (0.0 - 1.0)
aeron.debug.receive.data.loss.seed	Seed for receive data loss RNG
aeron.debug.receive.control.loss.rate	Receive control loss rate
aeron.debug.receive.control.loss.seed	Seed for receive control loss RNG
aeron.debug.send.data.loss.rate	Send data loss rate
aeron.debug.send.data.loss.seed	Seed for send data loss RNG
aeron.debug.send.control.loss.rate	Send control loss rate
aeron.debug.send.control.loss.seed	Seed for send control loss RNG

You get four independent loss knobs: send/receive crossed with data/control. The most interesting tests come from asymmetric configurations.

Four design points that make loss injection realistic

The framework rests on four deliberate design decisions.

1. Data and control loss are independent

Data packets and control packets — status messages, NAKs, RTT — have separate loss generators. This lets you test “data gets through but NAKs are lost.” That scenario probes whether the system recovers when its recovery mechanism itself is impaired.

2. Two loss models — random rate vs. scripted gaps

The *.loss.rate properties above wire to RandomLossGenerator, whose per-frame decision is literally random.nextDouble() <= lossRate. It is not retransmission-aware: at a given rate it will drop retransmissions at that same rate — realistic for a lossy link, but it means a high rate can stack retransmits.

The package also ships FixedLossGenerator and MultiGapLossGenerator, which are retransmission-aware: they track which frames have already been dropped per stream and session and let the retransmission through. Without that, a “drop frame #42” rule would also drop the retransmission of #42 — an unrecoverable gap and an infinite retransmission loop. But the system-property mechanism never instantiates these two — they’re for programmatic setups (e.g. JavaTestMediaDriver). Use the properties for uniform random loss; reach for the programmatic path when you need a scripted, retransmission-aware gap pattern.

3. Seeds make runs deterministic

Every random loss generator accepts a seed. A fixed seed means the same loss pattern means the same test outcome. This is what makes flaky-looking tests reproducible — critical for CI/CD where you need consistent pass/fail behavior.

4. NAK coalescing can be disabled

Call dontCoalesceNaksOnReceiverByDefault() to set NAK delay to zero. NAKs are sent immediately instead of waiting for the coalescing window. This speeds up retransmission in tests without changing the loss behavior.

Key Insight

The retransmission-awareness is the most subtle and important design point. Aeron’s loss generators only drop the first occurrence of a frame, so the tests are realistic rather than pathological. And the most revealing test scenarios are asymmetric: high receive control loss (NAKs get lost) combined with low data loss (most data arrives). That combination tests recovery when the recovery channel is the thing that is broken.

Dynamic, runtime loss control

Static configuration fixes the loss rate at JVM startup, which is what makes it reproducible. If you instead need to dial loss up and down on a running driver — for live demos or exploratory chaos testing — that calls for a runtime tool rather than these properties. Such tooling is out of scope for this page.

Counters to watch when loss is injected

These four counters tell you how the system detects, recovers, and pays for loss.

Counter	What it tells you
NAK messages sent/received	Spikes when loss is active — shows detection speed
Retransmits sent	Shows recovery activity — how much bandwidth is spent on recovery
Publisher pos vs Subscriber pos	Gap grows under loss — shows how far behind the subscriber falls
Bytes sent/received	Throughput impact — quantifies the cost of loss

How loss maps to p50, p99, and throughput

Loss injection moves all three numbers, but not evenly.

• Throughput takes the most direct hit. Retransmits sent compete for the same bandwidth as fresh data, and the bytes sent/received counters quantify that cost in real time.
• p99 and the tail stretch first. A dropped frame stalls the subscriber until detection and retransmission complete. NAK detection speed and the coalescing window set how long that stall lasts — which is exactly why dontCoalesceNaksOnReceiverByDefault() shortens it.
• p50 stays comparatively stable at low loss rates, because most messages arrive on the first try. It degrades only as loss climbs high enough to affect the median delivery.

Key Insight

The most revealing metric is the gap between publisher position and subscriber position. It shows exactly how much data is “in limbo” during a loss event. With a fixed seed you can re-run the identical loss pattern and watch how quickly the gap closes once recovery kicks in — that recovery speed is your system’s true resilience characteristic, and it is the number a single unseeded run cannot show you reliably.