مفاهیم پایه ای لاراول 7 - Logging

مقدمه

این مقاله از آموزش laravel، به مفاهیم logging پرداخته است. برای کمک به یادگیری بیشتر در مورد آنچه در برنامه شما اتفاق می افتد ، لاراول سرویس logging قوی را ارائه می دهد که به شما امکان log messages ، system error log را می دهد.

 laravel از کتابخانه Monolog استفاده می کند ، که پشتیبانی از انواع log handler قدرتمند را فراهم می کند. لاراول این امکان را برای پیکربندی این handler ها فراهم می کند ، به شما امکان می دهد آنها را با هم ترکیب کرده و log handling برنامه خود را شخصی سازی کنید.

پیکربندی

تمام پیکربندی های سیستم logging برنامه شما در فایل config/logging.php قرار دارد. این فایل به شما امکان می دهد کانال های log برنامه خود را پیکربندی کنید ، بنابراین مطمئن شوید که هر یک از کانال های موجود و گزینه های آنها را بررسی کنید. در ادامه چند گزینه معمول را بررسی خواهیم کرد.

به طور پیش فرض ، لاراول هنگام  logging messages از کانال stack استفاده می کند. stack channel برای جمع آوری چندین کانال log در یک کانال واحد استفاده می شود.

پیکربندی Channel Name

به طور پیش فرض ، Monolog با "channel name" سازگار است که با محیط فعلی ، مانند production یا local مطابقت دارد. برای تغییر این مقدار ، یک گزینهname به پیکربندی کانال خود اضافه کنید:

'stack' => [
        'driver' => 'stack',
        'name' => 'channel-name',
        'channels' => ['single', 'slack'],
    ],

 Channel Driver های موجود

 

پیکربندی کانالهای Single و Daily

کانال های single و daily دارای سه گزینه پیکربندی اختیاری هستند: bubble ،permission و locking.

پیکربندی کانال Papertrail 

کانال papertrail به گزینه های پیکربندی url و port نیاز دارد. می توانید این مقادیر را از Papertrail بدست آورید.

پیکربندی کانال Slack 

کانال slack به گزینه پیکربندی url نیاز دارد. این URL باید با URL مربوط به incoming webhook که برای تیم Slack پیکربندی کرده اید مطابقت داشته باشد. به طور پیش فرض ، Slack فقط log ها را در سطح critical و بالاتر دریافت می کند. با این حال ، می توانید این را در فایل پیکربندی logging خود تنظیم کنید.

 ایجاد Log Stacks

همانطور که قبلا گفته شد ، stack driverبه شما امکان می دهد چندین کانال را در یک log channel ترکیب کنید. برای نشان دادن چگونگی استفاده از log stack ها ، بیایید نگاهی به یک نمونه پیکربندی بندازیم که ممکن است در یک برنامه مشاهده کنید:

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

بیایید این پیکربندی را بررسی کنیم.توجه کنید که کانال stack ما از طریق گزینه channels خود دو کانال دیگر را جمع می کند: slack و syslog. بنابراین ، هنگام logging messages ، هر دوی این کانال ها امکان ورود به message را دارند.

سطوح Log

به گزینه پیکربندی level در تنظیمات کانال syslog و slack در مثال بالا توجه کنید. این گزینه حداقل "level" یک پیام را برایlog توسط کانال تعیین می کند. Monolog ، که سرویس logging  لاراول را تأمین می کند ، تمام سطوح log تعریف شده در RFC 5424 specification را ارائه می دهد: emergencyalertcriticalerrorwarningnotice,info و debug.

بنابراین ، تصور کنید ما با استفاده از متد debug پیامی را log می کنیم:

Log::debug('An informational message.');

با توجه به پیکربندی ما ، کانال syslog پیام را به system log می نویسد. از آنجا که error message بالاتر یا critical نیست ، به Slack ارسال نمی شود. ولی ، اگر یک emergency message وارد کنیم ، این پیام به system log و Slack ارسال می شود ، زیرا سطح emergency برای هر دو کانال بالاتر است:

Log::emergency('The system is down!');

نوشتن Log Messages

شما می توانید با استفاده از Log facade اطلاعاتی را در log ها بنویسید. همانطور که قبلا ذکر شد ، logger  هشت logging level را که در RFC 5424 specification تعریف شده فراهم می کند: emergencyalertcritical,errorwarningnoticeinfo و debug

Log::emergency($message);
    Log::alert($message);
    Log::critical($message);
    Log::error($message);
    Log::warning($message);
    Log::notice($message);
    Log::info($message);
    Log::debug($message);

بنابراین ، می توانید با یکی از این متد ها پیامی را برای سطح مربوطه log کنید. به طور پیش فرض ، message در default log channel نوشته می شود که توسط فایل config/logging.php پیکربندی شده است:

‌‌<‌‌?php
    
    namespace App\Http\Controllers;
    
    use App\Http\Controllers\Controller;
    use App\User;
    use Illuminate\Support\Facades\Log;
    
    class UserController extends Controller
    {
        /**
         * Show the profile for the given user.
         *
         * @param  int  $id
         * @return Response
         */
        public function showProfile($id)
        {
            Log::info('Showing user profile for user: '.$id);
    
            return view('user.profile', ['user' => User::findOrFail($id)]);
        }
    }

اطلاعات Contextual

آرایه ای از داده های contextua نیز می توانند با متدهای log منتقل شود. این داده های contextual با log message قالب بندی و نمایش داده می شوند:

Log::info('User failed to login.', ['id' => $user->id]);

نوشتن Specific Channels

بعضی اوقات ممکن است بخواهید پیامی را به کانال دیگری غیر از کانال پیش فرض برنامه خود log کنید. برای بازیابی و log به هر کانال تعریف شده در فایل پیکربندی خود ، می توانید از متد channel درLog facade استفاده کنید:

Log::channel('slack')->info('Something happened!');

اگر می خواهید یک on-demand logging stack متشکل از چند کانال ایجاد کنید ، می توانید از متد stack استفاده کنید:

Log::stack(['single', 'slack'])->info('Something happened!');

سفارشی سازی Monolog Channel پیشرفته

سفارشی سازی Monolog برای Channels

بعضی اوقات ممکن است به کنترل کامل نحوه پیکربندی Monolog برای یک channel موجود نیاز داشته باشید. به عنوان مثال ، ممکن است بخواهید یک پیکربندی سفارشی Monolog FormatterInterface برای channel's handler مشخص پیاده سازی کنید.

برای شروع ، یک آرایه tap روی پیکربندی کانال تعریف کنید. آرایه tap باید شامل لیستی از کلاس ها باشد که فرصتی برای سفارشی کردن (یا "tap") به نمونه Monolog پس از ایجاد داشته باشد:

'single' => [
        'driver' => 'single',
        'tap' => [App\Logging\CustomizeFormatter::class],
        'path' => storage_path('logs/laravel.log'),
        'level' => 'debug',
    ],

هنگامی که گزینه tap را در کانال خود پیکربندی کردید ،می توانید کلاسی را تنظیم کنید که نمونه Monolog شما را سفارشی کند. این کلاس فقط به یک متد واحد نیاز دارد: __invoke ، که یک نمونه Illuminate\Log\Logger را دریافت می کند. پروکسی های نمونه Illuminate\Log\Logger فراخوانی تمام متدها را به نمونه Monolog زیر می نویسد:

‌‌<‌‌?php
    
    namespace App\Logging;
    
    class CustomizeFormatter
    {
        /**
         * Customize the given logger instance.
         *
         * @param  \Illuminate\Log\Logger  $logger
         * @return void
         */
        public function __invoke($logger)
        {
            foreach ($logger->getHandlers() as $handler) {
                $handler->setFormatter(...);
            }
        }
    }

 ایجاد Monolog Handler Channels

Monolog انواع مختلفی از  available handlers را دارد. در بعضی موارد ، نوعی logger که می خواهید ایجاد کنید فقط یک درایور Monolog با نمونه ای از یک handler خاص است. این کانال ها را می توان با استفاده از درایور monolog ایجاد کرد.

هنگام استفاده از درایور monolog ، از گزینه پیکربندی handler استفاده می شود تا مشخص شود کدام کنترل کننده نمونه خواهد شد. در صورت تمایل ، هر پارامتر سازنده ای که نیاز به handler دارد ممکن است با استفاده از گزینه with configuration مشخص شود:

'logentries' => [
        'driver'  => 'monolog',
        'handler' => Monolog\Handler\SyslogUdpHandler::class,
        'with' => [
            'host' => 'my.logentries.internal.datahubhost.company.com',
            'port' => '10000',
        ],
    ],
Monolog Formatters

هنگام استفاده از درایور monolog ، از Monolog LineFormatter به عنوان فرمت پیش فرض استفاده می شود. با این حال ، شما می توانید نوع فرمت منتقل شده بهhandler  را با استفاده از formatter و formatter_with  تنظیم کنید:

'browser' => [
        'driver' => 'monolog',
        'handler' => Monolog\Handler\BrowserConsoleHandler::class,
        'formatter' => Monolog\Formatter\HtmlFormatter::class,
        'formatter_with' => [
            'dateFormat' => 'Y-m-d',
        ],
    ],

اگر از یک  Monolog handler استفاده می کنید که توانایی تهیه فرمت بندی خود را دارد ، می توانید مقدار گزینه formatter را به صورت default تنظیم کنید:

'newrelic' => [
        'driver' => 'monolog',
        'handler' => Monolog\Handler\NewRelicHandler::class,
        'formatter' => 'default',
    ],

ایجاد Channels با Factories

اگر می خواهید یک channel کاملاً سفارشی تعریف کنید که در آن کنترل کاملی بر تنظیم و پیکربندی Monolog داشته باشید ، می توانید نوع custom driver را در فایل پیکربندی config/logging.phpخود تعیین کنید. پیکربندی شما باید شامل یک گزینه via باشد تا به factory class اشاره کند که برای ایجاد Monolog instance فراخوانی خواهد شد:

'channels' => [
        'custom' => [
            'driver' => 'custom',
            'via' => App\Logging\CreateCustomLogger::class,
        ],
    ],

هنگامی که custom channelرا پیکربندی کردید ،می توانید کلاسی را ایجاد کنید که Monolog instance شما ایجاد شود. این کلاس فقط به یک متد نیاز دارد:__invoke ، که باید Monolog instance را برگرداند:

‌‌<‌‌?php
    
    namespace App\Logging;
    
    use Monolog\Logger;
    
    class CreateCustomLogger
    {
        /**
         * Create a custom Monolog instance.
         *
         * @param  array  $config
         * @return \Monolog\Logger
         */
        public function __invoke(array $config)
        {
            return new Logger(...);
        }
    }

 

امیدواریم این آموزش از مقالات آموزش لاراول برایتان مفید بوده باشد.