ورود به سیستم

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

معرفی

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

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

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

پیکربندی

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

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

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

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

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

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

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

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

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

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

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

علاوه بر این، سیاست حفظ کانال را daily می توان از طریق LOG_DAILY_DAYS متغیر محیطی یا با تنظیم days گزینه پیکربندی پیکربندی کرد.

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

کانال به گزینه های پیکربندی papertrail نیاز دارد . اینها ممکن است از طریق متغیرهای محیطی و محیطی تعریف شوند . می توانید این مقادیر را از Papertrail بدست آورید . host port PAPERTRAIL_URL PAPERTRAIL_PORT

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

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

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

اخطارهای انحراف گزارش

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

'deprecations' => [
    'channel' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),
    'trace' => env('LOG_DEPRECATIONS_TRACE', false),
],
 
'channels' => [
    // ...
]

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

'channels' => [
    'deprecations' => [
        'driver' => 'single',
        'path' => storage_path('logs/php-deprecation-warnings.log'),
    ],
],

ساخت پشته سیاهههای مربوط

همانطور که قبلا ذکر شد، stack درایور به شما امکان می دهد چندین کانال را در یک کانال ورود به سیستم برای راحتی ترکیب کنید. برای نشان دادن نحوه استفاده از پشته‌های گزارش، اجازه دهید نگاهی به پیکربندی مثالی بیندازیم که ممکن است در یک برنامه تولیدی مشاهده کنید:

'channels' => [
    'stack' => [
        'driver' => 'stack',
        'channels' => ['syslog', 'slack'], 
        'ignore_exceptions' => false,
    ],
 
    'syslog' => [
        'driver' => 'syslog',
        'level' => env('LOG_LEVEL', 'debug'),
        'facility' => env('LOG_SYSLOG_FACILITY', LOG_USER),
        'replace_placeholders' => true,
    ],
 
    'slack' => [
        'driver' => 'slack',
        'url' => env('LOG_SLACK_WEBHOOK_URL'),
        'username' => env('LOG_SLACK_USERNAME', 'Laravel Log'),
        'emoji' => env('LOG_SLACK_EMOJI', ':boom:'),
        'level' => env('LOG_LEVEL', 'critical'),
        'replace_placeholders' => true,
    ],
],

بیایید این پیکربندی را تشریح کنیم. ابتدا توجه داشته باشید که 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;
use Illuminate\View\View;
 
class UserController extends Controller
{
    /**
     * Show the profile for the given user.
     */
    public function show(string $id): View
    {
        Log::info('Showing the user profile for user: {id}', ['id' => $id]);
 
        return view('user.profile', [
            'user' => User::findOrFail($id)
        ]);
    }
}

اطلاعات متنی

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

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

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

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

اگر می‌خواهید اطلاعات متنی را در تمام کانال‌های گزارش به اشتراک بگذارید، می‌توانید از Log::shareContext() روش استفاده کنید. این روش اطلاعات متنی را برای همه کانال های ایجاد شده و هر کانالی که متعاقبا ایجاد می شود ارائه می دهد:

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

اگر در حین پردازش مشاغل در صف نیاز به اشتراک‌گذاری زمینه گزارش دارید، می‌توانید از میان‌افزار job استفاده کنید .

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

گاهی اوقات ممکن است بخواهید پیامی را به کانالی غیر از کانال پیش فرض برنامه خود وارد کنید. می توانید از 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' => env('LOG_LEVEL', 'debug'),
    'replace_placeholders' => true,
],

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

<?php
 
namespace App\Logging;
 
use Illuminate\Log\Logger;
use Monolog\Formatter\LineFormatter;
 
class CustomizeFormatter
{
    /**
     * Customize the given logger instance.
     */
    public function __invoke(Logger $logger): void
    {
        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 همچنین می تواند پیام ها را قبل از ورود به سیستم پردازش کند. شما می توانید پردازنده های خود را ایجاد کنید یا از پردازنده های موجود ارائه شده توسط Monolog استفاده کنید .

اگر می‌خواهید پردازنده‌ها را برای یک monolog درایور سفارشی کنید، یک processors مقدار پیکربندی به پیکربندی کانال خود اضافه کنید:

'memory' => [
    'driver' => 'monolog',
    'handler' => Monolog\Handler\StreamHandler::class,
    'with' => [
        'stream' => 'php://stderr',
    ],
    'processors' => [
        // Simple syntax...
        Monolog\Processor\MemoryUsageProcessor::class,
 
        // With options...
        [
           'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
           'with' => ['removeUsedContextFields' => true],
       ],
    ],
],

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

اگر می خواهید یک کانال کاملاً سفارشی تعریف کنید که در آن کنترل کاملی بر نمونه سازی و پیکربندی 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.
     */
    public function __invoke(array $config): Logger
    {
        return new Logger(/* ... */);
    }
}

دنبال کردن پیام های گزارش با استفاده از Pail

اغلب ممکن است لازم باشد لاگ های برنامه خود را در زمان واقعی دنبال کنید. به عنوان مثال، هنگام اشکال زدایی یک مشکل یا هنگام نظارت بر گزارش های برنامه خود برای انواع خاصی از خطاها.

Laravel Pail بسته ای است که به شما امکان می دهد به راحتی مستقیماً از خط فرمان وارد فایل های لاگ برنامه لاراول خود شوید. برخلاف دستور استاندارد tail ، Pail برای کار با هر درایور لاگ از جمله Sentry یا Flare طراحی شده است. علاوه بر این، Pail مجموعه ای از فیلترهای مفید را برای کمک به شما در یافتن سریع آنچه به دنبال آن هستید ارائه می دهد.

نصب و راه اندازی

Laravel Pail به PHP 8.2+ و پسوند PCNTL نیاز دارد .

برای شروع، Pail را با استفاده از مدیریت بسته Composer در پروژه خود نصب کنید:

composer require laravel/pail

استفاده

برای شروع tailing log ها، pail دستور زیر را اجرا کنید:

php artisan pail

برای افزایش پرحرفی خروجی و جلوگیری از کوتاه شدن (...)، از -v گزینه استفاده کنید:

php artisan pail -v

برای حداکثر پرحرفی و نمایش ردپای پشته استثنایی، از -vv گزینه استفاده کنید:

php artisan pail -vv

برای توقف سیاهههای مربوط به دنباله، Ctrl+C هر زمان که بخواهید فشار دهید.

فیلتر کردن سیاههها

--filter

می توانید از --filter گزینه فیلتر کردن گزارش ها بر اساس نوع، فایل، پیام و محتوای ردیابی پشته استفاده کنید:

php artisan pail --filter="QueryException"

--message

برای فیلتر کردن گزارش‌ها فقط بر اساس پیام آنها، می‌توانید از این --message گزینه استفاده کنید:

php artisan pail --message="User created"

--level

این --level گزینه ممکن است برای فیلتر کردن گزارش ها بر اساس سطح گزارش آنها استفاده شود :

php artisan pail --level=error

--user

فقط برای نمایش گزارش‌هایی که در زمانی که یک کاربر مشخص شده است نوشته شده‌اند، می‌توانید شناسه کاربر را برای این --user گزینه ارائه کنید:

php artisan pail --user=1