Basics - 12. Logging

Configuring The Channel Name

Standardmäßig wird Monolog mit einem "Kanalnamen" instanziiert, der der aktuellen Umgebung, wie z.B. produktion oder local, entspricht. Um diesen Wert zu ändern, fügen Sie der Konfiguration Ihres Kanals eine name-Option hinzu:

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

Available Channel Drivers

Configuring The Single and Daily Channels

Die The Single and Daily Channels verfügen über drei optionale Konfigurationsoptionen: bubble, permission, and locking.

Configuring The Papertrail Channel

Der Papertrail-Kanal benötigt die Konfigurationsoptionen URL und Port. Diese Werte erhalten Sie bei Papertrail.

Configuring The Slack Channel

Der Slack-Kanal erfordert eine Option zur URL-Konfiguration. Diese URL sollte mit einer URL für einen eingehenden Webhook übereinstimmen, den Sie für Ihr Slack-Team konfiguriert haben.

Building Log Stacks

Wie bereits erwähnt, ermöglicht der stack-Driver die Kombination mehrerer Kanäle zu einem einzigen Protokollkanal. Um zu veranschaulichen, wie man Log-Stacks verwendet, werfen wir einen Blick auf eine exemplarische Konfiguration, die Sie möglicherweise in einer Produktionsanwendung sehen:

'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',
    ],
],

Lasst uns diese Konfiguration zerlegen. Erstens, beachten Sie, dass unser stack channel über seine Kanaloption zwei weitere Kanäle aggregiert: syslog und slack. Wenn Sie also Nachrichten protokollieren, haben diese beiden Kanäle die Möglichkeit, die Nachricht zu protokollieren.

Log Levels

Beachten Sie die Option zur Konfiguration der Ebenen, die in den Konfigurationen Syslog und Slack Channel im obigen Beispiel vorhanden ist. Diese Option bestimmt den minimalen "Pegel", den eine Nachricht haben muss, um vom Kanal protokolliert zu werden. Monolog, das die Protokollierungsdienste von Laravel betreibt, bietet alle in der RFC 5424-Spezifikation definierten Protokollebenen: emergency, alert, critical, error, warning, notice, info, and debug.

Stellen Sie sich also vor, wir protokollieren eine Meldung mit der debug-Methode:

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

In unserer Konfiguration schreibt der Syslog-Kanal die Nachricht in das Systemprotokoll; da die Fehlermeldung jedoch nicht kritisch oder höher ist, wird sie nicht an Slack gesendet. Wenn wir jedoch eine Notfallmeldung (emergency message) protokollieren, wird sie sowohl an das Systemprotokoll als auch an Slack gesendet, da der Notpegel (emergency level) für beide Kanäle über unserem Mindestpegel liegt:

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

Writing Log Messages

Sie können über die Log Facade Informationen in die Protokolle schreiben. Wie bereits erwähnt, stellt der Logger die acht in der RFC 5424-Spezifikation definierten Protokollierungsstufen zur Verfügung: emergency, alert, critical, error, warning, notice, info and 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);

Sie können also jede dieser Methoden aufrufen, um eine Nachricht für die entsprechende Ebene zu protokollieren. Standardmäßig wird die Nachricht in den Standardprotokollkanal geschrieben, wie er in Ihrer Konfigurationsdatei config/logging.php konfiguriert ist:

<?php

namespace App\Http\Controllers;

use App\User;
use Illuminate\Support\Facades\Log;
use App\Http\Controllers\Controller;

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 Information

Eine Reihe von Kontextdaten kann auch an die Protokollmethoden übergeben werden. Diese Kontextdaten werden formatiert und mit der Logmeldung angezeigt:

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

Writing To Specific Channels

Manchmal möchten Sie eine Nachricht auf einem anderen Kanal als dem Standardkanal Ihrer Anwendung protokollieren. Sie können die channel-Methode auf der log-Facade verwenden, um jeden in Ihrer Konfigurationsdatei definierten Kanal abzurufen und zu protokollieren:

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

Wenn Sie einen On-Demand-Protokollierungsstapel erstellen möchten, der aus mehreren Kanälen besteht, können Sie die stack-Methode verwenden:

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

Advanced Monolog Channel Customization

Customizing Monolog For Channels

Manchmal benötigen Sie die vollständige Kontrolle darüber, wie Monolog für einen bestehenden Kanal konfiguriert ist. Beispielsweise können Sie eine benutzerdefinierte Monolog FormatterInterface-Implementierung für die Handler eines bestimmten Kanals konfigurieren.

Um zu beginnen, definieren Sie ein tap-Array in der Konfiguration des Kanals. Das tap-Array sollte eine Liste von Klassen enthalten, die die Möglichkeit haben sollten, die Monolog-Instanz nach ihrer Erstellung anzupassen (oder "anzutippen"):

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

Sobald Sie die tap-Option auf Ihrem Kanal konfiguriert haben, können Sie die Klasse definieren, die Ihre Monolog-Instanz anpassen soll. Diese Klasse benötigt nur eine einzige Methode: __invoke Aufruf, der eine Illuminate\Log\Logger-Instanz empfängt. Die Illuminate\Log\Logger-Instanz proxiert alle Methodenaufrufe an die zugrunde liegende Monolog-Instanz:

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

Creating Monolog Handler Channels

Monolog hat eine Vielzahl von verfügbaren Handlern. In einigen Fällen ist der Typ des Loggers, den Sie erstellen möchten, lediglich ein monolog-Driver mit einer Instanz eines bestimmten Handlers. Diese Kanäle können mit dem monolog-Driver erstellt werden.

Bei Verwendung des monolog-Driver wird mit der Option handler-Konfiguration angegeben, welcher Handler instanziiert werden soll. Optional können alle Konstruktorparameter, die der Handler benötigt, mit der Option with configuration angegeben werden:

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

Monolog Formatters

Bei Verwendung des monolog-Driver wird der Monolog LineFormatter als Standardformatierer verwendet. Sie können jedoch den Typ des Formats, der an den Handler übergeben wird, mit Hilfe von Formatter und Formatter_with configuration options anpassen:

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

Wenn Sie einen Monolog-Handler verwenden, der in der Lage ist, einen eigenen Formatierer bereitzustellen, können Sie den Wert der Option Format-Konfiguration auf Standard (default) setzen:

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

Creating Channels Via Factories

Wenn Sie einen vollständig benutzerdefinierten Kanal definieren möchten, in dem Sie die volle Kontrolle über die Instanziierung und Konfiguration von Monolog haben, können Sie in Ihrer Konfigurationsdatei config/logging.php einen custom-Driver angeben. Ihre Konfiguration sollte eine via-Option enthalten, um auf die Factory-Klasse zu verweisen, die aufgerufen wird, um die Monolog-Instanz zu erstellen:

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

Sobald Sie den benutzerdefinierten Kanal (custom channel) konfiguriert haben, können Sie die Klasse definieren, die Ihre Monolog-Instanz erstellen soll. Diese Klasse benötigt nur eine einzige Methode: __invoke, der die Monolog-Instanz zurückgeben soll:

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