إتقان سجلات لارافيل: دليل شامل

مقدمة إلى تسجيل لارافيل #

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

نظام تسجيل لارافيل: Monolog والتكوين #

يستفيد نظام تسجيل لارافيل من Monolog، وهي مكتبة تسجيل PHP شائعة. هذا يعني أن لديك وصولًا إلى مجموعة واسعة من معالجات ومنسقات السجلات القوية. يقع جميع تكوينات التسجيل في config/logging.php.

جوهر تكوين تسجيل لارافيل هو مصفوفة channels. يمثل كل إدخال في هذه المصفوفة طريقة محددة يمكن لتطبيقك من خلالها تسجيل الرسائل.

// config/logging.php

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['single'],
        'ignore_exceptions' => false,
    ],

    'single' => [
        'driver' => 'single',
        'path' => storage_path('logs/laravel.log'),
        'level' => env('LOG_LEVEL', 'debug'),
    ],

    'daily' => [
        'driver' => 'daily',
        'path' => storage_path('logs/laravel.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => 14,
    ],

    'slack' => [
        'driver' => 'slack',
        'url' => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => 'Laravel Log',
        'emoji' => ':boom:',
        'level' => env('LOG_LEVEL', 'critical'),
    ],

    // ... قنوات أخرى
],

تعد قناة stack عادةً هي القناة الافتراضية (يتم تعيينها في ملف .env الخاص بك عبر LOG_CHANNEL=stack). تتيح لك دمج قنوات سجل متعددة في قناة واحدة، وإرسال رسالة سجل إلى جميع القنوات المكونة داخل الـ stack.

فهم قنوات السجل #

تأتي لارافيل مع العديد من قنوات السجل المكونة مسبقًا:

• single: يكتب جميع رسائل السجل إلى ملف واحد (storage/logs/laravel.log). مفيد للتطوير.
• daily: ينشئ ملف سجل لكل يوم (storage/logs/laravel-YYYY-MM-DD.log). يتحكم خيار days في عدد أيام ملفات السجل التي سيتم الاحتفاظ بها. هذا خيار شائع للإنتاج.
• stack: يجمع قنوات متعددة. بشكل افتراضي، يستخدم single، ولكن يمكنك تحديد أي مجموعة (على سبيل المثال، ['daily', 'slack']).
• slack: يرسل رسائل السجل إلى قناة Slack. يتطلب تكوين عنوان URL لـ Slack webhook.
• syslog: يسجل الرسائل في syslog الخاص بالنظام.
• errorlog: يسجل الرسائل في سجل أخطاء PHP.
• null: يتجاهل جميع رسائل السجل. مفيد للاختبار أو تعطيل التسجيل مؤقتًا.

يمكنك تعيين قناة السجل الافتراضية لتطبيقك في ملف .env:

LOG_CHANNEL=stack

الكتابة إلى السجلات #

يوفر واجهة Log في لارافيل طرقًا مريحة لكتابة الرسائل بمستويات خطورة مختلفة. تتوافق كل طريقة مع مستوى سجل Monolog:

• Log::emergency($message, $context = [])
• Log::alert($message, $context = [])
• Log::critical($message, $context = [])
• Log::error($message, $context = [])
• Log::warning($message, $context = [])
• Log::notice($message, $context = [])
• Log::info($message, $context = [])
• Log::debug($message, $context = [])

مثال:

use Illuminate\Support\Facades\Log;

// تسجيل رسالة معلوماتية
Log::info('المستخدم {id} سجل الدخول.', ['id' => $user->id]);

// تسجيل تحذير
Log::warning('استجابت بوابة الدفع بخطأ.', ['transaction_id' => $transaction->id]);

// تسجيل خطأ
try {
    // عملية قد تفشل
    throw new \Exception('خطأ محاكاة أثناء عملية حاسمة.');
} catch (\Exception $e) {
    Log::error('حدث خطأ غير متوقع.', ['exception' => $e]);
}

يمكنك أيضًا تحديد قناة معينة للكتابة إليها:

Log::channel('slack')->info('شخص ما وصل إلى لوحة تحكم المسؤول.');
Log::channel('daily')->debug('هذه الرسالة تذهب فقط إلى السجلات اليومية.');

البيانات السياقية #

الوسيطة الثانية لأي طريقة تسجيل هي مصفوفة من البيانات السياقية. سيتم تنسيق هذه البيانات وعرضها جنبًا إلى جنب مع رسالتك، مما يوفر مزيدًا من الرؤى دون تشتيت سلسلة الرسائل الرئيسية.

Log::info('تمت معالجة الطلب بنجاح.', [
    'order_id' => $order->id,
    'customer_email' => $order->customer->email,
    'amount' => $order->amount,
]);

تسجيل الاستثناءات #

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

try {
    // محاولة عملية خطيرة
    throw new \Exception('حدث خطأ ما أثناء تحميل الملف.');
} catch (\Exception $e) {
    Log::error('فشل تحميل الملف.', [
        'user_id' => Auth::id(),
        'exception' => $e->getMessage(),
        'trace' => $e->getTraceAsString(),
    ]);
    // اختياريًا إعادة الرمي أو التعامل بلطف
}

عند تمرير كائن Exception كبيانات سياقية، غالبًا ما يستخرج Monolog المعلومات ذات الصلة مثل الرسالة والملف والسطر.

تخصيص قنوات ومعالجات السجل #

تتيح لك لارافيل توسيع قدرات التسجيل الخاصة بها عن طريق إنشاء معالجات Monolog أو درايفرات مخصصة.

تعريف قناة مخصصة

يمكنك تعريف قناة مخصصة جديدة في config/logging.php:

'channels' => [
    // ...
    'custom_logger' => [
        'driver' => 'custom',
        'via' => App\Logging\CustomLogger::class,
    ],
],

ثم، أنشئ الفئة App\Logging\CustomLogger (على سبيل المثال، في app/Logging/CustomLogger.php):

<?php

namespace App\Logging;

use Monolog\Logger;
use Monolog\Handler\StreamHandler;

class CustomLogger
{
    /**
     * تخصيص مثيل المسجل المعطى.
     *
     * @param  \Illuminate\Log\Logger  $logger
     * @return void
     */
    public function __invoke(Logger $logger)
    {
        // إزالة المعالجات الافتراضية إذا كنت تريد التحكم الكامل
        foreach ($logger->getHandlers() as $handler) {
            $logger->popHandler();
        }

        $logger->pushHandler(new StreamHandler(storage_path('logs/custom.log'), Logger::DEBUG));
        $logger->pushHandler(new StreamHandler('php://stdout', Logger::INFO)); // مثال: سجل إلى وحدة التحكم
    }
}

الآن يمكنك استخدام Log::channel('custom_logger')->info('هذا يذهب إلى custom.log و stdout');.

تخصيص القنوات الموجودة (المعالجات)

يدعم Monolog أيضًا المعالجات (processors)، والتي يمكنها إضافة بيانات إضافية إلى سجلات السجل قبل إرسالها إلى المعالجات (handlers). تسهل لارافيل إضافة المعالجات إلى قنواتك.

// config/logging.php
'channels' => [
    'daily' => [
        'driver' => 'daily',
        'path' => storage_path('logs/laravel.log'),
        'level' => env('LOG_LEVEL', 'debug'),
        'days' => 14,
        'processors' => [
            \Monolog\Processor\PsrLogMessageProcessor::class,
            \Monolog\Processor\WebProcessor::class, // يضيف URL, IP, method, إلخ.
        ],
    ],
],

مراقبة السجلات #

بالنسبة لتطبيقات الإنتاج، مجرد كتابة السجلات لا يكفي. تحتاج إلى مراقبتها.

• التطوير المحلي: استخدم tail -f storage/logs/laravel.log في طرفيتك لمشاهدة السجلات في الوقت الفعلي.
• الإنتاج: فكر في استخدام خدمات إدارة السجلات مثل AWS CloudWatch أو Papertrail أو Logtail أو Sentry. توفر العديد من هذه الخدمات معالجات Monolog التي يمكنك دمجها في تطبيق لارافيل الخاص بك.

أفضل الممارسات للتسجيل #

• تسجيل معلومات ذات معنى: لا تسجل فقط "لقد نجح" أو "حدث خطأ". قدم سياقًا.
• استخدم مستويات السجل المناسبة: فرق بين debug، info، warning، و error.
  • DEBUG: معلومات مفصلة للتطوير وتصحيح الأخطاء.
  • INFO: أحداث مهمة، تشغيل عادي.
  • NOTICE: أحداث عادية ولكنها مهمة.
  • WARNING: أحداث استثنائية ليست أخطاء (مثل استخدام واجهة برمجة تطبيقات مهملة، فشل غير حرج).
  • ERROR: أخطاء وقت التشغيل التي لا تتطلب إجراءً فوريًا ولكن يجب عادةً تسجيلها ومراقبتها.
  • CRITICAL: ظروف حرجة (مثل مكون التطبيق غير متاح، استثناء غير متوقع).
  • ALERT: يجب اتخاذ إجراء فوري (مثل تعطل موقع الويب بالكامل، قاعدة البيانات غير متاحة).
  • EMERGENCY: النظام غير قابل للاستخدام.
• تجنب تسجيل البيانات الحساسة: لا تسجل أبدًا كلمات المرور أو مفاتيح API أو معلومات المستخدم الأخرى شديدة الحساسية مباشرةً. إذا كان يجب عليك تسجيل بيانات حساسة لأغراض تصحيح الأخطاء، فتأكد من أنها تم تعديلها بشدة أو تشفيرها، ولفترات قصيرة جدًا فقط تحت ضوابط وصول صارمة.
• مركزية السجلات: في بيئات متعددة الخوادم، قم بمركزية سجلاتك لتسهيل المراقبة والتحليل.
• تنبيهات تلقائية: قم بتكوين تنبيهات لسجلات المستويات الحرجة والأخطاء لإعلامك فورًا بالمشكلات.

الخلاصة #

يعد نظام تسجيل لارافيل، المدعوم من Monolog، أداة قوية بشكل لا يصدق لفهم تطبيقاتك وصيانتها. من خلال إتقان تكوينها وقنواتها وأفضل الممارسات، يمكنك تحسين قدرتك بشكل كبير على تصحيح الأخطاء ومراقبة صحة التطبيق وضمان تجربة مستخدم سلسة. قم بدمج التسجيل القوي في سير عمل التطوير الخاص بك من اليوم الأول، وسيشكرك مستقبلك.