docs(features): quantify the kernel netem correl bias that collapses small rates

The kernel's correlated-random generator (get_crandom, sch_netem.c) truncates
instead of wrapping, starving both edges of the stationary distribution: an
event threshold below the correlation value is almost never reached. Measured
with stock iproute2 on this kernel — uBridge's netlink encoding is identical:
loss 1% + correl 25% drops nothing over 2000 pings (expected ~2%), 10%/25%
measures ~1.8% one way, only the 50% symmetry point survives. duplicate and
reorder correl share the same comparison structure and collapse the same way;
gemodel is immune (Markov chain over plain uniform draws) and is the honest
tool for bursty loss at a chosen mean rate.

Documented in the packet-filters correlation-bias bullet, and surfaced in the
two machine-facing descriptions (MCP link_update packet_loss note, controller
filter schema) so agents and clients stop walking into the trap.
This commit is contained in:
YueGuobin committed 2026-10-08 19:42:18 +08:00
1 parent 5238bd3b39
commit d640050d4b
3 files changed
+9 -3

No files matched your search

+4 -1
View File
@@ -808,7 +808,10 @@ async def link_update(
* frequency_drop: [N] - Drop every Nth packet (N: -1 to 32767; -1 = drop
everything). Exact on kernel links (eBPF counter)
* packet_loss: [chance, correl?] - Loss percentage (0-100); correl (K)
makes consecutive losses dependent (bursty)
makes consecutive losses dependent (bursty). CAVEAT: the kernel netem
correl suppresses small rates — a chance below ~the correl value drops
almost nothing (1% + correl 25% ≈ zero loss); use gemodel for bursty
loss at a known mean rate
* delay: [ms, jitter?, distribution?] - Latency 1-32767 ms, jitter 0-32767
ms; distribution (K) one of uniform|normal|pareto|paretonormal, needs
jitter > 0