Laravel 13.30 يوضح سبب توقف queue worker في مخرجات queue:work
أضاف Laravel 13.30 سطراً يبيّن سبب توقف queue worker عند تشغيل الأمر queue:work. وتظهر المعلومة كنص عادي، أو كسجل JSON منظم مع خيار --json، ما يساعد فرق التشغيل على التمييز بين التوقف الطبيعي ومشكلات مثل تجاوز حد الذاكرة أو إعادة تشغيل العامل أثناء النشر.
أبرز النقاط
- يعرض Laravel 13.30 سبب توقف queue worker في السطر الأخير من مخرجات queue:work.
- يدعم الخيار --json سجلاً منظماً يتضمن reason وexit_code وjobs_processed واستهلاك الذاكرة.
- قيمة reason ثابتة وقابلة للاعتماد عليها في الفلترة ضمن سجلات التشغيل.
- لا تظهر المعلومة مع --quiet و--silent، ولا عند قتل العملية خارجياً مثل SIGKILL أو OOM killer.
- يمكن استخدام حدث WorkerStopping لإرسال أسباب التوقف إلى لوحات المراقبة أو أنظمة metrics.
كان من الممكن أن يتوقف queue:work في Laravel لأسباب متعددة، لكن مخرجات الطرفية كانت تبدو متشابهة قبل Laravel 13.30. لذلك، عندما يعيد Supervisor تشغيل worker باستمرار، لم يكن من السهل معرفة ما إذا كان السبب حد الذاكرة أو فقدان اتصال قاعدة البيانات أو تنفيذ queue:restart ضمن عملية نشر.
في Laravel 13.30، يطبع الأمر سبب التوقف في السطر الأخير من مخرجاته، بصيغة مقروءة مثل:
2026-09-01 13:20:40 Worker STOPPED Memory limit exceeded
سجل JSON مناسب للـ log pipelines
عند استخدام الخيار --json، يظهر التوقف كسجل JSON منظم بجانب سجلات معالجة الوظائف. يتضمن السجل حقولاً منها status وreason وexit_code وjobs_processed وmemory وtimestamp.
{"level":"info","status":"stopped","reason":"empty","exit_code":0,"jobs_processed":12,"memory":34.0,"timestamp":"2026-09-01T13:20:40.118273+00:00"}
قيمة reason هي القيمة الثابتة من enum WorkerStopReason، ما يجعل الاعتماد عليها في الفلترة أو التحليل أكثر استقراراً. ويكون memory بالميغابايت مع تقريب إلى منزلة عشرية واحدة، أو null عندما لا يسجل العامل قيمة للذاكرة. أما level فيكون info عند رمز خروج 0، وwarning لبقية رموز الخروج.
يمكن مثلاً استخراج سجلات التوقف من المخرجات بهذه الطريقة:
php artisan queue:work --json --max-time=3600 2>&1 | jq -c 'select(.status == "stopped")'
لن يظهر سطر التوقف عند استخدام --quiet أو --silent، ولا عندما تكون قيمة السبب null. كذلك، إذا قُتل الـ worker خارجياً، مثل SIGKILL أو عبر OOM killer، فلن يتمكن Laravel من تنفيذ الحدث المسؤول عن تسجيل السبب، وبالتالي يبقى هذا النوع من الخروج بلا مخرجات إضافية.
الحدث WorkerStopping ما زال متاحاً للتخصيص
يظل حدث WorkerStopping الخيار المناسب عندما تحتاج إلى أكثر من قراءة السجل. فهو يحمل السبب وحالة الخروج وعدد الوظائف المعالجة ووقت آخر job واستهلاك الذاكرة عند توقف الـ worker.
يمكن استخدامه لتجميع عدد مرات التوقف حسب السبب في لوحة مراقبة، أو لإرسال هذه البيانات إلى نظام metrics. أضاف المساهم Jack Bayliss هذا التغيير عبر Pull Request رقم #61339.
لماذا يهم؟
يسهّل التغيير تشخيص إعادة تشغيل الـ queue workers في بيئات الإنتاج دون الحاجة دائماً إلى ربط توقيت التوقف بسجلات النشر أو كتابة listener مخصص. كما أن صيغة JSON تجعل مراقبة أسباب التوقف ضمن log pipelines أبسط، مع بقاء WorkerStopping متاحاً للحالات التي تتطلب قياسات أو تنبيهات مخصصة.