[دليل التثبيت اليدوي](https://yeet.cx/docs/manual-installation) | لينكس فقط

لا حاجة لتكوين أي شيء — الإشارات هي حركة مرور خلفية ثابتة على أي جهاز، لذا تبدأ الصفوف في الوصول إلى الأعلى فورًا. هل تريد إنشاء بعضها بنفسك؟ `kill -USR1 <pid>`، `Ctrl-C` لجلب مهمة أمامية، أو قم بتشغيل أي بيئة تشغيل مُدارة وشاهد GC/المجدول الخاص بها وهو ينبه خيوطه الخاصة (`↯ EINTR futex scrolling by`).

## التحكم

يتابع الخلاصة الإشارة الأحدث افتراضيًا؛ عند تحديد صف أو الإيقاف المؤقت، فإنها تثبت بينما تستمر البيانات في التدفق بالأسفل.

| المفتاح | الإجراء |
| --- | ------ |
| `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)` الذي ينهيه. (البيئات التي تكتفي بوضع علامة في المعالج بلغة C ثم تقوم بالعمل الحقيقي لاحقًا — مثل CPython, Go — تظهر وقتًا صغيرًا هنا؛ هذا يعود لهم، وليس إلى 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` من المستخدم).

أي شيء آخر — مثل `SIGTERM` من `systemd`، أو `SIGINT` من `Ctrl-C` الخاص بك، أو `SIGPWR` من بيئة التشغيل إلى خيوطها الخاصة — يتم عرضه وتلوينه، لكن لا يُحتسب كوفاة، لأنه على الأرجح لم يكن واحدًا.

## منتقي الإشارات (مقبض نواة حي)

ثلاث إشارات هي مجرد همهمة خلفية على أي جهاز مشغول: `SIGCHLD` (كل استرداد لعملية تابعة)، `SIGURG` (نبض الاستباق غير المتزامن في Go)، و `SIGWINCH` (تغييرات حجم الطرفية، تُبث لكل عملية في المقدمة). تقوم sigwire بكتم هذه الثلاث **في النواة** افتراضيًا بحيث يكون المحتوى هو الحركة المثيرة للاهتمام — لكن أي الإشارات تعتبر ضوضاء يعود إليك.

اضغط `s` لفتح **منتقي الإشارات**: قائمة مشروطة بكل إشارة مع لون خطورتها الحي وعدد المرات التي رأيتها، وكل منها يمكن تبديله بين `shown` و `muted`. انتقل بسهم إلى واحدة (أو **اكتب رقمها** — `1`, `5` → انتقل إلى 15) ثم اضغط `space`، وسيتم عكس تلك الإشارة فورًا. `a` يعكسها **كلها** دفعة واحدة. يتتبع شريط العنوان عدد `muted` المخفيات.

هذا هو النصف ثنائي الاتجاه من العرض: قناع الكتم هو متغير عام من نوع `__u64` في قسم `.data` لبرنامج BPF الجاري، وتغيير صف يصلح البت المطابق من خلال `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`، مع أربعة برامج نقطة تتبع:

| البرنامج | مرتبط بـ | ما يلتقطه |
|---|---|---|
| `on_signal_generate` | `signal:signal_generate` | المُرسِل (`current`) + الهدف (`comm`/`pid`)، الإشارة، `si_code`، علامة `group`، `result` — يتم إسقاطه داخل النواة إذا كان بت الإشارة مضبوطًا في `mute_mask` الحي |
| `on_signal_deliver` | `signal:signal_deliver` | ترتيب الهدف (`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` — متغير عام `__u64` في قسم `.data`؛ يقوم المنتقي بتصحيح البتات الفردية لتسقط الإشارات داخل النواة.
- `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`، الترتيب/زمن الانتظار، الشارات، الصبغ، التجميع |
| [`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) | المفتش — لكل إشارة: الترتيب، المعالج، الأعلام، القناع المحظور |
| [`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` ← المصدر، الترتيب، الأعلام، فك القناع، الفتك |
| [`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 + الإشارة + المصدر + الترتيب |

النموذج هو **دفق متداول من الإشارات المولّدة**، تجميع التكرارات المتماثلة في صفوف `× N`. يتم تجميد صف التوليد للإشارة فور حل تسليمها — لذا فإن الصف الذي يظهر بالفعل على الشاشة لا يتغير أبدًا أو يقفز. مؤقت نافذة 120 مللي ثانية ينشر لقطة واحدة لكل إطار، لذا فإن الحلقة العازلة المزدحمة تكلف إعادة تصيير واحدة فقط، وليس آلافًا.

### لماذا نقاط التتبع، وليس `strace`/`ptrace`

`strace -f` يتبع شجرة عملية واحدة ويوقف الموجه عند كل حدث؛ `ptrace` موجه لكل هدف وتطفلي. نقاط تتبع الإشارات هي الوصلة حيث ترفع النواة الإشارة وتسلمها، لـ *كل* عملية، دون إعداد لكل تطبيق ودون إيقاف أحد. إقران التوليد ↔ التسليم ↔ `rt_sigreturn` هو ما يعطي زوج المرسل/الهدف، الترتيب، زمن انتظار كل معالج، وحكم 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) يحمي من ذلك: لكل نواة في مصفوفته، يبني الكائن، يشغل تلك النواة في جهاز ظاهري ([little-vm-helper من cilium](https://github.com/cilium/little-vm-helper)، صور من `quay.io/lvh-images`)، ويشغل **veristat** الثابت مقابلها — يفشل المهمة إذا رفض المدقق أي برنامج، ويعرض النتائج لكل نواة في شبكة ✅/❌. البوابة داخل الجهاز الظاهري هي [`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]
> - **نواة Linux مزودة بـ BTF** (`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` هي أداة مراقبة، وليست فرضًا. تُظهر ما تم رفعه؛ لا تحظر أو تؤخر أو تغير أي إشارة.

- **الصف يمثل إشارة *مرفوعة*.** خط لوحة التوصيل يأتي من التوليد؛ قد يلتقطها الهدف أو يحظرها أو يكون قد خرج بالفعل. أعمدة الترتيب/المعالج/القناع تأتي من جانب *التسليم* وتُملأ فقط عندما تسلمها النواة فعليًا — الإشارة المحظورة أو التي لا تزال معلقة لا تظهر ترتيبًا. انظر [ما يُعتبر مميتًا](#ما-يعتبر-مميتًا).
- **الربط هو بأفضل جهد.** التوليد والتسليم هما نقطتا تتبع منفصلتان بدون معرف مشترك، يتم مطابقتهما عبر `(target tid, signal)` ضمن نافذة زمنية. تحت عاصفة من نفس الإشارة إلى نفس الخيط، قد يكون الإقران غير دقيق؛ لكنه صحيح في الغالبية العظمى من الحالات.
- **قياس وقت المعالج يقيس إطار النواة، وليس نيتك.** `ran` هو التسليم ← `rt_sigreturn`. المعالج الذي فقط يضع علامة (CPython، بيئة تشغيل Go) يعود في ميكروثانية حتى لو حدث العمل "الحقيقي" لاحقًا في حلقة الأحداث — دقيق، لكنه ليس ما قد تتوقعه.
- **كشف EINTR يراقب كل خروج استدعاء نظام.** التقاط استدعاءات النظام المتقطعة يعني الارتباط بـ `raw_syscalls:sys_exit`، الذي يُطلق عند *كل* عودة استدعاء نظام على مستوى النظام (يخرج المعالج فورًا عند جميع الأكواد النادرة `-ERESTART*`، لذا فإن التكلفة الإضافية هي بضع تعليمات لكل استدعاء نظام — لكنها ليست صفرًا). *أسماء* استدعاءات النظام هي جدول x86-64؛ المعماريات الأخرى تُظهر رقم استدعاء النظام الخام.
- **مرسل الإشارة من النواة هو `current`.** بالنسبة لخطأ متزامن (`SIGSEGV` من وصول سيئ) يكون ذلك هو المهمة التي تسببت في الخطأ — صحيح ومفيد. بالنسبة لإشارة نواة غير متزامنة، فإن `current` هو أي مهمة كانت قيد التشغيل عندما رفعتها النواة، وهو تلميح وليس حقيقة مطلقة.
- **ترقيم إشارات الوقت الحقيقي هو اسمي.** يتم عرض `SIGRTMIN+n` بالإزاحة الخام؛ المكتبات تحتفظ بالقليلة المنخفضة لاستخدامها الخاص.
- **`comm` هو 16 بايت.** أسماء العمليات الطويلة تُقتطع بواسطة النواة، وليس بواسطة sigwire.

## أسئلة المجتمع

**هل يبطئ العمليات المتتبعة؟**
لا يوجد عبء ذو معنى. برامج نقاط التتبع سلبية؛ التكلفة هي كتابة محدودة لحلقة عازلة لكل إشارة (وعدد قليل من التعليمات لكل خروج استدعاء نظام لكشف EINTR)، والحلقة العازلة تُسقط بدلاً من الحظر إذا تخلف فضاء المستخدم.

**هل سيظهر إشارات موجهة إلى عملية كانت قيد التشغيل بالفعل عندما أبدأ؟**
نعم. نقاط التتبع تُطلق لكل إشارة من لحظة اتصال sigwire، بغض النظر عن وقت بدء المرسل أو الهدف — لا توجد حالة لكل عملية قد تكون فاتتك.

**هل يعمل لأي عملية، أم لواحدة فقط؟**
أي عملية على المضيف، كلها مرة واحدة — شريط المرسل/الهدف يفرق بينها. هو حركة إشارات الجهاز بأكمله، وليس pid واحد.

**هل يمكنني تصدير المحتوى؟**
ليس مدمجًا. استدعاءات `RingBuf.subscribe` في `probes/sigwire.js` تحتوي على كل سجل مُفكك، لذا فإن وضع مخرج 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