net.latency-summary

def summarise_latency(samples_us: Sequence[Optional[int]]) -> LatencySummary

@dataclass(frozen=True)
class LatencySummary:
    """What a run of probes says about a link, as ping prints it."""

    sent: int
    received: int
    lost: int
    #: lost / sent, rounded half-up; 10000 = every probe lost
    loss_basis_points: int
    #: null when nothing was received
    min_us: Optional[int]
    #: mean, rounded half-up to a whole microsecond
    avg_us: Optional[int]
    max_us: Optional[int]
    #: nearest-rank 95th percentile, a sample that was really seen
    p95_us: Optional[int]
    #: mean absolute difference of consecutive received samples, half-up; null under two
    jitter_us: Optional[int]

from fune.net.latency_summary import summarise_latency  # net.latency-summary@^1

from typing import List, Optional, Sequence

from .math_round_div import round_div  ← from math.round-div ^1.0.0 · built alongside by fune
from .stats_percentile import percentile  ← from stats.percentile ^2.0.0 · built alongside by fune
from .net_latency_summary_types import LatencySummary


def summarise_latency(samples_us: Sequence[Optional[int]]) -> LatencySummary:
    """Summarise a run of probes the way ping does, in whole microseconds.

    Integer microseconds rather than float milliseconds, so every language
    gives the same answer and a vector can compare exactly. A lost probe counts
    towards loss and is skipped (not a break) when measuring jitter.
    """
    if isinstance(samples_us, (str, bytes)) or not isinstance(samples_us, (list, tuple)):
        raise TypeError("samplesUs must be a list")
    if len(samples_us) == 0:
        raise ValueError("samplesUs must not be empty")
    got: List[int] = []
    for s in samples_us:
        if s is None:
            continue
        if isinstance(s, bool) or not (isinstance(s, int) or (isinstance(s, float) and s.is_integer())):
            raise TypeError("each sample must be a whole number of microseconds or null, received %r" % (s,))
        s = int(s)
        if s < 0:
            raise ValueError("samples must not be negative, received %d" % s)
        got.append(s)
    sent = len(samples_us)
    received = len(got)
    lost = sent - received
    loss = round_div(lost * 10000, sent, "half-up")
    if received == 0:
        return LatencySummary(sent=sent, received=received, lost=lost, loss_basis_points=loss,
                              min_us=None, avg_us=None, max_us=None, p95_us=None, jitter_us=None)
    jitter = None
    if received >= 2:
        diffs = sum(abs(got[i] - got[i - 1]) for i in range(1, received))
        jitter = round_div(diffs, received - 1, "half-up")
    # Nearest-rank returns a sample that was really seen, so it is a whole number.
    p95 = int(percentile([float(v) for v in got], 95, "nearest-rank", 0))
    return LatencySummary(
        sent=sent,
        received=received,
        lost=lost,
        loss_basis_points=loss,
        min_us=min(got),
        avg_us=round_div(sum(got), received, "half-up"),
        max_us=max(got),
        p95_us=p95,
        jitter_us=jitter,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add net.latency-summary

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./net.latency-summary-1.0.0-python.fune, or fetch it from a terminal with fune pull net.latency-summary@1.0.0:python.

The whole function, every language, is one file too: net.latency-summary-1.0.0.fune, 16,995 bytes, sha256 c5e4c99d628f4ef623dfefae12ed3b64b1ec4e9e410a83d09c0d2247bd5d9cb0. It installs into a project of any language.

# fune: before net.latency-summary

# fune: after net.latency-summary

# fune: replace math.round-div in net.latency-summary
# fune: replace stats.percentile in net.latency-summary

# fune: step net.latency-summary after <n|label>

More from the author

- **Input is whole microseconds, `null` for a lost probe**, in the order the probes were sent. Integers keep all three languages identical and let the vectors compare exactly; a caller timing with a monotonic clock converts once (`elapsed.as_micros()`). - **Loss** is `lost / sent` in basis points, rounded half-up (`math.round-div`): 1 of 3 lost is 3333, 2 of 3 is 6667, all lost is 10000. - **avg** is the mean of the received samples, rounded half-up to a whole microsecond. - **p95** is the nearest-rank 95th percentile (`stats.percentile`, `nearest-rank`): the smallest sample with at least 95% of samples at or below it. It is always a sample that was really seen; for 20 samples it is the 19th smallest, not the maximum. - **jitter** is the mean absolute difference between consecutive *received* samples, in send order, rounded half-up. A lost probe is skipped, not a break, so `[1000, null, 3000, 2000]` compares 1000 with 3000 and 3000 with 2000. This is the simple "mean deviation of successive round trips", not RFC 3550's exponentially smoothed interarrival jitter (which needs one-way transit times and weights recent packets); it is `null` with fewer than two replies. - With no replies, min/avg/max/p95/jitter are all `null` and loss is 10000.

## Errors

An empty list (`samplesUs must not be empty`), a negative sample (`samples must not be negative`), and a sample that is not a whole number or null (`each sample must be a whole number of microseconds or null`).

Rust callers building on this can use `latency_summary_to_value` and `latency_summary_from_value`.

Files