@mark1russell7/prober 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Russell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @mark1russell7/prober
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An eBPF prober for TCP. It records what the kernel did to each socket, and eBPF stamps each record on CLOCK_MONOTONIC, the clock that all containers on a VM share.
+
+The package has three parts:
+
+- **`bpf/prober.bpf.c`**, in C: a libbpf CO-RE program. The image of [`@mark1russell7/harness`](https://www.npmjs.com/package/@mark1russell7/harness) compiles it against the BTF of the kernel that it operates on.
+- **`native/`**, in Rust, on libbpf-rs: the record decoder and the `prober` collector.
+- **`src/`**, in TypeScript: the record contract for the readers of the lines of the collector, `KernelRecord` and `RECORD_KINDS`.
+
+## The records
+
+The kernel program records these events:
+
+- Each TCP state change, and the owner of the socket at connect and at accept.
+- Retransmissions, resets, error reports and the destruction of a socket.
+- TIME_WAIT sockets and request sockets.
+- Each keepalive probe or zero-window probe that `tcp_write_wakeup` sends.
+- Each segment that an established socket receives (`tcp_probe`).
+- The state of the retransmit timer at each retransmission.
+- Each time that the timer wheel fires the keepalive timer or the retransmit timer of a socket (`timer`).
+
+The state of the retransmit timer tells the tail loss probe from the retransmissions of the RTO timer. Only the RTO timer counts toward `tcp_retries2`.
+
+A `timer` record has three more fields:
+
+- **`behind`** is the number of jiffies between the slot of the timer on the wheel and the time that the CPU fired it. The wheel fires a slot in its tick. Thus a timer behind its slot shows a delay of its CPU, for example a vCPU that the host stopped.
+- **`late`** is the number of jiffies after the expiry that the owner of the timer set. It is the rounding of the wheel.
+- **`owned`** tells that the owner of the socket held the socket when the timer fired. A keepalive timer then sends nothing, and it tries again HZ/20 later.
+
+To find the slot, `timer_expire_entry` keeps, for each CPU, the timer that the wheel fires and its slot. The function of the timer then finds itself there.
+
+Each amount in a record is a quantity in a canonical unit of [`@mark1russell7/quantity`](https://www.npmjs.com/package/@mark1russell7/quantity). An RTO or the delay of a timer is in `jiffy`, a round trip is in `us`, and a segment is in `B`.
+
+## The collector
+
+The Rust crate has two parts:
+
+- The library has the record decoder, which reads the C struct field by field with no `unsafe`. It also has the clock, the quantities and the names of the errno values, which the tools of the harness share.
+- The `collector` feature adds the `prober` binary. It loads the kernel program and watches the network namespaces that it gets by inode. It prints each record as one JSON line.
+
+Each second, the collector also prints the clock track and the number of records that the ring buffer dropped.
+
+## The contract, written three times
+
+The C enum that the kernel side stamps, the names of the Rust decoder and `RECORD_KINDS` must agree in sequence. Otherwise, a record reads as the wrong kind. `src/index.test.ts` reads the other two and compares them.
+
+The line of a record is fixed to the byte:
+
+- Its keys are in byte sequence, as serde_json writes each object that it holds.
+- An amount is `{"unit":…,"value":N.0}`.
+- Strings have the escapes of serde_json.
+- A task name that is not UTF-8 decodes as `String::from_utf8_lossy` of Rust decodes it.
+
+## Three collectors
+
+Three collectors load the same `prober.bpf.o` and print the same lines:
+
+- `native/`, Rust on libbpf-rs: the collector that the harness uses
+- `go/`, Go on cilium/ebpf v0.22: pure Go, with no cgo, in one static binary
+- `c/prober.c`, C on libbpf 1.6
+
+The Go and C collectors are in the repository for the comparison. They are not in the npm package. A decision to keep them or to remove them is open.
+
+Each collector has a `--decode FILE` mode, which reads raw records from a file and not from the kernel. This mode holds the three to one contract:
+
+- `fixtures/records.bin` has 46 raw records, and one record that is cut short. The records have each kind, each optional field, the extremes of each integer, the escapes of JSON and each way to break UTF-8. `src/fixture.ts` makes the file, and its test keeps the committed bytes the same as the output.
+- The Rust test compares the writer of the crate with the output of serde, record by record. It also compares the names with the lossy decoder of the standard library.
+- The comparison image (`image/Dockerfile`) decodes the fixture with the three collectors. The build stops unless each line is the same, byte for byte.
+
+Then `image/compare.sh` starts the three collectors live in one privileged container. A loopback storm of short connections (`c/storm.c`) gives each record that the life of a connection has.
+
+## The results
+
+These results are from 2026-10-11, on kernel 6.6.87.2 under Docker Desktop, with 16 CPUs. Each collector writes its line by hand into one buffer, and it writes the buffer one time. The first versions did not do this, and that difference was larger than the difference between the languages.
+
+|                                                   | Rust                        | Go                          | C                           |
+| ------------------------------------------------- | --------------------------- | --------------------------- | --------------------------- |
+| The decoder and the writer alone, on raw records   | 3.34 M a second             | 2.49 M a second             | 3.46 M a second             |
+| The three on one storm: the same records          | 39,839                      | 39,839, none different      | 39,839, none different      |
+| Alone, 20,000 connections, 3 rounds: records lost | none (0.65–0.78 M a second) | none (0.70–0.75 M a second) | none (0.61–0.67 M a second) |
+| CPU for those ≈ 407,000 records                   | 240–330 ms                  | 400–440 ms                  | 260–290 ms                  |
+| Peak memory (with the 16 MiB ring)                | 34 MB                       | 85–91 MB                    | 33 MB                       |
+| The start: load, verify, attach                   | 1.0–1.1 s                   | 1.0–1.2 s                   | 1.2 s                       |
+| Binary                                            | 0.8 MB (libbpf inside)      | 3.6 MB (static)             | 49 KB (and libbpf.so)       |
+| A clean release build                             | 20 s                        | 8 s                         | 1 s                         |
+
+- Rust and C have the same cost when they have the same loop. Go uses approximately 50 % more CPU and two times the memory for its runtime. It gives a static binary with no C toolchain.
+- The start is the verifier and the attach of the kernel, which are the same in each language.
+- The first versions show the cost of the loop. With serde, which made a map for each record, Rust dropped a third of the records of a heavy storm. Go made and sorted an object for each record, and it dropped more than half. C used `fprintf` one time for each field. It kept up with a slower storm only, and it dropped up to a quarter of a faster storm.
+
+To start the comparison again, use this command:
+
+```sh
+LOOM_PROBER_COMPARE=1 pnpm --filter @mark1russell7/prober exec vitest run src/compare.test.ts
+```
+
+The test holds what does not change with the load of the host. These are the bytes, and the same records with none lost under a light storm. It prints the numbers of the heavy storm.
+
+## Installation
+
+```sh
+pnpm add @mark1russell7/prober zod
+```
+
+The package uses `@mark1russell7/quantity`, and `quantity` uses `zod` as a peer dependency. Thus the application installs `zod`. The npm package has the kernel program, the Rust crate and the fixture, thus an image can compile them from `node_modules`.
+
+## Tests
+
+- `pnpm --filter @mark1russell7/prober test` compares the contract in C, Rust and TypeScript, and it holds the fixture to its generator.
+- `cargo test --features collector` in the build of the image of the harness tests the record decoder. It also tests the names of tail loss probes, RTO retransmissions and fast retransmissions.
+- The cells of [`@mark1russell7/harness`](https://www.npmjs.com/package/@mark1russell7/harness) measure each interval from these records. The `TCP_INFO` samples of the client agree with them within one sample, and a run with records that the collector dropped is void.

package/bpf/prober.bpf.c

@@ -0,0 +1,372 @@
+// SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
+/* prober.bpf.c - the prober's kernel source: a libbpf CO-RE program that records
+ * what the kernel does to every TCP socket in the network namespaces it watches, each record
+ * stamped on CLOCK_MONOTONIC, which every container on the VM shares.
+ *
+ * Its core was built and verified first: the state changes, the owner at
+ * connect and accept, retransmissions, resets, error reports, destruction, TIME_WAIT and request
+ * socks, with the socket cookie, the namespace and the cgroup. The harness adds four things:
+ * - each probe tcp_write_wakeup sends, as keepalive or zero-window;
+ * - every segment received on an established socket, so a frozen peer's ACKs show;
+ * - the connection's retransmit-timer state on each retransmission, so the tail loss probe (its
+ *   pending event is the loss probe) parts from the RTO timer's retransmissions, which alone
+ *   count toward tcp_retries2;
+ * - each run of a socket's keepalive or retransmit timer, with how far behind its wheel slot it
+ *   ran, so a run that a stalled vCPU delayed tells itself apart from the kernel's own timing. */
+#include "vmlinux.h"
+#include <bpf/bpf_helpers.h>
+#include <bpf/bpf_tracing.h>
+#include <bpf/bpf_core_read.h>
+#include <bpf/bpf_endian.h>
+#include "prober.h"
+
+char LICENSE[] SEC("license") = "Dual BSD/GPL";
+
+struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 1 << 24); } rb SEC(".maps");
+struct { __uint(type, BPF_MAP_TYPE_HASH); __uint(max_entries, 256); __type(key, __u32); __type(value, __u8); } want SEC(".maps");
+struct { __uint(type, BPF_MAP_TYPE_HASH); __uint(max_entries, 65536); __type(key, __u32); __type(value, __s32); } cfd SEC(".maps");
+struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __uint(max_entries, 1); __type(key, __u32); __type(value, __u64); } lost SEC(".maps");
+
+/* the pid-namespace level Docker Desktop's containers sit at, as measured */
+const volatile __u32 pidns_level = 3;
+const volatile __u8 all_ns = 0;
+
+static __always_inline bool ok_ns(__u32 ns) { return all_ns || bpf_map_lookup_elem(&want, &ns); }
+
+/* Wake the reader only when 256 KiB are waiting: a wakeup per record cost about 3 us per event
+ * (as measured). The reader also drains the ring every 20 ms. */
+static __always_inline long wake(void)
+{
+	return bpf_ringbuf_query(&rb, BPF_RB_AVAIL_DATA) >= (1 << 18) ? BPF_RB_FORCE_WAKEUP : BPF_RB_NO_WAKEUP;
+}
+
+static __always_inline __s32 docker_pid(void)
+{
+	struct task_struct *t = (struct task_struct *)bpf_get_current_task();
+	struct pid *p = BPF_CORE_READ(t, group_leader, thread_pid);
+	unsigned int lvl = BPF_CORE_READ(p, level);
+	struct upid up = {};
+	if (lvl < pidns_level)
+		return -1;
+	bpf_probe_read_kernel(&up, sizeof(up), &p->numbers[pidns_level]);
+	return up.nr;
+}
+
+static __always_inline struct ev *reserve(void)
+{
+	struct ev *e = bpf_ringbuf_reserve(&rb, sizeof(*e), 0);
+	if (!e) {
+		__u32 k = 0; __u64 *n = bpf_map_lookup_elem(&lost, &k);
+		if (n) (*n)++;
+		return 0;
+	}
+	__builtin_memset(e, 0, sizeof(*e));
+	e->mono = bpf_ktime_get_ns();
+	e->pid = docker_pid();
+	bpf_get_current_comm(e->comm, sizeof(e->comm));
+	return e;
+}
+
+static __always_inline void fill_sk(struct ev *e, const struct sock *sk)
+{
+	e->netns = BPF_CORE_READ(sk, __sk_common.skc_net.net, ns.inum);
+	e->nscookie = BPF_CORE_READ(sk, __sk_common.skc_net.net, net_cookie);
+	e->cgid = BPF_CORE_READ(sk, sk_cgrp_data.cgroup, kn, id);
+	e->saddr = BPF_CORE_READ(sk, __sk_common.skc_rcv_saddr);
+	e->daddr = BPF_CORE_READ(sk, __sk_common.skc_daddr);
+	e->sport = BPF_CORE_READ(sk, __sk_common.skc_num);
+	e->dport = bpf_ntohs(BPF_CORE_READ(sk, __sk_common.skc_dport));
+	e->state = BPF_CORE_READ(sk, __sk_common.skc_state);
+	e->err = BPF_CORE_READ(sk, sk_err);
+}
+
+/* the retransmit timer's state and the sequence space, as the kernel holds them now */
+static __always_inline void fill_tcp(struct ev *e, const struct sock *sk)
+{
+	const struct inet_connection_sock *icsk = (const struct inet_connection_sock *)sk;
+	const struct tcp_sock *tp = (const struct tcp_sock *)sk;
+	e->has_tcp = 1;
+	e->tcp.retransmits = BPF_CORE_READ(icsk, icsk_retransmits);
+	e->tcp.pending = BPF_CORE_READ(icsk, icsk_pending);
+	e->tcp.backoff = BPF_CORE_READ(icsk, icsk_backoff);
+	e->tcp.probes_out = BPF_CORE_READ(icsk, icsk_probes_out);
+	e->tcp.rto = BPF_CORE_READ(icsk, icsk_rto);
+	e->tcp.srtt_us = BPF_CORE_READ(tp, srtt_us) >> 3;
+	e->tcp.snd_una = BPF_CORE_READ(tp, snd_una);
+	e->tcp.snd_nxt = BPF_CORE_READ(tp, snd_nxt);
+	e->tcp.rcv_nxt = BPF_CORE_READ(tp, rcv_nxt);
+}
+
+SEC("tp_btf/inet_sock_set_state")
+int BPF_PROG(on_state, const struct sock *sk, const int oldstate, const int newstate)
+{
+	if (sk->sk_protocol != IPPROTO_TCP || !ok_ns(sk->__sk_common.skc_net.net->ns.inum))
+		return 0;
+	struct ev *e = reserve();
+	if (!e) return 0;
+	e->kind = EV_STATE; e->tai = bpf_ktime_get_tai_ns();
+	e->cookie = bpf_get_socket_cookie((void *)sk);
+	e->skaddr = (__u64)sk;
+	fill_sk(e, sk);
+	e->oldst = oldstate; e->newst = newstate;
+	if (oldstate == 7 && newstate == 2) {             /* connect(): the owner and its fd */
+		__u32 tid = (__u32)bpf_get_current_pid_tgid();
+		__s32 *fd = bpf_map_lookup_elem(&cfd, &tid);
+		e->fd = fd ? *fd : -1; e->owner = 1;
+	}
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+SEC("tracepoint/syscalls/sys_enter_connect")
+int on_connect_enter(struct trace_event_raw_sys_enter *ctx)
+{
+	__u32 tid = (__u32)bpf_get_current_pid_tgid(); __s32 fd = (__s32)ctx->args[0];
+	bpf_map_update_elem(&cfd, &tid, &fd, BPF_ANY);
+	return 0;
+}
+
+SEC("tracepoint/syscalls/sys_exit_connect")
+int on_connect_exit(struct trace_event_raw_sys_exit *ctx)
+{
+	__u32 tid = (__u32)bpf_get_current_pid_tgid();
+	bpf_map_delete_elem(&cfd, &tid);
+	return 0;
+}
+
+static __always_inline int accept_exit(long ret)
+{
+	if (ret < 0) return 0;
+	struct task_struct *t = (struct task_struct *)bpf_get_current_task();
+	struct file **fdt = BPF_CORE_READ(t, files, fdt, fd);
+	struct file *f = 0;
+	bpf_probe_read_kernel(&f, sizeof(f), &fdt[ret]);
+	struct socket *so = BPF_CORE_READ(f, private_data);
+	struct sock *sk = BPF_CORE_READ(so, sk);
+	__u32 ns = BPF_CORE_READ(sk, __sk_common.skc_net.net, ns.inum);
+	if (!ok_ns(ns) || BPF_CORE_READ(sk, sk_protocol) != IPPROTO_TCP) return 0;
+	struct ev *e = reserve();
+	if (!e) return 0;
+	e->kind = EV_ACCEPT;
+	e->cookie = BPF_CORE_READ(sk, __sk_common.skc_cookie.counter);
+	fill_sk(e, sk);
+	e->fd = (__s32)ret; e->owner = 1;
+	e->ino = BPF_CORE_READ(f, f_inode, i_ino);
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+SEC("tracepoint/syscalls/sys_exit_accept4")
+int on_accept4_exit(struct trace_event_raw_sys_exit *ctx) { return accept_exit(ctx->ret); }
+SEC("tracepoint/syscalls/sys_exit_accept")
+int on_accept_exit(struct trace_event_raw_sys_exit *ctx) { return accept_exit(ctx->ret); }
+
+static __always_inline struct ev *sk_record(const struct sock *sk, __u32 kind, __u32 extra)
+{
+	if (!ok_ns(BPF_CORE_READ(sk, __sk_common.skc_net.net, ns.inum)))
+		return 0;
+	struct ev *e = reserve();
+	if (!e) return 0;
+	e->kind = kind;
+	e->cookie = bpf_get_socket_cookie((void *)sk);
+	fill_sk(e, sk);
+	e->extra = extra;
+	return e;
+}
+
+static __always_inline int sk_event(const struct sock *sk, __u32 kind, __u32 extra)
+{
+	struct ev *e = sk_record(sk, kind, extra);
+	if (e) bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+SEC("tp_btf/tcp_retransmit_skb")
+int BPF_PROG(on_retrans, const struct sock *sk, const struct sk_buff *skb)
+{
+	struct ev *e = sk_record(sk, EV_RETRANS, 0);
+	if (!e) return 0;
+	fill_tcp(e, sk);
+	e->has_seg = 1;
+	bpf_probe_read_kernel(&e->seg.seq, sizeof(e->seg.seq), skb->cb);    /* TCP_SKB_CB(skb)->seq */
+	e->seg.len = BPF_CORE_READ(skb, len);
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+/* keepalive's probes and the zero-window ones both go out through tcp_write_wakeup. The SNMP
+ * counters are an anonymous enum, which CO-RE cannot relocate by name; the image's build takes
+ * vmlinux.h from the kernel it runs on, so these constants are that kernel's own. */
+SEC("fentry/tcp_write_wakeup")
+int BPF_PROG(on_probe, struct sock *sk, int mib)
+{
+	__u32 what = PROBE_OTHER;
+	if (mib == LINUX_MIB_TCPKEEPALIVE) what = PROBE_KEEPALIVE;
+	else if (mib == LINUX_MIB_TCPWINPROBE) what = PROBE_WINDOW;
+	struct ev *e = sk_record(sk, EV_PROBE, what);
+	if (!e) return 0;
+	fill_tcp(e, sk);
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+/* The timer each CPU's wheel is running now, and the wheel slot it is running it from.
+ * call_timer_fn traces timer_expire_entry and then calls the timer's own function, on the same
+ * CPU, so a socket's timer function finds its own wheel slot here. */
+struct expiring { __u64 timer, baseclk, now; };
+struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __uint(max_entries, 1); __type(key, __u32); __type(value, struct expiring); } expiring SEC(".maps");
+
+SEC("tp_btf/timer_expire_entry")
+int BPF_PROG(on_timer_expire, struct timer_list *timer, unsigned long baseclk)
+{
+	__u32 k = 0;
+	struct expiring *x = bpf_map_lookup_elem(&expiring, &k);
+	if (x) { x->timer = (__u64)timer; x->baseclk = baseclk; x->now = bpf_jiffies64(); }
+	return 0;
+}
+
+/* A socket's own timer, run from the wheel. `behind` is how many jiffies after its slot the CPU
+ * ran it: the wheel runs a slot in the tick it falls due, so any lag is the CPU's or the VM's, a
+ * vCPU the host descheduled, which no timer's rounding explains. `late` is how many after the
+ * expiry its owner asked for, the rounding included. Whether the socket's owner held it says
+ * whether the keepalive timer will put itself off by HZ/20. The socket is the timer's container,
+ * read through CO-RE like any probe read, its cookie as accept's is. */
+static __always_inline int timer_fired(__u64 skaddr, const struct timer_list *t, __u32 what)
+{
+	__u32 k = 0;
+	struct expiring *x = bpf_map_lookup_elem(&expiring, &k);
+	if (!x || x->timer != (__u64)t) return 0;
+	const struct sock *sk = (const struct sock *)skaddr;
+	if (!ok_ns(BPF_CORE_READ(sk, __sk_common.skc_net.net, ns.inum))) return 0;
+	struct ev *e = reserve();
+	if (!e) return 0;
+	e->kind = EV_TIMER;
+	e->cookie = BPF_CORE_READ(sk, __sk_common.skc_cookie.counter);
+	fill_sk(e, sk);
+	fill_tcp(e, sk);
+	/* a socket its owner holds as the timer runs: keepalive tries again HZ/20 later */
+	e->extra = what | (BPF_CORE_READ(sk, sk_lock.owned) ? TIMER_OWNED : 0);
+	__u64 expires = BPF_CORE_READ(t, expires);
+	e->behind = (__u32)(x->now - x->baseclk);
+	e->late = x->now > expires ? (__u32)(x->now - expires) : 0;
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+SEC("fentry/tcp_keepalive_timer")
+int BPF_PROG(on_keepalive_timer, struct timer_list *t)
+{
+	return timer_fired((__u64)t - bpf_core_field_offset(struct sock, sk_timer), t, TIMER_KEEPALIVE);
+}
+
+/* the retransmit timer: the RTO's, the tail loss probe's and the zero-window probe's */
+SEC("fentry/tcp_write_timer")
+int BPF_PROG(on_write_timer, struct timer_list *t)
+{
+	return timer_fired((__u64)t - bpf_core_field_offset(struct inet_connection_sock, icsk_retransmit_timer),
+			   t, TIMER_RETRANSMIT);
+}
+
+/* every segment that reaches an established socket: tcp_rcv_established's first act */
+SEC("tp_btf/tcp_probe")
+int BPF_PROG(on_rx, struct sock *sk, struct sk_buff *skb)
+{
+	struct ev *e = sk_record(sk, EV_RX, 0);
+	if (!e) return 0;
+	fill_tcp(e, sk);
+	struct tcphdr th = {};
+	bpf_probe_read_kernel(&th, sizeof(th), BPF_CORE_READ(skb, data));
+	__u32 len = BPF_CORE_READ(skb, len);
+	__u32 head = (__u32)th.doff * 4;
+	e->has_seg = 1;
+	e->seg.seq = bpf_ntohl(th.seq);
+	e->seg.ack = bpf_ntohl(th.ack_seq);
+	e->seg.len = len > head ? len - head : 0;
+	e->seg.flags = ((__u32)th.fin) | ((__u32)th.syn << 1) | ((__u32)th.rst << 2) | ((__u32)th.psh << 3) |
+		       ((__u32)th.ack << 4);
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+SEC("tp_btf/tcp_send_reset")
+int BPF_PROG(on_rst_tx, const struct sock *sk, const struct sk_buff *skb) { return sk_event(sk, EV_RST_TX, skb == 0); }
+
+SEC("tp_btf/tcp_receive_reset")
+int BPF_PROG(on_rst_rx, struct sock *sk) { return sk_event(sk, EV_RST_RX, 0); }
+
+/* tcp_write_err is inlined on the measured kernel, so the error report stands for it */
+SEC("tp_btf/inet_sk_error_report")
+int BPF_PROG(on_error, const struct sock *sk)
+{
+	if (sk->sk_protocol != IPPROTO_TCP) return 0;
+	struct ev *e = sk_record(sk, EV_ERROR, BPF_CORE_READ((struct inet_connection_sock *)sk, icsk_pending));
+	if (!e) return 0;
+	fill_tcp(e, sk);
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+SEC("tp_btf/tcp_destroy_sock")
+int BPF_PROG(on_destroy, struct sock *sk) { return sk_event(sk, EV_DESTROY, 0); }
+
+SEC("fentry/tcp_time_wait")
+int BPF_PROG(on_tw_enter, struct sock *sk, int state, int timeo) { return sk_event(sk, EV_TW_ENTER, state); }
+
+SEC("fentry/inet_csk_reqsk_queue_hash_add")
+int BPF_PROG(on_req_new, struct sock *sk, struct request_sock *req, unsigned long timeout)
+{
+	if (!ok_ns(BPF_CORE_READ(sk, __sk_common.skc_net.net, ns.inum)))
+		return 0;
+	struct ev *e = reserve();
+	if (!e) return 0;
+	e->kind = EV_REQ_NEW;
+	e->cookie = bpf_get_socket_cookie((void *)req);       /* the child inherits this cookie */
+	e->extra = (__u32)bpf_get_socket_cookie((void *)sk);   /* the listener (low 32 bits) */
+	e->netns = BPF_CORE_READ(sk, __sk_common.skc_net.net, ns.inum);
+	e->saddr = BPF_CORE_READ(req, __req_common.skc_rcv_saddr);
+	e->daddr = BPF_CORE_READ(req, __req_common.skc_daddr);
+	e->sport = BPF_CORE_READ(req, __req_common.skc_num);
+	e->dport = bpf_ntohs(BPF_CORE_READ(req, __req_common.skc_dport));
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+SEC("fentry/inet_twsk_kill")
+int BPF_PROG(on_tw_kill, struct inet_timewait_sock *tw)
+{
+	__u32 ns = BPF_CORE_READ(tw, __tw_common.skc_net.net, ns.inum);
+	if (!ok_ns(ns)) return 0;
+	struct ev *e = reserve();
+	if (!e) return 0;
+	e->kind = EV_TW_KILL; e->netns = ns;
+	e->cookie = BPF_CORE_READ(tw, __tw_common.skc_cookie.counter);
+	e->saddr = BPF_CORE_READ(tw, __tw_common.skc_rcv_saddr);
+	e->daddr = BPF_CORE_READ(tw, __tw_common.skc_daddr);
+	e->sport = BPF_CORE_READ(tw, __tw_common.skc_num);
+	e->dport = bpf_ntohs(BPF_CORE_READ(tw, __tw_common.skc_dport));
+	e->extra = BPF_CORE_READ(tw, tw_substate);
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}
+
+SEC("fentry/tcp_v4_send_reset")
+int BPF_PROG(on_rst_v4, const struct sock *sk, struct sk_buff *skb)
+{
+	unsigned char *head = BPF_CORE_READ(skb, head);
+	__u16 nh = BPF_CORE_READ(skb, network_header), th = BPF_CORE_READ(skb, transport_header);
+	/* the socket's netns when there is one (skb->dev is NULL for an RST answered by a listener) */
+	__u32 ns = sk ? BPF_CORE_READ(sk, __sk_common.skc_net.net, ns.inum) : BPF_CORE_READ(skb, dev, nd_net.net, ns.inum);
+	if (!ok_ns(ns)) return 0;
+	struct iphdr ip = {}; struct tcphdr tcp = {};
+	bpf_probe_read_kernel(&ip, sizeof(ip), head + nh);
+	bpf_probe_read_kernel(&tcp, sizeof(tcp), head + th);
+	struct ev *e = reserve();
+	if (!e) return 0;
+	e->kind = EV_RST_V4; e->netns = ns;
+	e->state = sk ? BPF_CORE_READ(sk, __sk_common.skc_state) : 0;
+	e->cookie = sk ? BPF_CORE_READ(sk, __sk_common.skc_cookie.counter) : 0;
+	e->saddr = ip.daddr; e->daddr = ip.saddr;          /* the RST goes back to the sender */
+	e->sport = bpf_ntohs(tcp.dest); e->dport = bpf_ntohs(tcp.source);
+	e->extra = ((__u32)tcp.syn) | ((__u32)tcp.ack << 1) | ((__u32)tcp.fin << 2) | ((__u32)tcp.rst << 3);
+	bpf_ringbuf_submit(e, wake());
+	return 0;
+}

package/bpf/prober.h

@@ -0,0 +1,59 @@
+/* prober.h - the record the kernel side writes and user space prints */
+#ifndef HARNESS_PROBER_H
+#define HARNESS_PROBER_H
+
+enum {
+	EV_STATE = 1, /* a TCP state change */
+	EV_ACCEPT,    /* a connection accepted, with its owner's fd */
+	EV_RETRANS,   /* a segment retransmitted: the tail loss probe, the RTO timer's, or a fast one */
+	EV_RST_TX,    /* a reset sent from a socket (no skb: an active reset) */
+	EV_RST_RX,    /* a reset received */
+	EV_ERROR,     /* an error reported to the socket's owner: sk_err */
+	EV_DESTROY,   /* the socket destroyed */
+	EV_TW_ENTER,  /* into TIME_WAIT */
+	EV_TW_KILL,   /* a TIME_WAIT socket killed */
+	EV_REQ_NEW,   /* a request sock born (a SYN accepted onto a listener) */
+	EV_RST_V4,    /* a reset sent by tcp_v4_send_reset, with or without a socket */
+	EV_PROBE,     /* a probe sent by tcp_write_wakeup: keepalive or zero window */
+	EV_RX,        /* a segment received on an established socket (tcp_probe) */
+	EV_TIMER,     /* a socket's own timer run from the wheel: its keepalive, or its retransmit timer */
+};
+
+/* what EV_PROBE's extra says the probe was */
+enum { PROBE_OTHER = 0, PROBE_KEEPALIVE = 1, PROBE_WINDOW = 2 };
+
+/* which timer EV_TIMER's extra says ran, in its low byte, and TIMER_OWNED when the socket's owner
+ * held the socket as it ran: the keepalive timer then tries again HZ/20 later, sending nothing */
+enum { TIMER_KEEPALIVE = 1, TIMER_RETRANSMIT = 2, TIMER_OWNED = 0x100 };
+
+/* the connection's TCP state when the record was taken */
+struct tcp_now {
+	__u32 retransmits; /* icsk_retransmits: the RTO timer's retransmissions this episode */
+	__u32 pending;     /* icsk_pending: which retransmit-timer event is armed */
+	__u32 backoff;     /* icsk_backoff */
+	__u32 probes_out;  /* icsk_probes_out */
+	__u32 rto;         /* icsk_rto, in jiffies */
+	__u32 srtt_us;     /* the smoothed RTT, in microseconds */
+	__u32 snd_una, snd_nxt, rcv_nxt;
+};
+
+/* the segment a record is about: retransmitted, or received */
+struct seg {
+	__u32 seq, ack, len, flags;
+};
+
+struct ev {
+	__u64 mono, tai, cookie, nscookie, cgid, skaddr, ino;
+	__u32 kind, netns, saddr, daddr, extra;
+	__s32 pid, fd, oldst, newst, state, err, owner;
+	__u16 sport, dport;
+	__u32 has_tcp, has_seg;
+	struct tcp_now tcp;
+	struct seg seg;
+	/* EV_TIMER: how many jiffies behind its wheel slot the CPU ran the timer, which no timer's
+	 * rounding explains (a stalled vCPU does), and how many after its own expiry */
+	__u32 behind, late;
+	char comm[16];
+};
+
+#endif

package/build/index.d.ts

@@ -0,0 +1,52 @@
+import { Quantity } from "@mark1russell7/quantity";
+//#region src/index.d.ts
+/** These are the kinds of record, in the sequence of the enum in `bpf/prober.h` and of `KINDS` in the Rust decoder. */
+export declare const RECORD_KINDS: readonly ["state", "accept", "retrans", "rst_tx", "rst_rx", "error", "destroy", "tw_enter", "tw_kill", "req_new", "rst_v4", "probe", "rx", "timer"];
+/** A record kind is one kind of record that the kernel side writes. */
+export type RecordKind = (typeof RECORD_KINDS)[number];
+/** These are the lines of the collector itself: its start, its clock track, its failure, and a record that it cannot read. */
+export type CollectorLine = "begin" | "clock" | "fail" | "undecodable";
+/**
+ * A kernel record is one record of the prober: what the kernel did to a socket. The eBPF side
+ * stamps it on CLOCK_MONOTONIC, the clock that all containers on the VM share (`native/src/record.rs`).
+ */
+export interface KernelRecord {
+  readonly ev: RecordKind | CollectorLine | string;
+  readonly mono: number;
+  readonly cookie?: number;
+  readonly netns?: number;
+  readonly src?: string;
+  readonly dst?: string;
+  readonly state?: number;
+  /** This number is the `sk_err` of the socket at the time of the record: the errno of an error report. */
+  readonly err?: number;
+  /** This value is the cause of a retransmission: the tail loss probe, the RTO timer, or a fast retransmission from ACK processing. */
+  readonly why?: "tlp" | "rto" | "fast";
+  /** This value is the kind of a probe that `tcp_write_wakeup` sent, or of a socket timer that fired. */
+  readonly what?: "keepalive" | "window" | "retransmit" | "other";
+  /**
+   * For a socket timer that fired, `behind` is the delay of the CPU after the slot of the timer
+   * wheel. Only a stalled CPU causes that delay. `late` is the time after the expiry of the timer,
+   * with the rounding of the wheel.
+   */
+  readonly behind?: Quantity;
+  readonly late?: Quantity;
+  /** This flag tells that a socket timer fired while the owner of the socket held it. Keepalive then tries again HZ/20 later. */
+  readonly owned?: boolean;
+  readonly tcp?: {
+    readonly retransmits: number;
+    readonly pending: number;
+    readonly backoff: number;
+    readonly probes_out: number;
+    readonly rto: Quantity;
+    readonly srtt: Quantity;
+  };
+  readonly seg?: {
+    readonly seq: number;
+    readonly ack?: number;
+    readonly len: Quantity;
+  };
+  readonly [field: string]: unknown;
+}
+//#endregion
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -0,0 +1,22 @@
+//#region src/index.ts
+/** These are the kinds of record, in the sequence of the enum in `bpf/prober.h` and of `KINDS` in the Rust decoder. */
+const RECORD_KINDS = [
+	"state",
+	"accept",
+	"retrans",
+	"rst_tx",
+	"rst_rx",
+	"error",
+	"destroy",
+	"tw_enter",
+	"tw_kill",
+	"req_new",
+	"rst_v4",
+	"probe",
+	"rx",
+	"timer"
+];
+//#endregion
+export { RECORD_KINDS };
+
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// @mark1russell7/prober: the instrument that records what each layer did to a connection. Its\n// first source is the kernel: bpf/prober.bpf.c, a libbpf CO-RE program, and the collector in\n// native/ that prints each record as a JSON line. This module is the record contract for the\n// readers of those lines.\n\nimport type { Quantity } from \"@mark1russell7/quantity\";\n\n/** These are the kinds of record, in the sequence of the enum in `bpf/prober.h` and of `KINDS` in the Rust decoder. */\nexport const RECORD_KINDS = [\n  \"state\",\n  \"accept\",\n  \"retrans\",\n  \"rst_tx\",\n  \"rst_rx\",\n  \"error\",\n  \"destroy\",\n  \"tw_enter\",\n  \"tw_kill\",\n  \"req_new\",\n  \"rst_v4\",\n  \"probe\",\n  \"rx\",\n  \"timer\",\n] as const;\n\n/** A record kind is one kind of record that the kernel side writes. */\nexport type RecordKind = (typeof RECORD_KINDS)[number];\n\n/** These are the lines of the collector itself: its start, its clock track, its failure, and a record that it cannot read. */\nexport type CollectorLine = \"begin\" | \"clock\" | \"fail\" | \"undecodable\";\n\n/**\n * A kernel record is one record of the prober: what the kernel did to a socket. The eBPF side\n * stamps it on CLOCK_MONOTONIC, the clock that all containers on the VM share (`native/src/record.rs`).\n */\nexport interface KernelRecord {\n  readonly ev: RecordKind | CollectorLine | string;\n  readonly mono: number;\n  readonly cookie?: number;\n  readonly netns?: number;\n  readonly src?: string;\n  readonly dst?: string;\n  readonly state?: number;\n  /** This number is the `sk_err` of the socket at the time of the record: the errno of an error report. */\n  readonly err?: number;\n  /** This value is the cause of a retransmission: the tail loss probe, the RTO timer, or a fast retransmission from ACK processing. */\n  readonly why?: \"tlp\" | \"rto\" | \"fast\";\n  /** This value is the kind of a probe that `tcp_write_wakeup` sent, or of a socket timer that fired. */\n  readonly what?: \"keepalive\" | \"window\" | \"retransmit\" | \"other\";\n  /**\n   * For a socket timer that fired, `behind` is the delay of the CPU after the slot of the timer\n   * wheel. Only a stalled CPU causes that delay. `late` is the time after the expiry of the timer,\n   * with the rounding of the wheel.\n   */\n  readonly behind?: Quantity;\n  readonly late?: Quantity;\n  /** This flag tells that a socket timer fired while the owner of the socket held it. Keepalive then tries again HZ/20 later. */\n  readonly owned?: boolean;\n  readonly tcp?: {\n    readonly retransmits: number;\n    readonly pending: number;\n    readonly backoff: number;\n    readonly probes_out: number;\n    readonly rto: Quantity;\n    readonly srtt: Quantity;\n  };\n  readonly seg?: { readonly seq: number; readonly ack?: number; readonly len: Quantity };\n  readonly [field: string]: unknown;\n}\n"],"mappings":";;AAQA,MAAa,eAAe;CAC1B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF"}