[수동 설치 가이드](https://yeet.cx/docs/manual-installation) | Linux 전용

구성할 것이 없습니다 — 신호는 모든 박스에서 지속적인 백그라운드 트래픽이므로 행이 즉시 상단에 나타나기 시작합니다. 직접 만들어 보고 싶으신가요? `kill -USR1 <pid>`, 포그라운드 작업에서 `Ctrl-C`, 또는 관리형 런타임을 시작하고 해당 런타임의 GC/스케줄러가 자체 스레드에 ping을 보내는 것을 확인하세요 (`↯ EINTR futex` 스크롤되는).

## 컨트롤

피드는 기본적으로 최신 신호를 따라갑니다. 행을 선택하거나 일시 중지하면 데이터가 아래에서 계속 흐르는 동안 정지 상태를 유지합니다.

| 키 | 동작 |
| --- | ------ |
| `p` · `Space` | 피드 일시 중지 / 재개 (읽기 위해 고정) |
| `↑`/`↓`, `k`/`j` | 행을 일시 중지하고 검사 — 세부 패널 열기 |
| `/` | 퍼지 필터 — 프로세스, PID, 신호, 소스 및 처분과 일치; 일치하는 문자는 실시간으로 강조 표시 |
| `e` | **중단된 시스템 호출만** 필터링 (`↯ EINTR` / `↺ 재시작됨`) |
| `s` | **신호 선택기** 열기 — 모든 신호를 음소거 또는 표시, 실시간 |
| `Esc` | 한 단계 뒤로 — 필터 지우기 / 선택기 닫기 / 선택 해제, 그런 다음 종료 |
| `q` | 종료 |

## 보고 있는 것

각 행은 하나의 생성된 신호이며, 최신 신호가 상단에 있습니다:```
 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` (사용자 공간 핸들러 실행), `default` (→ 기본 동작: 종료 / 코어 덤프 / 중단 / 무시), 또는 `ignored`.
- **syscall** — 이 시그널이 블록된 시스템 콜을 중단시킨 경우: `EINTR ← read` (사용자 공간에서 `EINTR` 수신) 또는 `restarted read` (`SA_RESTART`로 투명하게 재개됨).
- **ran** — 핸들러 실행 시간. 전달부터 이를 종료하는 `rt_sigreturn(2)`까지 측정. (CPython, Go와 같이 C 핸들러에서 플래그만 설정하고 실제 작업은 나중에 수행하는 런타임은 여기서 매우 짧은 시간을 보여줌; 이는 런타임의 특성이며 sigwire의 문제가 아님)
- **flags** — 핸들러에 설정된 `sigaction` 플래그 (`SA_RESTART`, `SA_SIGINFO`, `SA_NODEFER`, …).
- **TARGET BLOCKS** — 전달 시점에 대상이 블록한 시그널(`sigprocmask`)이며, `task_struct`에서 직접 가져옴.

`Esc`는 검사기를 닫고, `p`는 실시간 피드를 재개합니다.

## 치명적인 것으로 간주하는 기준

`☠ fatal` 카운터와 `☠` 행 배지는 의도적으로 엄격합니다. `signal_generate`는 시그널이 *생성될* 때 발생하므로, sigwire는 대상이 핸들러를 설치했는지 알 수 없습니다. `SIGTERM`이 잡혀서 정상 종료되거나 완전히 무시될 수 있기 때문입니다. 따라서 명확하게 치명적일 때만 사망으로 계산합니다:

- **`SIGKILL`** 전달 — 잡을 수 없고, 무시할 수 없으며, 항상 치명적임; **또는**
- **코어 덤프 시그널**(`SEGV`/`BUS`/`ABRT`/`ILL`/`FPE`/`TRAP`/`SYS`/`QUIT`)이 **커널 자체에 의해 발생**된 경우 (동기적 결함, 사용자 공간의 `kill`이 아님).

그 외의 모든 것 — `systemd`의 `SIGTERM`, `Ctrl-C`의 `SIGINT`, 런타임이 자신의 스레드에 보낸 `SIGPWR` — 은 표시되고 색상이 지정되지만, 사망으로 계산되지 않습니다. 왜냐하면 그렇지 않을 가능성이 높기 때문입니다.

## 시그널 선택기 (실시간 커널 노브)

세 가지 시그널은 바쁜 시스템에서 순수한 백그라운드 잡음입니다: `SIGCHLD` (모든 자식 수거), `SIGURG` (Go의 비동기 선점 하트비트), `SIGWINCH` (터미널 크기 변경, 모든 포그라운드 프로세스에 브로드캐스트). sigwire는 기본적으로 이 세 가지를 **커널에서** 음소거하여 피드가 흥미로운 트래픽만 표시하도록 합니다. 그러나 어떤 시그널이 잡음인지는 사용자가 결정할 수 있습니다.

`p`를 누르면 **시그널 선택기**가 열립니다: 각 시그널의 실시간 심각도 색상과 지금까지 본 횟수가 표시된 모달 목록으로, 각각 `shown`과 `muted` 사이를 전환할 수 있습니다. 화살표로 이동하거나 (**숫자를 입력** — `1`, `5` → 15로 점프) 스페이스바를 누르면 해당 시그널이 즉시 전환됩니다. `a`를 누르면 **모든** 시그널을 한 번에 전환합니다. 제목 표시줄의 `muted` 개수는 숨겨진 시그널 수를 추적합니다.

이것은 데모의 양방향 부분입니다: 음소거 마스크는 실행 중인 BPF 프로그램의 `.data` 섹션에 있는 `__u64` 전역 변수이며, 행을 전환하면 프로그램이 계속 실행되는 동안 `DataSec.patch()`를 통해 해당 비트가 패치됩니다. 커널은 시그널이 링 버퍼에 도달하기 전에 음소거된 시그널을 버리므로, 음소거는 비용이 들지 않습니다. 그리고 음소거 해제는 리로드 없이 중간 스트림에서 시그널을 다시 가져옵니다.

## 작동 방식

핵심은 [`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) (커널, 하나의 객체로 링크됨)와 [`src/probes/sigwire.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/sigwire.js) (사용자 공간)입니다. 모든 것은 `(target tid, signal)`로 상관 관계가 있습니다.

### BPF 측

두 소스 파일은 하나의 로드 가능한 객체 `bin/probe.bpf.o`로 링크되며, 4개의 tracepoint 프로그램이 있습니다:

| 프로그램 | 연결 대상 | 캡처 내용 |
|---|---|---|
| `on_signal_generate` | `signal:signal_generate` | 송신자 (`current`) + 대상 (`comm`/`pid`), 시그널, `si_code`, `group` 플래그, `result` — 해당 시그널 비트가 실시간 `mute_mask`에 설정된 경우 커널 내에서 버려짐 |
| `on_signal_deliver` | `signal:signal_deliver` | 대상의 disposition (`sa_handler`), `sa_flags`, 그리고 `task_struct`에서 가져온 `blocked` 시그널 집합; 핸들러 타이밍을 위해 전달 시간을 기록 |
| (rt_sigreturn) | `syscalls:sys_enter_rt_sigreturn` | 기록된 전달 시간과의 차이를 계산하여 핸들러 실행 시간을 얻음 |
| (sys_exit) | `raw_syscalls:sys_exit` | 드문 `-ERESTART*` 반환을 기록하여 다음 `signal_deliver`에서 `EINTR`/`restarted` + 중단된 시스템 콜 번호로 해석 |

맵이 커널과 사용자 공간을 연결합니다:

- `events` — `RINGBUF`, 생성당 하나의 `signal_event`.
- `dispatch` — `RINGBUF`, 전달/핸들러 반환당 하나의 `dispatch_event`.
- `mute_mask` — `.data` 섹션의 `__u64` 전역 변수; 선택기가 개별 비트를 패치하여 커널 내에서 시그널을 버림.
- `handler_start` / `restart_pending` — `HASH`, tid를 키로 하는 스레드별 스크래치 공간으로, 전달과 `rt_sigreturn`을 짝짓고, 시스템 콜의 `-ERESTART*` 종료와 그 뒤에 오는 전달을 연결.

### JS 측

| 파일 | 책임 |
|---|---|
| [`src/probes/probe.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/probe.js) | `bin/probe.bpf.o`를 한 번 로드하고, 맵을 바인딩하며, 프로그램을 시작 (자동 연결) |
| [`src/probes/sigwire.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/probes/sigwire.js) | 유일한 BPF 인식 데이터 모듈: 두 개의 링 버퍼를 롤링 피드로 병합하고 집계하며, 전달을 생성과 상관 관계를 맺고, 음소거 마스크 노브를 소유 — `feed`, `visible`, `muteMask` 시그널을 노출 |
| [`src/main.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/main.jsx) | 구성 루트: 입력, 선택, 반응형 레이아웃 (좁은 터미널에서 레일 숨김), `mount` |
| [`src/components/feed.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/feed.jsx) | 스위치보드: `sender ──SIG──▶ target`, disposition/지연 시간, 배지, 색조, 병합 |
| [`src/components/tally.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/tally.jsx) | 사이드 레일 — 상위 시그널, 소스별 분석, 전달 집계 |
| [`src/components/detail.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/detail.jsx) | 검사기 — 시그널별 disposition, 핸들러, 플래그, 블록 마스크 |
| [`src/components/picker.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/picker.jsx) | 시그널 선택기 모달 — 커널 음소거 마스크를 통해 각 시그널을 음소거/표시 |
| [`src/components/titlebar.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/titlebar.jsx) | 브랜드, 실시간 속도, 총계, `☠ fatal` 카운터, 음소거 개수, 재생/일시 중지 |
| [`src/components/footer.jsx`](https://github.com/yeet-src/sigwire/blob/HEAD/src/components/footer.jsx) | 키 힌트와 실시간 필터 프롬프트 |
| [`src/lib/signals.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/signals.js) | 유일한 진실 공급원: 이름, 심각도, 색상, `si_code` → 소스, disposition, 플래그, 마스크 디코딩, 치명성 |
| [`src/lib/format.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/format.js) | 순수 포매터 — 패딩, 자르기, `ago()`, 지속 시간, 간결한 개수 |
| [`src/lib/fuzzy.js`](https://github.com/yeet-src/sigwire/blob/HEAD/src/lib/fuzzy.js) | 프로세스 + pid + 시그널 + 소스 + disposition에 대한 하위 시퀀스 퍼지 매칭 |

모델은 **생성된 시그널의 롤링 피드**이며, 동일한 반복을 `×N` 행으로 병합합니다. 시그널의 생성 행은 전달이 해결되는 즉시 고정되므로, 이미 화면에 있는 행은 절대 변경되거나 이동하지 않습니다. 120ms 윈도우 타이머가 프레임당 하나의 스냅샷을 게시하므로, 바쁜 링 버퍼는 수천 번이 아닌 한 번의 리렌더링만 발생합니다.

### 왜 tracepoint인가? (`strace`/`ptrace`가 아닌 이유)

`strace -f`는 하나의 프로세스 트리를 따르고 이벤트마다 tracee를 중단합니다. `ptrace`는 대상별로 침습적입니다. 시그널 tracepoint는 *커널*이 시그널을 발생시키고 전달하는 지점으로, 모든 프로세스에 대해 앱별 설정 없이 아무도 중단하지 않습니다. 생성 ↔ 전달 ↔ `rt_sigreturn`을 짝짓는 것은 송신자/대상 쌍, disposition, 핸들러별 지연 시간, 그리고 시그널의 전체 생애를 하나로 묶는 EINTR 판정을 제공합니다.

## 다양한 커널에서 테스트

`make veristat`는 **사용자의** 커널에서 `bin/probe.bpf.o`를 veristat으로 로드합니다 — 각 프로그램이 검증기를 통과하는지 빠르게 확인하고, 프로그램별 복잡도(insns/states)를 출력합니다. BPF 로드에는 권한이 필요하므로 `sudo`를 사용하십시오.

랩톱에서 로드되는 프로그램이 이전 커널의 검증기에서 거부될 수 있습니다. [`.github/workflows/kernel-matrix.yml`](https://github.com/yeet-src/sigwire/blob/HEAD/.github/workflows/kernel-matrix.yml)이 이를 방지합니다: 행렬의 각 커널에 대해 객체를 빌드하고, 해당 커널을 VM에서 부팅하며([cilium's little-vm-helper](https://github.com/cilium/little-vm-helper), 이미지는 `quay.io/lvh-images`에서 가져옴), 정적 **veristat**를 실행합니다. 검증기가 프로그램을 거부하면 작업이 실패하고, 커널별 결과가 하나의 ✅/❌ 그리드로 표시됩니다. VM 내 게이트는 [`build/verify-kernel.sh`](https://github.com/yeet-src/sigwire/blob/HEAD/build/verify-kernel.sh)입니다.

로컬에서 동일한 행렬을 실행하려면 (Linux + KVM) `make veristat-matrix`를 사용하십시오 — `lvh` + QEMU로 커널 이미지를 부팅하고 `ok`/`FAIL` 그리드를 출력합니다. `make veristat-matrix KERNELS="6.6 bpf-next"`로 특정 커널을 선택할 수 있습니다.

## 요구 사항

> [!IMPORTANT]
> - **BTF가 있는 Linux 커널** (`CONFIG_DEBUG_INFO_BTF`) — CO-RE를 위해 필요하며, `bpftool`이 `src/bpf/include/vmlinux.h`를 생성합니다. 최신 Arch, Fedora, Ubuntu, Debian (대부분의 주류 배포판 커널 ~5.4부터)에서 기본값.
> - **yeet 데몬** — 권한이 필요한 BPF 로드를 수행합니다. BPF 기능이 데몬화된 프로세스에 위임되므로, `sigwire` 자체는 권한 없이 실행됩니다. `curl -fsSL https://yeet.cx | sh`로 설치합니다.
>
> 소스에서 빌드하려면 `clang`과 `bpftool`도 필요합니다. 그러나 정적 툴체인이 함께 제공되므로 시스템 C/BPF 툴체인은 필요하지 않습니다. node/npm도 필요 없습니다: esbuild도 함께 제공되며 프로젝트에 타사 종속성이 없습니다.

## 정직한 주의사항

> [!NOTE]
> `sigwire`는 관찰 가능성 도구이지, 강제 도구가 아닙니다. 발생된 시그널을 보여줄 뿐, 차단하거나 지연시키거나 변경하지 않습니다.

- **행은 *발생된* 시그널입니다.** 스위치보드 라인은 생성 시점에서 비롯됩니다. 대상이 이를 잡거나, 차단하거나, 이미 종료되었을 수 있습니다. disposition/handler/mask 열은 *전달* 측에서 오며 커널이 실제로 전달할 때만 채워집니다 — 차단되었거나 아직 대기 중인 시그널은 disposition이 표시되지 않습니다. [치명적인 것으로 간주하는 기준](#치명적인-것으로-간주하는-기준)을 참조하십시오.
- **상관 관계는 최선의 노력입니다.** 생성과 전달은 별도의 tracepoint이며 공유 ID가 없고, 시간 창 내에서 `(target tid, signal)`로 매칭됩니다. 동일한 시그널이 동일한 스레드에 폭주할 경우 짝짓기가 흐려질 수 있습니다. 대부분의 일반적인 경우에는 정확합니다.
- **핸들러 타이밍은 커널의 프레임을 측정하며, 사용자의 의도를 측정하지 않습니다.** `ran`은 전달 → `rt_sigreturn`입니다. 플래그만 설정하는 핸들러(CPython, Go 런타임)는 "실제" 작업이 나중에 이벤트 루프에서 발생하더라도 마이크로초 단위로 반환됩니다 — 정확하지만 예상과 다를 수 있습니다.
- **EINTR 감지는 모든 시스템 콜 종료를 감시합니다.** 중단된 시스템 콜을 포착하려면 `raw_syscalls:sys_exit`에 연결해야 하며, 이는 시스템 전체의 모든 시스템 콜 반환에서 발생합니다 (핸들러는 드문 `-ERESTART*` 코드를 제외하고 즉시 종료되므로 추가 비용은 시스템 콜당 몇 개의 명령어입니다 — 하지만 0은 아닙니다). 시스템 콜 *이름*은 x86-64 테이블입니다. 다른 아키텍처에서는 원시 시스템 콜 번호가 표시됩니다.
- **커널 시그널의 송신자는 `current`입니다.** 동기적 결함(잘못된 접근으로 인한 `SIGSEGV`)의 경우, 이는 결함이 있는 태스크 자체입니다 — 정확하고 유용합니다. 비동기 커널 시그널의 경우, `current`는 커널이 시그널을 발생시킬 때 실행 중이던 태스크로, 힌트일 뿐 확실하지 않습니다.
- **실시간 시그널 번호는 명목상입니다.** `SIGRTMIN+n`은 원시 오프셋으로 표시됩니다. 라이브러리는 낮은 번호를 자체적으로 사용하기 위해 예약합니다.
- **`comm`은 16바이트입니다.** 긴 프로세스 이름은 sigwire가 아닌 커널에 의해 잘립니다.

## 커뮤니티 질문

**추적되는 프로세스의 속도를 저하시키나요?**
의미 있는 오버헤드는 없습니다. tracepoint 프로그램은 수동적입니다. 비용은 시그널당 제한된 링 버퍼 쓰기 (및 EINTR 감지를 위한 시스템 콜 종료당 몇 개의 명령어)이며, 사용자 공간이 뒤처지면 링 버퍼는 차단하지 않고 버립니다.

**시작할 때 이미 실행 중이던 프로세스를 대상으로 하는 시그널도 표시되나요?**
네. sigwire가 연결되는 순간부터 모든 시그널에 대해 tracepoint가 발생합니다. 송신자나 대상이 언제 시작되었는지와 관계없이, 놓친 프로세스별 상태가 없습니다.

**특정 프로세스에만 작동하나요, 아니면 모든 프로세스에 작동하나요?**
호스트의 모든 프로세스, 한 번에 모두 — 송신자/대상 거터에서 구분합니다. 단일 pid가 아닌 전체 머신의 시그널 트래픽입니다.

**피드를 내보낼 수 있나요?**
내장 기능은 아닙니다. `probes/sigwire.js`의 `RingBuf.subscribe` 콜백은 모든 디코딩된 레코드를 보유하므로, JSON/HTTP/Kafka 싱크를 추가하는 분기가 있습니다. 관리형 파이프라인을 설정하려면 [당사에 문의](https://yeet.cx/)하십시오.

## 소스에서 빌드하기```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