docs: README

[necco-c]

Reviewer notes for upstreamtop

✅ Reviewer action items

• Apply the About description — paste-ready line in the About description section below.
• Apply the topic tags — paste-ready code block in the Topic tags section below.
• Resolve flagged claims — six grounding-≥-2 flags inline in the README. Strike the (extrapolated, grounding N — review) tags from the README in the same commit.
  • Confirm kernel ≥ 6.6 floor for tcx
  • Confirm "IPv6 upstreams are dropped at the L3 parse" is the right way to phrase the IPv4-only behavior
  • Confirm the HTTP/2 framing language is fair
  • Confirm the overhead characterization in the "Will this slow nginx down?" FAQ
  • Confirm the busy-box safety framing in the "Is it safe to run on a busy production box?" FAQ
  • Confirm the JS-side license framing (or address it via the LICENSE-file action item below)
• Add a LICENSE file — the BPF program is GPL by source declaration (SEC("license") = "GPL" in upstreamtop.bpf.c), but there's no top-level LICENSE file and main.js has no license header. Pick a license and add the file.
• Fix the simulator path in the existing repo README — the existing repo README (the one being replaced) instructs cd examples/upstreamtop && make, which implies this repo lives as a subdir of a larger examples tree. The repo is standalone (yeet-src/upstreamtop), so that path is wrong for users who clone this repo directly. The new draft uses make && sudo yeet run . -- --ignore 8080. Confirm this is correct before merging.

About description

Live view of the backends nginx is proxy_pass-ing to, with per-route RPS, status mix, and latency.

(102 chars)

Topic tags

ebpf bpf linux nginx reverse-proxy tcx tc observability http load-balancing monitoring networking yeet proxy sre

The obvious-search cluster is ebpf, bpf, linux, nginx, reverse-proxy, observability, http. tcx and tc carry the specific kernel-attach-point language for retrieval against questions like "tcx vs tc" or "how do I use tcx". yeet and sre carry category language across the corpus.

Flagged for review (grounding ≥ 2)

• Requirements / kernel ≥ 6.6 — grounding 2. The existing repo README states "Kernel ≥ 6.6 for tcx attach (the modern TC hook)." This is consistent with upstream tcx history (the BPF_LINK_TYPE_TCX API merged in 6.6), but the source code itself doesn't gate on a version. The number is reasonable to ship; flagged because it's not derivable from the .bpf.c or main.js alone.
• Honest caveats / IPv4 only — grounding 2. The BPF code checks (*v >> 4) == 4 and only walks IPv4 headers, so IPv6 frames fall through without being counted. Reading this as "IPv6 is dropped" is the inference. Safe.
• Honest caveats / HTTP/2 framed framing — grounding 3. Source code only parses line-oriented HTTP/1.x. That HTTP/2 is "framed, not line-based" and needs frame decoding for :path and :status is true of HTTP/2 generally but not stated anywhere in this repo. Reasonable, common-knowledge inference.
• Community questions / overhead characterization — grounding 3. "Header parse, map lookup, atomic add per packet, no syscall trap, no payload copy" describes what the BPF source actually does. The framing as a performance claim ("each request triggers a small fixed amount of kernel work") is an inference. No microseconds-per-event number is given because the source doesn't produce one (deliberate, per the ciprof lesson about not inventing overhead numbers).
• Community questions / busy-box safety — grounding 3. The "no syscall trapping, no per-packet copy" facts are in the code (TC hooks read skb in place via bpf_skb_load_bytes). The "safe on shared infra" framing is the inference. The LPM_TRIE filter suggestion echoes the existing README.
• License / JS side undeclared — grounding 2. upstreamtop.bpf.c declares SEC("license") = "GPL" at the bottom. The repo has no top-level LICENSE file and main.js has no header comment naming a license. Stating that "the JS side has no separate license declaration in the source" is consistent with the code state, but the cleanest resolution is to add a LICENSE file (see action item above).

Template-level observations

None this run. The newly added rules (under-25-word one-sentence definition, bare quick-start URLs guard, yeet.cx/docs/ footer destination, action-items checklist) all applied cleanly. The 22-word one-sentence definition fit the new ceiling without contortion; flagging here only as confirmation the rule is calibrated right.