[Guia de instalação manual](https://yeet.cx/docs/manual-installation) | Apenas Linux

Nada para configurar — sinais são tráfego constante de fundo em qualquer máquina, então as linhas começam a aparecer no topo imediatamente. Quer gerar alguns você mesmo? `kill -USR1 <pid>`, `Ctrl-C` em um job em primeiro plano, ou inicie qualquer runtime gerenciado e observe seu GC/agendador pingar suas próprias threads (`↯ EINTR futex` passando pela tela).

## Controles

O feed segue o sinal mais recente por padrão; selecione uma linha ou pause e ele ficará parado enquanto os dados continuam fluindo abaixo.

| tecla | ação |
| --- | ------ |
| `p` · `Space` | pausar / retomar o feed (congelar para ler) |
| `↑`/`↓`, `k`/`j` | pausar e inspecionar uma linha — abre o painel de detalhes |
| `/` | filtro difuso — corresponde a processo, pid, sinal, fonte e disposição; caracteres correspondentes destacam-se ao vivo |
| `e` | filtrar para **apenas syscalls interrompidas** (`↯ EINTR` / `↺ reiniciadas`) |
| `s` | abrir o **seletor de sinais** — silenciar ou mostrar qualquer sinal, ao vivo |
| `Esc` | retroceder uma camada — limpar o filtro / fechar o seletor / descartar a seleção, depois sair |
| `q` | sair |

## O que você está vendo

Cada linha é um sinal gerado, o mais recente no topo:```
 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` (executou um manipulador em userspace), `default` (→ a ação padrão: terminar / core dump / parar / ignorar) ou `ignored`.
- **syscall** — se este sinal interrompeu uma syscall bloqueada: `EINTR ← read` (userspace viu `EINTR`) ou `restarted read` (`SA_RESTART` a retomou transparentemente).
- **ran** — quanto tempo o manipulador executou, medido da entrega ao `rt_sigreturn(2)` que o encerra. (Runtimes que apenas marcam uma flag no manipulador C e fazem o trabalho real depois — CPython, Go — mostram um tempo pequeno aqui; isso é eles, não o sigwire.)
- **flags** — as flags `sigaction` do manipulador (`SA_RESTART`, `SA_SIGINFO`, `SA_NODEFER`, …).
- **TARGET BLOCKS** — os sinais que o alvo tinha bloqueado (seu `sigprocmask`) no momento da entrega, diretamente do seu `task_struct`.

`Esc` fecha o inspetor; `p` retoma o feed ao vivo.

## O que conta como fatal

O contador `☠ fatal` e o badge de linha `☠` são intencionalmente rigorosos. Como `signal_generate` dispara na *geração*, o sigwire não consegue ver se o alvo instalou um manipulador — um `SIGTERM` pode ser capturado e transformado num desligamento limpo, ou ignorado por completo. Então só conta uma morte quando é inequívoco:

- **`SIGKILL`** entregue — incapturável, inignorável, sempre fatal; **ou**
- um **sinal de core dump** (`SEGV`/`BUS`/`ABRT`/`ILL`/`FPE`/`TRAP`/`SYS`/`QUIT`) que o **próprio kernel levantou** (uma falha síncrona, não um `kill` de userspace).

Qualquer outra coisa — um `SIGTERM` do `systemd`, um `SIGINT` do seu `Ctrl-C`, um `SIGPWR` de um runtime para as suas próprias threads — é mostrado e colorido, mas não contado como morte, porque provavelmente não foi uma.

## O seletor de sinais (um knob do kernel ao vivo)

Três sinais são puro ruído de fundo em qualquer máquina ocupada: `SIGCHLD` (cada coleta de filho), `SIGURG` (batida cardíaca de pré-empção assíncrona do Go) e `SIGWINCH` (redimensionamentos de terminal, transmitidos para todos os processos em primeiro plano). O sigwire silencia esses três **no kernel** por defeito para que o feed seja o tráfego interessante — mas quais sinais são ruído é por sua conta.

Prima `s` para abrir o **seletor de sinais**: uma lista modal de cada sinal com a sua cor de gravidade ao vivo e quantos já viu, cada um alternável entre `shown` e `muted`. Navegue com setas até um (ou **digite o seu número** — `1`, `5` → salta para o 15) e prima `space`, e esse sinal muda instantaneamente. `a` alterna-os **todos** de uma vez. O `muted` count na barra de título monitoriza quantos estão ocultos.

Esta é a metade bidirecional da demonstração: a máscara de silêncio é um `__u64` global na secção `.data` do programa BPF em execução, e alternar uma linha corrige o bit correspondente através de `DataSec.patch()` enquanto o programa continua a executar. O kernel descarta sinais silenciados antes de chegarem ao ring buffer, por isso silenciar não lhe custa nada — e reativar traz um sinal de volta a meio da transmissão sem recarregar.

## Como funciona

O núcleo é [`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, ligados num único objeto) e [`src/probes/sigwire.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/sigwire.js) (userspace). Tudo é correlacionado por `(target tid, signal)`.

### O lado BPF

Dois ficheiros fonte ligam-se num único objeto carregável, `bin/probe.bpf.o`, com quatro programas de tracepoint:

| Programa | Anexado a | O que captura |
|---|---|---|
| `on_signal_generate` | `signal:signal_generate` | o emissor (`current`) + alvo (`comm`/`pid`), o sinal, `si_code`, flag `group`, `result` — descartado in-kernel se o bit do sinal estiver definido na `mute_mask` ao vivo |
| `on_signal_deliver` | `signal:signal_deliver` | a disposição do alvo (`sa_handler`), `sa_flags` e — a partir de `task_struct` — o seu sigset `blocked`; carimba a entrega para temporização do manipulador |
| (rt_sigreturn) | `syscalls:sys_enter_rt_sigreturn` | calcula a diferença em relação à entrega carimbada para o tempo de execução do manipulador |
| (sys_exit) | `raw_syscalls:sys_exit` | regista o raro retorno `-ERESTART*` para que o próximo `signal_deliver` o resolva em `EINTR`/`restarted` + o número da syscall interrompida |

Os mapas ligam o kernel ao userspace:

- `events` — `RINGBUF`, um `signal_event` por geração.
- `dispatch` — `RINGBUF`, um `dispatch_event` por entrega / retorno do manipulador.
- `mute_mask` — um `__u64` global na secção `.data`; o seletor corrige bits individuais para descartar sinais in-kernel.
- `handler_start` / `restart_pending` — `HASH` indexado por tid, espaço de rascunho por thread que emparelha uma entrega com o seu `rt_sigreturn`, e a saída `-ERESTART*` de uma syscall com a entrega que se segue.

### O lado JS

| ficheiro | responsabilidade |
|---|---|
| [`src/probes/probe.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/probe.js) | carrega `bin/probe.bpf.o` uma vez, vincula os mapas, inicia os programas (auto-anexam) |
| [`src/probes/sigwire.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/sigwire.js) | o único módulo de dados com conhecimento BPF: combina ambos os ring buffers num feed contínuo com totais, correlaciona a entrega com a geração, possui o controlo da máscara de silêncio — expõe os sinais `feed`, `visible`, `muteMask` |
| [`src/main.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/main.jsx) | raiz de composição: entrada, seleção, layout responsivo (a barra lateral esconde-se em terminais estreitos), `mount` |
| [`src/components/feed.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/feed.jsx) | a central telefónica: `emissor ──SIG──▶ alvo`, disposição/latência, badges, matiz, coalescência |
| [`src/components/tally.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/tally.jsx) | a barra lateral — principais sinais, repartição por origem, contagem de entregas |
| [`src/components/detail.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/detail.jsx) | o inspetor — disposição do sinal, manipulador, flags, máscara de bloqueio |
| [`src/components/picker.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/picker.jsx) | o modal do seletor de sinais — silencia/mostra cada sinal através da máscara de silêncio do kernel |
| [`src/components/titlebar.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/titlebar.jsx) | marca, taxa ao vivo, totais, o contador `☠ fatal`, contagem de silenciados, ao vivo/pausado |
| [`src/components/footer.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/footer.jsx) | dicas de teclas e o prompt do filtro ao vivo |
| [`src/lib/signals.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/signals.js) | a única fonte de verdade: nome, gravidade, cor, `si_code` → origem, disposição, flags, descodificação de máscara, fatalidade |
| [`src/lib/format.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/format.js) | formatadores puros — preenchimento, truncatura, `ago()`, durações, contagens compactas |
| [`src/lib/fuzzy.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/fuzzy.js) | correspondência difusa de subsequência sobre processo + pid + sinal + origem + disposição |

O modelo é um **feed contínuo de sinais gerados**, coalescendo repetições idênticas em linhas `×N`. A linha de geração de um sinal é congelada no instante em que a sua entrega é resolvida — por isso uma linha já no ecrã nunca muda ou salta. Um temporizador de janela de 120 ms publica uma imagem por frame, portanto um ring buffer ocupado custa uma re-renderização, não milhares.

### Porquê tracepoints e não `strace`/`ptrace`

`strace -f` segue uma árvore de processos e pára o tracee em cada evento; `ptrace` é por alvo e intrusivo. Os tracepoints de sinal são a junção onde o *kernel* levanta e entrega um sinal, para *todos* os processos, sem configuração por aplicação e sem parar ninguém. Emparelhar geração ↔ entrega ↔ `rt_sigreturn` é o que produz o par emissor/alvo, a disposição, a latência por manipulador e o veredito EINTR que unem toda a vida de um sinal.

## Testando entre kernels

`make veristat` carrega `bin/probe.bpf.o` com veristat no **seu** kernel — uma verificação rápida de que cada programa passa o verificador, mais a complexidade por programa (insns/states). Carregar BPF necessita de privilégios, por isso use `sudo`.

Um programa que carrega no seu portátil pode ser rejeitado pelo verificador de um kernel mais antigo. [`.github/workflows/kernel-matrix.yml`](https://github.com/yeet-src/sigwire/blob/HEAD/.github/workflows/kernel-matrix.yml) protege contra isso: para cada kernel na sua matriz, constrói o objeto, arranca esse kernel numa VM ([little-vm-helper do cilium](https://github.com/cilium/little-vm-helper), imagens de `quay.io/lvh-images`) e executa o **veristat** estático fornecido contra ele — falhando o job se o verificador rejeitar algum programa, e pivotando os resultados por kernel numa grelha ✅/❌. O gate na VM é [`build/verify-kernel.sh`](https://github.com/yeet-src/sigwire/blob/HEAD/build/verify-kernel.sh).

Execute a mesma matriz localmente (Linux + KVM) com `make veristat-matrix` — arranca as imagens de kernel com `lvh` + QEMU e imprime uma grelha `ok`/`FAIL`. Escolha kernels com `make veristat-matrix KERNELS="6.6 bpf-next"`.

## Requisitos

> [!IMPORTANT]
> - **Um kernel Linux com BTF** (`CONFIG_DEBUG_INFO_BTF`) para CO-RE — o `bpftool` gera `src/bpf/include/vmlinux.h` a partir dele. Padrão nas atuais Arch, Fedora, Ubuntu e Debian (todos os kernels de distribuição mainstream desde ~5.4).
> - **O daemon yeet**, que realiza a carga BPF privilegiada. As capacidades BPF são delegadas a um processo daemonizado, por isso o `sigwire` propriamente dito executa sem privilégios. `curl -fsSL https://yeet.cx | sh` instala-o.
>
> Para compilar a partir do código-fonte também precisa de `clang` e `bpftool` — mas a toolchain estática fornecida fornece-os, por isso não precisa de uma toolchain C/BPF de sistema. Sem node/npm: o esbuild também é fornecido e o projeto não tem dependências de terceiros.

## Advertências honestas

> [!NOTE]
> O `sigwire` é observabilidade, não imposição. Mostra o que foi levantado; não bloqueia, atrasa ou altera nenhum sinal.

- **Uma linha é um sinal *levantado*.** A linha da central telefónica vem da geração; o alvo pode capturá-lo, bloqueá-lo ou já ter saído. As colunas de disposição/manipulador/máscara vêm do lado da *entrega* e preenchem-se apenas quando o kernel efetivamente o entrega — um sinal bloqueado ou ainda pendente não mostra disposição. Veja [O que conta como fatal](#o-que-conta-como-fatal).
- **A correlação é de melhor esforço.** Geração e entrega são tracepoints separados sem id partilhado, correspondidos por `(target tid, signal)` dentro de uma janela temporal. Sob uma tempestade do mesmo sinal para a mesma thread o emparelhamento pode desfocar; está correto no caso comum esmagador.
- **A temporização do manipulador mede o quadro do kernel, não a sua intenção.** `ran` é entrega → `rt_sigreturn`. Um manipulador que apenas define uma flag (CPython, runtime do Go) retorna em microssegundos mesmo que o trabalho "real" aconteça depois no loop de eventos — preciso, só não é o que talvez esperasse.
- **A deteção de EINTR observa todas as saídas de syscall.** Capturar syscalls interrompidas implica anexar a `raw_syscalls:sys_exit`, que dispara em *cada* retorno de syscall em todo o sistema (o manipulador sai imediatamente em todos exceto os raros códigos `-ERESTART*`, portanto o custo adicional é de algumas instruções por syscall — mas não é zero). Os *nomes* das syscalls são uma tabela x86-64; outras arquiteturas mostram o número bruto da syscall.
- **O emissor de um sinal do kernel é `current`.** Para uma falha síncrona (`SIGSEGV` de um acesso inválido) é a própria tarefa a falhar — correto e útil. Para um sinal assíncrono do kernel, `current` é a tarefa que estava a executar quando o kernel o levantou, o que é uma dica, não um evangelho.
- **A numeração de sinais em tempo real é nominal.** `SIGRTMIN+n` é mostrado pelo offset bruto; as bibliotecas reservam os poucos mais baixos para seu próprio uso.
- **`comm` tem 16 bytes.** Nomes de processos longos são truncados pelo kernel, não pelo sigwire.

## Perguntas da comunidade

**Isso abranda os processos monitorizados?**
Nenhuma sobrecarga significativa. Os programas de tracepoint são passivos; o custo é uma escrita limitada no ring buffer por sinal (e as poucas instruções por saída de syscall para deteção de EINTR), e o ring buffer descarta em vez de bloquear se o userspace ficar para trás.

**Mostrará sinais dirigidos a um processo que já estava a executar quando eu o iniciar?**
Sim. Os tracepoints disparam para cada sinal desde o momento em que o sigwire anexa, independentemente de quando o emissor ou alvo começou — não há estado por processo a ter sido perdido.

**Funciona para qualquer processo, ou apenas um?**
Qualquer processo no anfitrião, todos ao mesmo tempo — a calha emissor/alvo distingue-os. É o tráfego de sinais de toda a máquina, não um pid.

**Posso exportar o feed?**
Não está incorporado. As chamadas de retorno `RingBuf.subscribe` em `probes/sigwire.js` contêm todos os registos descodificados, portanto um sumidouro JSON/HTTP/Kafka é um ramo ali. Para configurar um pipeline gerido, [contacte-nos](https://yeet.cx/).

## Compilando a partir do código-fonte```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