# Monitor

يشغّل مراقبًا في الخلفية يبثّ الأحداث من برنامج نصي طويل الأمد. كل سطر في المخرجات القياسية يصبح إشعارًا — واصل عملك بينما تصل الأحداث في المحادثة.

## متى يُستخدم

- تتبّع الأخطاء والتحذيرات وأنماط الانهيار في ملف السجل أثناء تشغيل عملية النشر
- استطلاع واجهة برمجية بعيدة أو طلب سحب أو أنبوب CI كل 30 ثانية للكشف عن أحداث الحالة الجديدة
- مراقبة التغييرات في دليل نظام الملفات أو مخرجات البناء في الوقت الفعلي
- انتظار شرط محدد عبر تكرارات عديدة (مثل الوصول إلى نقطة تحقق في خطوة تدريب أو إفراغ طابور)
- **ليس** للانتظار البسيط حتى الانتهاء — استخدم `Bash` مع `run_in_background` لذلك؛ يُرسل إشعار اكتمال واحد عند انتهاء العملية

## المعاملات

- `command` (نص، مطلوب): أمر الصدفة أو البرنامج النصي المراد تشغيله. كل سطر يُكتب في المخرجات القياسية يصبح حدث إشعار مستقلًا. ينتهي المراقب عند انتهاء العملية.
- `description` (نص، مطلوب): تسمية قصيرة قابلة للقراءة تظهر في كل إشعار. كن محددًا — "الأخطاء في deploy.log" أفضل من "مراقبة السجلات". تُعرّف هذه التسمية أيّ مراقب قد اشتغل.
- `timeout_ms` (رقم، الافتراضي `300000`، الحد الأقصى `3600000`): مهلة الإنهاء القسري بالمللي ثانية. بعد هذه المدة تُنهى العملية. يُتجاهل عند `persistent: true`.
- `persistent` (قيمة منطقية، الافتراضي `false`): عند `true` يعمل المراقب طوال فترة الجلسة دون مهلة. أوقفه صراحةً باستخدام `TaskStop`.

## أمثلة

### المثال الأول: تتبّع ملف سجل للأخطاء والانهيارات

يغطّي هذا المثال جميع الحالات النهائية: علامة النجاح، والتتبّع الخلفي، وكلمات الخطأ الشائعة، والإنهاء بسبب OOM، والخروج غير المتوقع للعملية.

```bash
tail -F /var/log/deploy.log | grep -E --line-buffered \
  "deployed|Traceback|Error|FAILED|assert|Killed|OOM"
```

استخدم `grep --line-buffered` في كل أنبوب. بدونه يخزّن نظام التشغيل المخرجات في كتل 4 كيلوبايت وقد تتأخر الأحداث لدقائق. يغطّي نمط التبديل مسار النجاح (`deployed`) ومسارات الإخفاق (`Traceback`، `Error`، `FAILED`، `Killed`، `OOM`). المراقب الذي يرصد علامة النجاح فقط يبقى صامتًا عند الانهيار — الصمت لا يختلف عن "لا يزال يعمل".

### المثال الثاني: استطلاع واجهة برمجية بعيدة كل 30 ثانية

```bash
while true; do
  curl -sf "https://api.example.com/status" || true
  sleep 30
done | grep --line-buffered -E "completed|failed|error"
```

`|| true` يمنع خطأ شبكي عابرًا من إنهاء الحلقة. فترات الاستطلاع البالغة 30 ثانية أو أكثر مناسبة للواجهات البرمجية البعيدة لتجنب حدود معدل الطلبات. عدّل نمط grep لالتقاط استجابات النجاح والإخفاق على حدٍّ سواء حتى لا تُخفي الأخطاء من جانب الواجهة البرمجية بالصمت.

## ملاحظات

- **استخدم دائمًا `grep --line-buffered` في الأنابيب.** بدونه يؤخّر تخزين الأنبوب الأحداث لدقائق لأن نظام التشغيل يجمع المخرجات حتى يمتلئ كتلة 4 كيلوبايت. يفرض `--line-buffered` تفريغ الذاكرة المؤقتة بعد كل سطر.
- **يجب أن يغطّي الفلتر توقيعات النجاح والإخفاق معًا.** المراقب الذي يرصد علامة النجاح فقط يبقى صامتًا عند الانهيار أو التجمّد أو الخروج غير المتوقع. وسّع التبديل: أضف `Error`، `Traceback`، `FAILED`، `Killed`، `OOM` وعلامات الحالة النهائية المماثلة بجانب كلمة النجاح.
- **فترات الاستطلاع: 30 ثانية أو أكثر للواجهات البرمجية البعيدة.** الاستطلاع المتكرر للخدمات الخارجية يخاطر بأخطاء حدود معدل الطلبات أو الحظر. لفحوصات نظام الملفات المحلية أو العمليات، 0.5–1 ثانية مناسبة.
- **استخدم `persistent: true` للمراقبين طوال فترة الجلسة.** القيمة الافتراضية لـ `timeout_ms` وهي 300,000 مللي ثانية (5 دقائق) تُنهي العملية. للمراقبين الذين يجب أن يعملوا حتى الإيقاف الصريح، عيّن `persistent: true` واستدعِ `TaskStop` عند الانتهاء.
- **إيقاف تلقائي عند فيضان الأحداث.** كل سطر في المخرجات القياسية رسالة محادثة. إذا كان الفلتر واسعًا جدًا وأنتج أحداثًا كثيرة جدًا، يُوقف المراقب تلقائيًا. أعد التشغيل بنمط `grep` أضيق. السطور التي تصل في غضون 200 مللي ثانية تُجمَّع في إشعار واحد.
