دليل الرصد والمراقبة لخدمة API¶

توفر هذه الوثيقة دليلاً لإشارات الرصد والمراقبة الخاصة بخدمة API. بما أن API هي المكون المركزي للمنصة، فإن صحتها أمر بالغ الأهمية. فهم سجلاتها ومقاييسها ضروري لاستكشاف الأخطاء وإصلاحها.

1. التسجيل (Logging)¶

تستخدم خدمة API التسجيل المنظم (structured logging) لتوفير رؤية مفصلة وقابلة للاستعلام في عملياتها. تتم كتابة جميع السجلات إلى المخرج القياسي.

كيفية عرض السجلات¶

استخدم الأمر التالي لمتابعة السجلات الحية لخدمة API:

docker compose logs -f api

رسائل السجل الرئيسية¶

عند استكشاف الأخطاء، ابحث عن رسائل السجل المحددة هذه:

• "message": "payload too large"

  • المعنى: حاولت خدمة Scraper إرسال دفعة أكبر من الحد المسموح به وهو 1.5 MB.
  • الإجراء: هذا ليس خطأً حرجًا، ولكنه قد يشير إلى تكوين خاطئ في Scraper.

• "message": "conflict for external_id ..."

  • المعنى: أرسلت خدمة Scraper مقالًا موجودًا بالفعل في قاعدة البيانات ولكن بمحتوى مختلف، مما يشير إلى عدم تطابق محتمل في تجزئة المحتوى (content hash).
  • الإجراء: قد يتطلب هذا تحقيقًا يدويًا لتحديد سبب تغير المحتوى.

• Illuminate\Database\QueryException

  • المعنى: خطأ فادح يشير إلى أن API لا يمكنها الاتصال بقاعدة بيانات PostgreSQL.
  • الإجراء: هذه حادثة ذات خطورة عالية. قم بتصعيدها إلى مسؤول قاعدة البيانات على الفور.

2. المقاييس الرئيسية ولوحات المراقبة¶

تتم مراقبة أداء وصحة خدمة API من خلال مجموعة من مقاييس التطبيق ومراقبة قائمة الانتظار.

لوحة مراقبة Laravel Horizon¶

• الرابط: http://localhost/horizon (أو ما يعادله في بيئة الإنتاج)
• ما يجب مراقبته:
  • المهام الفاشلة: يعد العدد المتزايد من المهام الفاشلة المؤشر الأساسي لوجود مشكلة في مسار الجلب أو التحليل.
  • أوقات الانتظار في قائمة الانتظار: تشير أوقات الانتظار الطويلة إلى أن عمال قائمة الانتظار مثقلون أو عالقون، وقد يتطلب الأمر زيادة عدد عمليات العمال.

مقاييس Prometheus¶

بينما لم يتم بعد عرض نقطة نهاية /metrics مخصصة، يجب مراقبة المقاييس التالية عبر وسائل أخرى (مثل وحدة تحكم الدخول Nginx أو مصدر Prometheus مستقبلي لـ Laravel).

• http_requests_total{route="/api/v1/ingest/articles"}: معدل طلبات الجلب الواردة.
• http_requests_duration_seconds{route="/api/v1/ingest/articles"}: زمن استجابة نقطة نهاية الجلب.
• laravel_jobs_processed_total: العدد الإجمالي للمهام التي تمت معالجتها في الخلفية.
• laravel_jobs_failed_total: العدد الإجمالي للمهام التي فشلت في الخلفية.

3. فحوصات الصحة¶

توفر خدمة API نقطة نهاية بسيطة لفحص الصحة عبر HTTP.

• نقطة النهاية: /api/v1/health (ملاحظة: قد لا تكون هذه النقطة معروضة بشكل عام وقد لا يمكن الوصول إليها إلا من داخل شبكة Docker).
• الأمر (من حاوية أخرى):

  curl http://api/api/v1/health
  

• استجابة النجاح: استجابة 200 OK مع نص JSON بسيط.