README
¶
loom
loom is a distributed network traffic generation and measurement system for Linux. It weaves many independent traffic flows — raw protocols and realistic application behaviors — across many machines, on a schedule you define, and measures what happens in real time.
Think of it as iperf when you want a quick number, and a programmable traffic fabric when you don't: a measured client→server throughput test, or a declarative scenario driving dozens of agents with overlapping, randomized flows.
Measure throughput between two hosts (the iperf-style test). Run an agent on each host, then drive a flow between them from anywhere — both sides are measured:
# on the server host and the client host: run the agent
$ LOOMD_ADDR=:9551 loomd
# from your workstation: drive a 1 Gbps UDP flow client → server for 10s
$ cat > test.yaml <<'EOF'
scenario: quick-test
endpoints: [ { name: client }, { name: server } ]
timeline:
- name: blast
flow: { kind: udp, rate: 1Gbps, packet_size: 1400 }
from: client
to: server
start: 0s
stop: { after: 10s }
EOF
$ loomctl run -f test.yaml -a 'client=10.0.0.1:9551,server=10.0.0.2:9551'
[14:03:01] tx 0.99 Gbps rx 0.99 Gbps (2 flows)
...
--- summary --- elapsed 10.1s
tx 1.24 GB avg 0.99 Gbps
rx 1.24 GB avg 0.99 Gbps
The run ends as soon as the flow finishes (not at the horizon); add --per-flow
for a per-flow breakdown — handy when flows take different network paths.
Or a quick one-host check — generate, pace, and measure a flow locally with
no receiver (the discard datapath drops after accounting):
$ loom run --rate 50Mbps --duration 5s
[ 1.0s] 49.98 Mbps 4459 pkts 5.95 MB
--- summary --- sent 29.7 MB in 22300 packets, avg 49.9 Mbps
Why loom
- One tool, two modes. A single-flow CLI for quick tests, and a control plane that runs multi-point scenarios across a fleet of agents.
- Realistic, not just packet-blasting. Raw UDP/TCP today; HTTPS/VoIP/SSH/ Prometheus/FTP behavior emulation on the roadmap.
- Fast where it counts. A zero-copy data plane with pluggable backends — kernel sockets by default, AF_XDP for line-rate, DPDK to come — behind one interface, so speed is a backend choice, not a rewrite.
- Measurement-first. Streaming and end-of-run throughput, latency, jitter, and loss; one-way delay and NIC hardware timestamping are designed in.
- Reproducible. Seeded scenarios replay identically, so you can compare runs and catch regressions.
Get started
| You are… | Start here |
|---|---|
| New to loom | Getting Started → Core Concepts |
| Evaluating / an expert | Architecture → Performance |
| Deploying it | Deployment |
| Looking something up | Reference · Scenario schema |
The full manual lives in docs/.
Install
curl -fsSL https://raw.githubusercontent.com/bgrewell/loom/main/scripts/install.sh | bash
Installs loom, loomd, and loomctl — prebuilt binaries when available, else
built from source. upgrade.sh and
uninstall.sh are the counterparts; tuning and options
are in scripts/README.md.
Or with the Go toolchain:
go install github.com/bgrewell/loom/cmd/loom@latest # the CLI
go install github.com/bgrewell/loom/cmd/loomd@latest # the agent
go install github.com/bgrewell/loom/cmd/loomctl@latest # the controller
Linux only for now. See Getting Started for a guided first run.
Status
Active development. The architecture is settled and the single-host engine, distributed control plane, telemetry, and an AF_XDP datapath are in; application emulations and a web dashboard are next. Design decisions are recorded as ADRs in DECISIONS.md; the plan is in docs/roadmap.md.
License
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
cmd
|
|
|
loom
command
Command loom is the loom CLI — the primary human interface to the traffic generation & measurement system.
|
Command loom is the loom CLI — the primary human interface to the traffic generation & measurement system. |
|
loomctl
command
Command loomctl is the loom controller — it loads a scenario and drives it across agents (DESIGN.md §11).
|
Command loomctl is the loom controller — it loads a scenario and drives it across agents (DESIGN.md §11). |
|
loomd
command
Command loomd is the loom agent — the only component that touches the wire.
|
Command loomd is the loom agent — the only component that touches the wire. |
|
Package control implements the loom.v1.Control gRPC service — the controller<->agent control plane (DESIGN.md §8).
|
Package control implements the loom.v1.Control gRPC service — the controller<->agent control plane (DESIGN.md §8). |
|
Package controller orchestrates a scenario across agents: it resolves the endpoints each event runs between, plans the timeline, and at each fire wires a receiver and a sender on the right agents and starts them.
|
Package controller orchestrates a scenario across agents: it resolves the endpoints each event runs between, plans the timeline, and at each fire wires a receiver and a sender on the right agents and starts them. |
|
core
|
|
|
accounting
Package accounting turns hot-path byte/packet counters into windowed throughput rates.
|
Package accounting turns hot-path byte/packet counters into windowed throughput rates. |
|
components
Package components bundles the pluggable registries (datapath/generator/ scheduler/payload) into one injectable value (ADR-0022), so a flow builder or an agent depends on an explicit Components rather than reaching into global singletons.
|
Package components bundles the pluggable registries (datapath/generator/ scheduler/payload) into one injectable value (ADR-0022), so a flow builder or an agent depends on an explicit Components rather than reaching into global singletons. |
|
contract
Package contract holds shared conformance checks that every implementation of a core interface must pass.
|
Package contract holds shared conformance checks that every implementation of a core interface must pass. |
|
datapath
Package datapath is the packet-I/O backend abstraction.
|
Package datapath is the packet-I/O backend abstraction. |
|
emul
Package emul is loom's application-behavior emulation engine: realistic traffic *shapes* (VoIP, HTTPS browsing, Prometheus, SSH) compiled to one shared behavior-script primitive and run over any datapath.
|
Package emul is loom's application-behavior emulation engine: realistic traffic *shapes* (VoIP, HTTPS browsing, Prometheus, SSH) compiled to one shared behavior-script primitive and run over any datapath. |
|
flow
Package flow is the atomic unit of traffic: a generator paced by a scheduler, sent over a datapath, accounted, and bounded by a stop condition.
|
Package flow is the atomic unit of traffic: a generator paced by a scheduler, sent over a datapath, accounted, and bounded by a stop condition. |
|
frameaddr
Package frameaddr resolves the layer-2/3 addressing a raw datapath (AF_XDP) needs to emit deliverable frames: the local NIC's MAC and IPv4, and the peer's MAC for a target on the same L2 segment.
|
Package frameaddr resolves the layer-2/3 addressing a raw datapath (AF_XDP) needs to emit deliverable frames: the local NIC's MAC and IPv4, and the peer's MAC for a target on the same L2 segment. |
|
generator
Package generator produces a flow's traffic content: it decides what bytes go in each packet, using a payload source.
|
Package generator produces a flow's traffic content: it decides what bytes go in each packet, using a payload source. |
|
latency
Package latency measures round-trip latency with typed results and an interval sampling model.
|
Package latency measures round-trip latency with typed results and an interval sampling model. |
|
log
Package log provides the two halves of loom's logging model (DESIGN.md §6): a lock-free, non-blocking hot-path event Ring drained off the data plane, and an async leveled Logger for control/diagnostic output.
|
Package log provides the two halves of loom's logging model (DESIGN.md §6): a lock-free, non-blocking hot-path event Ring drained off the data plane, and an async leveled Logger for control/diagnostic output. |
|
payload
Package payload generates the bytes a flow sends.
|
Package payload generates the bytes a flow sends. |
|
pump
Package pump is the data-plane inner loop: it draws packets from a generator, paces them with a scheduler, sends them over a datapath, and records them in accounting.
|
Package pump is the data-plane inner loop: it draws packets from a generator, paces them with a scheduler, sends them over a datapath, and records them in accounting. |
|
registry
Package registry provides a generic, concurrency-safe name→factory registry.
|
Package registry provides a generic, concurrency-safe name→factory registry. |
|
report
Package report turns a flow's live counters into streaming interval reports and an end-of-run summary, emitted to a pluggable sink (human/json/...).
|
Package report turns a flow's live counters into streaming interval reports and an end-of-run summary, emitted to a pluggable sink (human/json/...). |
|
scenario
Package scenario is the parsed model of a loom scenario file (docs/scenario-schema.md): endpoints, defaults, and a timeline of events with the value grammar (via core/units).
|
Package scenario is the parsed model of a loom scenario file (docs/scenario-schema.md): endpoints, defaults, and a timeline of events with the value grammar (via core/units). |
|
scheduler
Package scheduler paces packets within a single flow (intra-flow rate control).
|
Package scheduler paces packets within a single flow (intra-flow rate control). |
|
selection
Package selection resolves scenario endpoint selectors against the endpoint set: names, oneOf/allOf/any modes, and tag expressions like tags(all(10g, not(win))).
|
Package selection resolves scenario endpoint selectors against the endpoint set: names, oneOf/allOf/any modes, and tag expressions like tags(all(10g, not(win))). |
|
stats
Package stats provides streaming measurement math — running mean/variance, jitter, and sequence-based loss/duplicate/reorder detection — as pure values with no global state.
|
Package stats provides streaming measurement math — running mean/variance, jitter, and sequence-based loss/duplicate/reorder detection — as pure values with no global state. |
|
timeline
Package timeline turns a scenario's timeline into a schedule of "fires" — when each event (and each repeat instance) should start — and drives them in real time.
|
Package timeline turns a scenario's timeline into a schedule of "fires" — when each event (and each repeat instance) should start — and drives them in real time. |
|
timesync
Package timesync computes the clock offset and round-trip delay between two hosts from the four-timestamp NTP exchange (DESIGN.md §10, ADR-0010).
|
Package timesync computes the clock offset and round-trip delay between two hosts from the four-timestamp NTP exchange (DESIGN.md §10, ADR-0010). |
|
units
Package units parses the scenario value grammar — rates, sizes, durations, and "lo..hi" ranges of each (docs/scenario-schema.md).
|
Package units parses the scenario value grammar — rates, sizes, durations, and "lo..hi" ranges of each (docs/scenario-schema.md). |
Click to show internal directories.
Click to hide internal directories.