ورود به سیستم

• معرفی
• پیکربندی
  • درایورهای کانال موجود
  • پیش نیاز کانال
  • اخطارهای منسوخ شدن ثبت گزارش
• ساخت پشته سیاهههای مربوط
• نوشتن پیام های گزارش
  • اطلاعات متنی
  • نوشتن در کانال های خاص
• سفارشی سازی کانال مونولوگ
  • سفارشی سازی Monolog برای کانال ها
  • ایجاد کانال های مونولوگ Handler
  • ایجاد کانال های سفارشی از طریق کارخانه ها

معرفی

برای کمک به کسب اطلاعات بیشتر در مورد آنچه در برنامه شما اتفاق می افتد، لاراول خدمات گزارش گیری قوی ارائه می دهد که به شما امکان می دهد پیام ها را در فایل ها، گزارش خطای سیستم و حتی به Slack ثبت کنید تا به کل تیم خود اطلاع دهید.

لاگ لاراول بر اساس "کانال ها" است. هر کانال نشان دهنده روش خاصی برای نوشتن اطلاعات گزارش است. به عنوان مثال، single کانال فایل های گزارش را در یک فایل گزارش می نویسد، در حالی که slack کانال پیام های گزارش را برای Slack ارسال می کند. پیام های گزارش ممکن است بر اساس شدت آنها در چندین کانال نوشته شوند.

لاراول در زیر هود از کتابخانه Monolog استفاده می کند که از انواع کنترل کننده های لاگ قدرتمند پشتیبانی می کند. لاراول پیکربندی این دسته‌ها را سخت می‌کند و به شما این امکان را می‌دهد که آنها را ترکیب و مطابقت دهید تا مدیریت گزارش برنامه خود را سفارشی کنید.

پیکربندی

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

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

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

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

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

درایورهای کانال موجود

هر کانال ورود به سیستم توسط یک "درایور" تغذیه می شود. درایور تعیین می کند که پیام گزارش چگونه و کجا واقعاً ضبط شود. درایورهای کانال لاگ زیر در هر برنامه لاراول موجود است. ورودی بیشتر این درایورها از قبل در config/logging.php فایل پیکربندی برنامه شما وجود دارد، بنابراین حتماً این فایل را مرور کنید تا با محتویات آن آشنا شوید:

برای کسب اطلاعات بیشتر در مورد و درایورها ، اسناد مربوط به سفارشی سازی کانال پیشرفته را بررسی کنید . monolog custom

پیش نیاز کانال

پیکربندی کانال های تک و روزانه

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

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

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

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

کانال slack به یک url گزینه پیکربندی نیاز دارد. این نشانی اینترنتی باید با URL مربوط به وب هوک ورودی که برای تیم Slack خود پیکربندی کرده اید مطابقت داشته باشد.

critical به طور پیش‌فرض، Slack فقط گزارش‌ها را در سطح و بالاتر دریافت می‌کند . با این حال، می توانید config/logging.php با تغییر level گزینه پیکربندی در آرایه پیکربندی کانال Slack log خود، این را در فایل پیکربندی خود تنظیم کنید.

اخطارهای منسوخ شدن ثبت گزارش

PHP، لاراول و سایر کتابخانه ها اغلب به کاربران خود اطلاع می دهند که برخی از ویژگی های آنها منسوخ شده است و در نسخه های بعدی حذف خواهند شد. اگر می‌خواهید این هشدارهای منسوخ شدن را ثبت کنید، می‌توانید کانال گزارش مورد نظر خود را در فایل پیکربندی deprecations برنامه خود مشخص کنید: config/logging.php

'deprecations' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
 
'channels' => [
    ...
]

یا ممکن است یک کانال گزارش با نام تعریف کنید deprecations . اگر یک کانال گزارش با این نام وجود داشته باشد، همیشه برای ثبت موارد منسوخ استفاده می شود:

'channels' => [
    'deprecations' => [
        'driver' => 'single',
        'path' => storage_path('logs/php-deprecation-warnings.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 گزینه خود جمع می کند: syslog و slack . بنابراین، هنگام ثبت پیام‌ها، هر دوی این کانال‌ها امکان ثبت پیام را خواهند داشت. با این حال، همانطور که در زیر خواهیم دید، این که آیا این کانال‌ها واقعاً پیام را ثبت می‌کنند یا خیر، ممکن است بر اساس شدت / «سطح» پیام تعیین شود.

سطوح ورود به سیستم

level به گزینه پیکربندی موجود در پیکربندی کانال syslog و slack در مثال بالا توجه کنید . این گزینه حداقل "سطح" را تعیین می کند که یک پیام باید توسط کانال ثبت شود. Monolog که خدمات لاگ لاراول را نیرو می دهد، تمام سطوح گزارش تعریف شده در مشخصات RFC 5424 را ارائه می دهد : اضطراری ، هشدار ، بحرانی ، خطا ، هشدار ، اطلاعیه ، اطلاعات و اشکال زدایی .

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

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

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

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

نوشتن پیام های گزارش

می توانید با استفاده از نما اطلاعات را در سیاهههای مربوط Log بنویسید . همانطور که قبلا ذکر شد، لاگر هشت سطح گزارش تعریف شده در مشخصات RFC 5424 را ارائه می دهد : اضطراری ، هشدار ، بحرانی ، خطا ، هشدار ، اطلاعیه ، اطلاعات و اشکال زدایی :

use Illuminate\Support\Facades\Log;
 
Log::emergency($message);
Log::alert($message);
Log::critical($message);
Log::error($message);
Log::warning($message);
Log::notice($message);
Log::info($message);
Log::debug($message);

می توانید با هر یک از این روش ها پیامی را برای سطح مربوطه ثبت کنید. به‌طور پیش‌فرض، پیام در کانال گزارش پیش‌فرض همانطور که توسط logging فایل پیکربندی شما پیکربندی شده است، نوشته می‌شود:

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

اطلاعات متنی

آرایه ای از داده های متنی ممکن است به روش های log ارسال شود. این داده‌های متنی با پیام گزارش قالب‌بندی و نمایش داده می‌شوند:

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

گاهی اوقات، ممکن است بخواهید برخی از اطلاعات متنی را مشخص کنید که باید در تمام ورودی های گزارش بعدی گنجانده شود. به عنوان مثال، ممکن است بخواهید شناسه درخواستی را وارد کنید که با هر درخواست ورودی به برنامه شما مرتبط است. برای انجام این کار، می توانید روش Log نما را فراخوانی کنید withContext :

<?php
 
namespace App\Http\Middleware;
 
use Closure;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Str;
 
class AssignRequestId
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle($request, Closure $next)
    {
        $requestId = (string) Str::uuid();
 
        Log::withContext([
            'request-id' => $requestId
        ]);
 
        return $next($request)->header('Request-Id', $requestId);
    }
}

نوشتن در کانال های خاص

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

use Illuminate\Support\Facades\Log;
 
Log::channel('slack')->info('Something happened!');

اگر می‌خواهید یک پشته گزارش بر اساس درخواست متشکل از چندین کانال ایجاد کنید، می‌توانید از stack روش زیر استفاده کنید:

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

کانال های درخواستی

همچنین می توان با ارائه پیکربندی در زمان اجرا، بدون اینکه آن پیکربندی در فایل پیکربندی برنامه شما وجود داشته باشد، یک کانال درخواستی ایجاد کرد logging . برای انجام این کار، می توانید یک آرایه پیکربندی را به روش Log نما ارسال کنید build :

use Illuminate\Support\Facades\Log;
 
Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
])->info('Something happened!');

همچنین ممکن است بخواهید یک کانال بر اساس تقاضا را در یک پشته گزارش بر اساس تقاضا قرار دهید. این را می توان با گنجاندن نمونه کانال درخواستی خود در آرایه ارسال شده به stack متد به دست آورد:

use Illuminate\Support\Facades\Log;
 
$channel = Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
]);
 
Log::stack(['slack', $channel])->info('Something happened!');

سفارشی سازی کانال مونولوگ

سفارشی سازی Monolog برای کانال ها

گاهی اوقات ممکن است نیاز به کنترل کامل روی نحوه پیکربندی Monolog برای یک کانال موجود داشته باشید. برای مثال، ممکن است بخواهید یک FormatterInterface پیاده سازی سفارشی Monolog را برای کانال داخلی لاراول پیکربندی کنید single .

برای شروع، یک 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;
 
use Monolog\Formatter\LineFormatter;
 
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(new LineFormatter(
                '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
            ));
        }
    }
}

همه کلاس‌های "tap" شما توسط کانتینر سرویس حل می‌شوند ، بنابراین هر وابستگی سازنده که نیاز دارند به طور خودکار تزریق می‌شود.

ایجاد کانال های مونولوگ Handler

Monolog هندلرهای متنوعی دارد و لاراول برای هر کدام یک کانال داخلی در نظر نمی گیرد. در برخی موارد، ممکن است بخواهید یک کانال سفارشی ایجاد کنید که صرفاً نمونه‌ای از یک کنترلر خاص Monolog است که دارای درایور لاگ لاراول مربوطه نیست. این کانال ها را می توان به راحتی با استفاده از monolog درایور ایجاد کرد.

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

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

قالب‌های مونولوگ

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

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

اگر از یک کنترل کننده Monolog استفاده می کنید که قادر به ارائه فرمت کننده خود است، می توانید مقدار formatter گزینه پیکربندی را روی default :

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

ایجاد کانال های سفارشی از طریق کارخانه ها

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

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

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

<?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(...);
    }
}