[Installationsanleitung für manuelle Installation](https://yeet.cx/docs/manual-installation) | Nur Linux

Nichts zu konfigurieren — Signale sind ständiger Hintergrundverkehr auf jeder Kiste, also landen Zeilen sofort oben. Möchtest du selbst welche erzeugen? `kill -USR1 <pid>`, `Ctrl-C` für einen Vordergrundjob, oder starte eine verwaltete Laufzeitumgebung und beobachte, wie der GC/Scheduler seine eigenen Threads pingt (`↯ EINTR futex` scrollt vorbei).

## Steuerung

Der Feed folgt standardmäßig dem neuesten Signal; wähle eine Zeile aus oder pausiere, dann bleibt sie stehen, während Daten darunter weiterfließen.

| Taste | Aktion |
| ----- | ------ |
| `p` · `Leertaste` | Feed pausieren / fortsetzen (einfrieren zum Lesen) |
| `↑`/`↓`, `k`/`j` | pausieren und eine Zeile inspizieren — öffnet das Detailfeld |
| `/` | unscharfer Filter — durchsucht Prozess, PID, Signal, Quelle und Disposition; übereinstimmende Zeichen werden live hervorgehoben |
| `e` | filtere auf **unterbrochene Syscalls** (`↯ EINTR` / `↺ neu gestartet`) |
| `s` | öffne die **Signalauswahl** — blende ein Signal stumm oder zeige es live an |
| `Esc` | eine Ebene zurück — Filter löschen / Auswahl schließen / Selektion aufheben, dann beenden |
| `q` | beenden |

## Was du siehst

Jede Zeile ist ein generiertes Signal, das neueste oben:```
 WHEN            SENDER  SIGNAL        TARGET               NOTE
  now       bash·4402──SIGINT───▶  node·8813        kill(2)  ↯ EINTR read  caught 41µs
 1.2s    systemd·1──────SIGTERM──▶  nginx·1291       kill(2)  caught 1.2ms
 3.4s     kernel·8813──SIGSEGV──▶  chrome·8813       fault    default  ☠
 4.1s   postgres·507──SIGUSR1───▶  postgres·509 ×6  kill(2)  caught 9µs

- **handled** — `caught` (hat einen Userspace-Handler ausgeführt), `default` (→ die Standardaktion: beenden / core dump / anhalten / ignorieren) oder `ignored`.
- **syscall** — wenn dieses Signal einen blockierten Syscall unterbrochen hat: `EINTR ← read` (Userspace sah `EINTR`) oder `restarted read` (`SA_RESTART` hat es transparent wiederaufgenommen).
- **ran** — wie lange der Handler ausgeführt wurde, gemessen von der Zustellung bis zum abschließenden `rt_sigreturn(2)`. (Laufzeiten, die im C-Handler nur ein Flag setzen und die eigentliche Arbeit später erledigen – CPython, Go – zeigen hier eine winzige Zeit; das liegt an ihnen, nicht an sigwire.)
- **flags** — die `sigaction`-Flags des Handlers (`SA_RESTART`, `SA_SIGINFO`, `SA_NODEFER`, …).
- **TARGET BLOCKS** — die Signale, die der Zielprozess (seine `sigprocmask`) im Moment der Zustellung blockiert hatte, direkt aus seiner `task_struct`.

`Esc` schließt den Inspektor; `p` setzt den Live-Feed fort.

## Was als fatal zählt

Der `☠ fatal`-Zähler und das `☠`-Reihenabzeichen sind bewusst streng. Da `signal_generate` bei der *Erzeugung* feuert, kann sigwire nicht sehen, ob das Ziel einen Handler installiert hat – ein `SIGTERM` könnte abgefangen und in eine saubere Beendigung umgewandelt oder ganz ignoriert werden. Daher zählt es einen Tod nur dann, wenn er eindeutig ist:

- **`SIGKILL`** zugestellt – abfangbar, ignorierbar, immer tödlich; **oder**
- ein **Core-Dump-Signal** (`SEGV`/`BUS`/`ABRT`/`ILL`/`FPE`/`TRAP`/`SYS`/`QUIT`), das der **Kernel selbst ausgelöst hat** (ein synchroner Fehler, kein Userspace-`kill`).

Alles andere – ein `SIGTERM` von `systemd`, ein `SIGINT` von Ihrem `Strg-C`, ein `SIGPWR` einer Laufzeit an ihre eigenen Threads – wird angezeigt und gefärbt, aber nicht als Tod gezählt, weil es wahrscheinlich keiner war.

## Der Signal-Auswähler (ein Live-Kernel-Knopf)

Drei Signale sind auf jeder ausgelasteten Maschine reines Hintergrundrauschen: `SIGCHLD` (jedes Kind wird abgeholt), `SIGURG` (Gos asynchroner Vorbeugungs-Herzschlag) und `SIGWINCH` (Terminalgrößenänderungen, die an alle Vordergrundprozesse gesendet werden). Sigwire blendet diese drei **im Kernel** standardmäßig aus, damit der Feed den interessanten Verkehr zeigt – aber welche Signale Rauschen sind, bleibt Ihnen überlassen.

Drücken Sie `s`, um den **Signal-Auswähler** zu öffnen: eine modale Liste aller Signale mit ihrer Live-Schweregradfarbe und wie oft Sie jedes gesehen haben. Jedes kann zwischen `shown` (angezeigt) und `muted` (stummgeschaltet) umgeschaltet werden. Pfeiltasten zu einem (oder **seine Nummer eingeben** – `1`, `5` → springt zu 15) und `Leertaste`, und das Signal wird sofort umgeschaltet. `a` schaltet sie **alle** gleichzeitig um. Der Titelbalken zeigt die Anzahl der stummgeschalteten (`muted`) an.

Dies ist die bidirektionale Hälfte der Demo: Die Stummschaltungsmaske ist eine globale `__u64` im `.data`-Abschnitt des laufenden BPF-Programms, und das Umschalten einer Zeile patcht das entsprechende Bit über `DataSec.patch()`, während das Programm weiterläuft. Der Kernel verwirft stummgeschaltete Signale, bevor sie den Ringpuffer erreichen. Daher kostet Stummschalten nichts – und das Aufheben der Stummschaltung bringt ein Signal mitten im Stream zurück, ohne Neuladen.

## Wie es funktioniert

Der Kern besteht aus [`src/bpf/sigwire.bpf.c`](https://github.com/yeet-src/sigwire/blob/HEAD/src/bpf/sigwire.bpf.c) + [`src/bpf/deliver.bpf.c`](https://github.com/yeet-src/sigwire/blob/HEAD/src/bpf/deliver.bpf.c) (Kernel, zu einem Objekt verlinkt) und [`src/probes/sigwire.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/sigwire.js) (Userspace). Alles wird durch `(Ziel-TID, Signal)` korreliert.

### Die BPF-Seite

Zwei Quelldateien werden zu einem ladbaren Objekt, `bin/probe.bpf.o`, mit vier Tracepoint-Programmen verlinkt:

| Programm | Angehängt an | Was es erfasst |
|---|---|---|
| `on_signal_generate` | `signal:signal_generate` | den Sender (`current`) + Ziel (`comm`/`pid`), das Signal, `si_code`, `group`-Flag, `result` – im Kernel verworfen, wenn das Bit des Signals in der Live-`mute_mask` gesetzt ist |
| `on_signal_deliver` | `signal:signal_deliver` | die Disposition des Ziels (`sa_handler`), `sa_flags` und – aus `task_struct` – seine `blocked`-Sigset; stempelt die Zustellung für die Handler-Zeitmessung |
| (rt_sigreturn) | `syscalls:sys_enter_rt_sigreturn` | Differenz zur gestempelten Zustellung für die Laufzeit des Handlers |
| (sys_exit) | `raw_syscalls:sys_exit` | zeichnet den seltenen Rückgabewert `-ERESTART*` auf, damit die nächste `signal_deliver` ihn in `EINTR`/`restarted` + die unterbrochene Syscall-Nummer auflöst |

Maps verbinden Kernel mit Userspace:

- `events` — `RINGBUF`, ein `signal_event` pro Erzeugung.
- `dispatch` — `RINGBUF`, ein `dispatch_event` pro Zustellung / Handler-Rückkehr.
- `mute_mask` — eine globale `__u64` im `.data`-Abschnitt; der Auswähler patcht einzelne Bits, um Signale im Kernel zu verwerfen.
- `handler_start` / `restart_pending` — `HASH`, keyed by TID, pro-Thread-Kratzer, der eine Zustellung mit ihrem `rt_sigreturn` paart und den `-ERESTART*`-Austritt eines Syscalls mit der darauf folgenden Zustellung.

### Die JS-Seite

| Datei | Verantwortung |
|---|---|
| [`src/probes/probe.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/probe.js) | lädt `bin/probe.bpf.o` einmal, bindet die Maps, startet die Programme (sie heften sich automatisch an) |
| [`src/probes/sigwire.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/sigwire.js) | das einzige BPF-bewusste Datenmodul: faltet beide Ringpuffer in einen rollierenden Feed mit Zählungen, korreliert Zustellung mit Erzeugung, besitzt den Stummschaltungs-Knopf – stellt die Signale `feed`, `visible`, `muteMask` bereit |
| [`src/main.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/main.jsx) | Kompositionswurzel: Eingabe, Auswahl, responsives Layout (Seitenleiste versteckt sich auf schmalen Terminals), `mount` |
| [`src/components/feed.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/feed.jsx) | die Schaltzentrale: `Sender ──SIG──▶ Ziel`, Disposition/Latenz, Abzeichen, Tönung, Zusammenfassung |
| [`src/components/tally.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/tally.jsx) | die Seitenleiste – Top-Signale, Aufschlüsselung nach Quelle, Zustellungszählung |
| [`src/components/detail.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/detail.jsx) | der Inspektor – Disposition pro Signal, Handler, Flags, blockierte Maske |
| [`src/components/picker.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/picker.jsx) | der Signal-Auswähler-Modal – schaltet jedes Signal über die Kernel-Stummschaltungsmaske stumm oder ein |
| [`src/components/titlebar.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/titlebar.jsx) | Marke, Live-Rate, Summen, der `☠ fatal`-Zähler, Anzahl stummgeschalteter, live/pausiert |
| [`src/components/footer.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/footer.jsx) | Tastenhinweise und die Live-Filter-Eingabeaufforderung |
| [`src/lib/signals.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/signals.js) | die einzige Quelle der Wahrheit: Name, Schweregrad, Farbe, `si_code` → Quelle, Disposition, Flags, Maskendekodierung, Tödlichkeit |
| [`src/lib/format.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/format.js) | reine Formatierer – Auffüllung, Kürzung, `ago()`, Dauern, kompakte Zählungen |
| [`src/lib/fuzzy.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/fuzzy.js) | Subsequenz-Fuzzy-Match über Prozess + PID + Signal + Quelle + Disposition |

Das Modell ist ein rollierender **Feed erzeugter Signale**, der identische Wiederholungen in `×N`-Zeilen zusammenfasst. Die Erzeugungszeile eines Signals wird eingefroren, sobald seine Zustellung aufgelöst ist – so ändert oder springt eine bereits auf dem Bildschirm befindliche Zeile nie. Ein 120-ms-Fenster-Timer veröffentlicht ein Snapshot pro Frame, sodass ein ausgelasteter Ringpuffer nur ein erneutes Rendern kostet, nicht tausende.

### Warum Tracepoints, nicht `strace`/`ptrace`

`strace -f` folgt einem Prozessbaum und stoppt den Tracee bei jedem Ereignis; `ptrace` ist zielabhängig und aufdringlich. Die Signal-Tracepoints sind die Nahtstelle, an der der *Kernel* ein Signal auslöst und zustellt, für *jeden* Prozess, ohne pro-App-Einrichtung und ohne jemanden anzuhalten. Die Paarung von Erzeugung ↔ Zustellung ↔ `rt_sigreturn` ergibt das Sender/Ziel-Paar, die Disposition, die Latenz pro Handler und das EINTR-Urteil, das das gesamte Leben eines Signals verbindet.

## Tests über verschiedene Kernel hinweg

`make veristat` lädt `bin/probe.bpf.o` mit veristat auf **Ihrem** Kernel – eine schnelle Überprüfung, dass jedes Programm den Verifier besteht, plus Komplexität pro Programm (Insns/States). Das Laden von BPF erfordert Privilegien, also verwenden Sie `sudo`.

Ein Programm, das auf Ihrem Laptop lädt, kann von einem älteren Kernel-Verifier abgelehnt werden. [`.github/workflows/kernel-matrix.yml`](https://github.com/yeet-src/sigwire/blob/HEAD/.github/workflows/kernel-matrix.yml) schützt davor: Für jeden Kernel in seiner Matrix wird das Objekt gebaut, dieser Kernel in einer VM gestartet ([ciliums little-vm-helper](https://github.com/cilium/little-vm-helper), Images von `quay.io/lvh-images`), und der mitgelieferte statische **veristat** dagegen ausgeführt – der Job schlägt fehl, wenn der Verifier ein Programm ablehnt, und die Ergebnisse pro Kernel werden in einem ✅/❌-Gitter dargestellt. Das In-VM-Gate ist [`build/verify-kernel.sh`](https://github.com/yeet-src/sigwire/blob/HEAD/build/verify-kernel.sh).

Führen Sie dieselbe Matrix lokal aus (Linux + KVM) mit `make veristat-matrix` – es bootet die Kernel-Images mit `lvh` + QEMU und gibt ein `ok`/`FAIL`-Gitter aus. Wählen Sie Kernel mit `make veristat-matrix KERNELS="6.6 bpf-next"`.

## Anforderungen

> [!IMPORTANT]
> - **Ein Linux-Kernel mit BTF** (`CONFIG_DEBUG_INFO_BTF`) für CO-RE – `bpftool` generiert daraus `src/bpf/include/vmlinux.h`. Standardmäßig auf aktuellen Arch-, Fedora-, Ubuntu- und Debian-Kerneln (alle gängigen Distro-Kernel seit etwa 5.4).
> - **Der yeet-Daemon**, der den privilegierten BPF-Ladevorgang durchführt. Die BPF-Fähigkeiten werden an einen Daemon-Prozess delegiert, sodass `sigwire` selbst ohne Privilegien läuft. `curl -fsSL https://yeet.cx | sh` installiert ihn.
>
> Zum Bauen aus dem Quellcode benötigen Sie außerdem `clang` und `bpftool` – aber die mitgelieferte statische Toolchain liefert sie, sodass Sie keine systemweite C/BPF-Toolchain benötigen. Kein node/npm: esbuild wird ebenfalls mitgeliefert und das Projekt hat keine Abhängigkeiten von Drittanbietern.

## Ehrliche Einschränkungen

> [!NOTE]
> `sigwire` ist Beobachtbarkeit, nicht Durchsetzung. Es zeigt, was ausgelöst wurde; es blockiert, verzögert oder verändert kein Signal.

- **Eine Zeile ist ein *ausgelöstes* Signal.** Die Schaltzentralenzeile stammt von der Erzeugung; das Ziel kann das Signal abfangen, blockieren oder bereits beendet sein. Die Spalten Disposition/Handler/Maske stammen von der *Zustellungsseite* und werden erst ausgefüllt, wenn der Kernel es tatsächlich zustellt – ein blockiertes oder noch anhängiges Signal zeigt keine Disposition. Siehe [Was als fatal zählt](#was-als-fatal-zählt).
- **Korrelation ist Best-Effort.** Erzeugung und Zustellung sind separate Tracepoints ohne gemeinsame ID, abgeglichen auf `(Ziel-TID, Signal)` innerhalb eines Zeitfensters. Bei einem Sturm desselben Signals auf denselben Thread kann die Paarung verschmieren; im überwältigend häufigen Fall stimmt sie.
- **Die Handler-Zeitmessung misst den Rahmen des Kernels, nicht Ihre Absicht.** `ran` ist Zustellung → `rt_sigreturn`. Ein Handler, der nur ein Flag setzt (CPython, Gos Laufzeit), kehrt in Mikrosekunden zurück, selbst wenn die „echte" Arbeit später in der Ereignisschleife stattfindet – genau, nur vielleicht nicht das, was Sie erwarten.
- **EINTR-Erkennung überwacht jeden Syscall-Austritt.** Das Abfangen unterbrochener Syscalls erfordert das Anhängen an `raw_syscalls:sys_exit`, das bei *jedem* Syscall-Rückkehr systemweit feuert (der Handler bricht sofort bei allen außer den seltenen `-ERESTART*`-Codes ab, daher sind die zusätzlichen Kosten ein paar Anweisungen pro Syscall – aber nicht Null). Syscall-*Namen* sind eine x86-64-Tabelle; andere Architekturen zeigen die rohe Syscall-Nummer.
- **Der Sender eines Kernelsignals ist `current`.** Bei einem synchronen Fehler (`SIGSEGV` durch einen ungültigen Zugriff) ist das die fehlerverursachende Aufgabe selbst – korrekt und nützlich. Bei einem asynchronen Kernelsignal ist `current` die gerade laufende Aufgabe, als der Kernel es auslöste, was ein Hinweis, aber keine absolute Gewissheit ist.
- **Die Nummerierung von Echtzeitsignalen ist nominell.** `SIGRTMIN+n` wird mit dem rohen Offset angezeigt; Bibliotheken reservieren die unteren für ihre eigene Verwendung.
- **`comm` ist 16 Bytes.** Lange Prozessnamen werden vom Kernel abgeschnitten, nicht von sigwire.

## Community-Fragen

**Verlangsamt es die getraceden Prozesse?**
Kein nennenswerter Overhead. Die Tracepoint-Programme sind passiv; die Kosten sind ein begrenzter Ringpuffer-Schreibvorgang pro Signal (und die paar Anweisungen pro Syscall-Austritt für die EINTR-Erkennung), und der Ringpuffer verwirft lieber, als zu blockieren, wenn der Userspace nicht hinterherkommt.

**Zeigt es Signale an, die für einen Prozess bestimmt sind, der bereits lief, als ich es startete?**
Ja. Die Tracepoints feuern für jedes Signal ab dem Moment, in dem sigwire sich anhängt, unabhängig davon, wann der Sender oder das Ziel gestartet wurden – es gibt keinen prozessbezogenen Status, der verpasst werden könnte.

**Funktioniert es für jeden Prozess oder nur für einen?**
Jeden Prozess auf dem Host, alle gleichzeitig – die Sender-/Ziel-Leiste unterscheidet sie. Es ist der gesamte Signalverkehr der Maschine, nicht eine PID.

**Kann ich den Feed exportieren?**
Nicht eingebaut. Die `RingBuf.subscribe`-Callbacks in `probes/sigwire.js` halten jeden dekodierten Datensatz, sodass eine JSON/HTTP/Kafka-Senke ein Abzweig dort wäre. Um eine verwaltete Pipeline einzurichten, [kontaktieren Sie uns](https://yeet.cx/).

## Bauen aus dem Quellcode```sh
make          # clang + bpftool → bin/probe.bpf.o ; esbuild → src/index.jsx
make bpf      # just the BPF object
make bundle   # just the JS bundle
make clean    # remove build artifacts