Linux-first
TCP/DNS/ICMP/PMTU
JSONL + HTML report

Internet Reliability Recorder

Daemon + CLI that captures evidence-quality reliability incidents with TCP connect, DNS, ICMP (CAP_NET_RAW), PMTU ceilings, and netlink link/route changes.

Quickstart

Build, run for 60s, and render a report.

./scripts/build.sh
./build/irr run --duration 60 --out ./bundle --profile home --interval 1000
./build/irr report --in ./bundle --out ./bundle/report.html

Requires Linux, C++17 toolchain, CMake ≥ 3.15. ICMP probe requires CAP_NET_RAW.

Downloads

Release assets (v0.1.0)

Docs

Architecture

Single epoll reactor with timerfd-driven scheduling. Probes emit events via an EventBus to a JSONL sink; reports are generated offline from the bundle.

CLI Reactor (epoll) Timerfd scheduler Probes Netlink monitor EventBus JSONL Store ReportGen

Metrics + Events

  • probe.tcp.connect: connect RTT ms; error category from SO_ERROR.
  • probe.dns.result|timeout: UDP query RTT, RCODE on error, TCP fallback outcome.
  • probe.icmp.rtt|timeout: echo RTT (requires CAP_NET_RAW).
  • probe.pmtu.result: discovered MTU bytes or emsgsize when constrained.
  • sys.netlink.route_change|link_change: link/route churn markers.
  • Aggregates: p50/p95/p99 via linear interpolation; loss% = failures / total.

Limitations: ICMP gated on CAP_NET_RAW; DNS uses first resolver; PMTU probes are lightweight and may be rate-limited.

What It Measures

  • TCP connect latency/loss to configured targets.
  • DNS UDP with TCP fallback; classifies rcode/timeouts.
  • ICMP echo RTT (when CAP_NET_RAW present) with timeout events.
  • PMTU ceilings via lightweight probes.
  • Netlink link/route change markers to correlate spikes.

CLI Usage

Run

./build/irr run \
  --duration 600 \
  --out ./bundle \
  --profile home \
  --interval 1000 \
  [--no-dns] [--no-icmp] [--no-pmtu] [--no-netlink]

Report

./build/irr report --in ./bundle --out ./bundle/report.html

Doctor

./build/irr doctor

Bundles contain run.json and events.jsonl; reports are self-contained HTML.

Report

Parses JSONL, computes p50/p95/p99, loss%, per-target stats, and renders an SVG timeline for TCP connect. User-controlled strings are escaped to avoid injection when inspecting bundles.

View sample

Default Targets

  • Profile home: TCP to 1.1.1.1:443 and 8.8.8.8:443; DNS qname example.com.
  • ICMP inherits interval; PMTU targets reuse TCP hosts (UDP 33434).
  • Resolvers auto-detected from /etc/resolv.conf, fallback 1.1.1.1.

Diagnostics

  • irr doctor checks /etc/resolv.conf and CAP_NET_RAW availability.
  • Netlink monitor stamps link/route changes for correlation.
  • JSONL logging retains timestamps, target meta, and error categories.

Raspberry Pi / SBC notes

  • Build natively: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build.
  • Use lightweight desktops or headless; keep bundles on tmpfs to reduce SD wear.
  • ICMP probe: sudo setcap cap_net_raw+ep ./irr.
  • For continuous runs, use the systemd unit (packaging/systemd/irr.service) and store bundles on ext4.

Packaging

  • OpenWrt: feed/Makefile under packaging/openwrt; build IPKs with the provided recipes.
  • Systemd: sample unit in packaging/systemd/irr.service (set ExecStart to built binary path).
  • CI: format (clang-format), lint (clang-tidy), Debug/Release build + ctest.

Versioning

  • Current: 0.1.0 (tag v0.1.0).
  • CI: format check (clang-format), lint (clang-tidy), Debug/Release build + ctest.

Report Issues

Open an issue on GitHub with:

  • What you ran (CLI flags) and platform/kernel.
  • Bundle or relevant excerpts of events.jsonl (if possible).
  • Network context (ISP/router, VPNs, captive portals).

File an issue