جمع السجلات

عند تقديم تقرير خلل، توفر حزمة السجلات للمشرفين المعلومات التي يحتاجونها لتشخيص المشكلة دون الذهاب والعودة لطلب تفاصيل.

حزمة سريعة

أسرع طريقة لإنشاء حزمة سجلات:

triggerfish logs bundle

ينشئ هذا أرشيفاً يحتوي على جميع ملفات السجلات من ~/.triggerfish/logs/:

• Linux/macOS: triggerfish-logs.tar.gz
• Windows: triggerfish-logs.zip

إذا فشلت عملية الأرشفة لأي سبب، يعود إلى نسخ ملفات السجل الخام إلى مجلد يمكنك ضغطه يدوياً.

ما تحتويه الحزمة

• triggerfish.log (ملف السجل الحالي)
• triggerfish.1.log إلى triggerfish.10.log (النسخ الاحتياطية المُدوَّرة، إن وُجدت)

الحزمة لا تحتوي على:

• ملف التكوين triggerfish.yaml
• المفاتيح السرية أو بيانات الاعتماد
• قاعدة بيانات SQLite
• SPINE.md أو TRIGGER.md

جمع السجلات يدوياً

إذا لم يكن أمر الحزمة متاحاً (إصدار قديم، Docker، إلخ):

# اعثر على ملفات السجلات
ls ~/.triggerfish/logs/

# أنشئ أرشيفاً يدوياً
tar czf triggerfish-logs.tar.gz ~/.triggerfish/logs/

# Docker
docker cp triggerfish:/data/logs/ ./triggerfish-logs/
tar czf triggerfish-logs.tar.gz triggerfish-logs/

زيادة تفاصيل السجل

افتراضياً، السجلات على مستوى INFO. لالتقاط مزيد من التفاصيل لتقرير خلل:

1. اضبط مستوى السجل على verbose أو debug:

   triggerfish config set logging.level verbose
   # أو لأقصى تفاصيل:
   triggerfish config set logging.level debug

2. أعد إنتاج المشكلة

3. اجمع الحزمة:

   triggerfish logs bundle

4. أعد المستوى إلى normal:

   triggerfish config set logging.level normal

تفاصيل مستويات السجل

المستوى	ما يلتقطه
quiet	الأخطاء فقط
normal	الأخطاء والتحذيرات والمعلومات (الافتراضي)
verbose	يضيف رسائل التصحيح (استدعاءات الأدوات، تفاعلات المزود، قرارات التصنيف)
debug	كل شيء بما في ذلك رسائل مستوى التتبع (بيانات البروتوكول الخام، تغييرات الحالة الداخلية)

تحذير: مستوى debug يُنتج الكثير من المخرجات. استخدمه فقط عند إعادة إنتاج مشكلة بنشاط، ثم عُد.

تصفية السجلات في الوقت الفعلي

أثناء إعادة إنتاج مشكلة، يمكنك تصفية تدفق السجل المباشر:

# عرض الأخطاء فقط
triggerfish logs --level ERROR

# عرض التحذيرات وما فوق
triggerfish logs --level WARN

على Linux/macOS، يستخدم هذا tail -f الأصلي مع التصفية. على Windows، يستخدم PowerShell Get-Content -Wait -Tail.

تنسيق السجل

كل سطر سجل يتبع هذا التنسيق:

[2026-02-17T14:30:45.123Z] [INFO] [gateway] Gateway WebSocket server started on port 18789

• الطابع الزمني: ISO 8601 بتوقيت UTC
• المستوى: ERROR، WARN، INFO، DEBUG، أو TRACE
• المكوّن: أي وحدة أنشأت السجل (مثل gateway، anthropic، telegram، policy)
• الرسالة: رسالة السجل مع سياق منظّم

ما يجب تضمينه في تقرير الخلل

مع حزمة السجلات، ضمّن:

1. خطوات إعادة الإنتاج. ماذا كنت تفعل عند حدوث المشكلة؟
2. السلوك المتوقع. ماذا كان يجب أن يحدث؟
3. السلوك الفعلي. ماذا حدث بدلاً من ذلك؟
4. معلومات المنصة. نظام التشغيل، المعمارية، إصدار Triggerfish (triggerfish version)
5. مقتطف التكوين. القسم ذو الصلة من triggerfish.yaml (احجب الأسرار)

راجع تقديم البلاغات للقائمة الكاملة.

المعلومات الحساسة في السجلات

ينظّف Triggerfish البيانات الخارجية في السجلات بتغليف القيم بفاصلات << و>>. يجب ألا تظهر مفاتيح API والرموز في مخرجات السجل. لكن قبل إرسال حزمة سجلات:

1. امسح بحثاً عن أي شيء لا تريد مشاركته (عناوين بريد إلكتروني، مسارات ملفات، محتوى رسائل)
2. احجب ما يلزم
3. أشر في بلاغك أن الحزمة تم حجبها

تحتوي ملفات السجلات على محتوى الرسائل من محادثاتك. إذا كانت محادثاتك تحتوي على معلومات حساسة، احجب تلك الأجزاء قبل المشاركة.