Registro de eventos

• Introducción
• Configuración
  • Drivers de canal disponibles
  • Requisitos previos para canales
  • Registro de advertencias de desaprobación
• Construcción de pilas de registro
• Escritura de mensajes de registro
  • Información contextual
  • Escritura en canales específicos
• Personalización de canales Monolog
  • Personalización de Monolog para canales
  • Creación de canales con handlers Monolog
  • Creación de canales personalizados mediante factories
• Visualización en tiempo real de mensajes de registro con Pail
  • Instalación
  • Uso
  • Filtrado de registros

#Introducción

Para ayudarle a entender mejor lo que sucede dentro de su aplicación, Laravel ofrece servicios robustos de registro que le permiten guardar mensajes en archivos, en el registro de errores del sistema e incluso en Slack para notificar a todo su equipo.

El registro en Laravel se basa en "canales". Cada canal representa una forma específica de escribir la información del registro. Por ejemplo, el canal single escribe los registros en un solo archivo, mientras que el canal slack envía mensajes de registro a Slack. Los mensajes pueden escribirse en múltiples canales según su severidad.

Internamente, Laravel utiliza la biblioteca Monolog, que ofrece soporte para una variedad de potentes handlers de registro. Laravel facilita la configuración de estos handlers, permitiéndole combinarlos para personalizar el manejo de registros de su aplicación.

#Configuración

Todas las opciones de configuración para el comportamiento de registro de su aplicación se encuentran en el archivo config/logging.php. Este archivo le permite configurar los canales de registro de su aplicación, así que asegúrese de revisar cada canal disponible y sus opciones. A continuación, revisaremos algunas opciones comunes.

Por defecto, Laravel usará el canal stack para registrar mensajes. El canal stack se utiliza para agregar múltiples canales de registro en un solo canal. Para más información sobre cómo construir pilas, consulte la documentación a continuación.

#Configuración del nombre del canal

Por defecto, Monolog se instancia con un "nombre de canal" que coincide con el entorno actual, como production o local. Para cambiar este valor, agregue una opción name en la configuración de su canal:

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

#Drivers de canal disponibles

Cada canal de registro está impulsado por un "driver". El driver determina cómo y dónde se registra realmente el mensaje. Los siguientes drivers de canal están disponibles en todas las aplicaciones Laravel. La mayoría de estos drivers ya tienen una entrada en el archivo config/logging.php de su aplicación, así que asegúrese de revisar este archivo para familiarizarse con su contenido:

#Requisitos previos para canales

#Configuración de los canales Single y Daily

Los canales single y daily tienen tres opciones de configuración opcionales: bubble, permission y locking.

Además, la política de retención para el canal daily puede configurarse mediante la opción days:

#Configuración del canal Papertrail

El canal papertrail requiere las opciones de configuración host y port. Puede obtener estos valores en Papertrail.

#Configuración del canal Slack

El canal slack requiere una opción de configuración url. Esta URL debe coincidir con la URL de un webhook entrante que haya configurado para su equipo de Slack.

Por defecto, Slack solo recibirá registros con nivel critical o superior; sin embargo, puede ajustar esto en su archivo config/logging.php modificando la opción level dentro del arreglo de configuración del canal Slack.

#Registro de advertencias de desaprobación

PHP, Laravel y otras librerías suelen notificar a sus usuarios que algunas de sus funcionalidades han sido desaprobadas y serán eliminadas en futuras versiones. Si desea registrar estas advertencias de desaprobación, puede especificar su canal de registro preferido para deprecations en el archivo config/logging.php de su aplicación:

'deprecations' => env('LOG_DEPRECATIONS_CHANNEL', 'null'),

'channels' => [
    ...
]

O bien, puede definir un canal de registro llamado deprecations. Si existe un canal con este nombre, siempre se usará para registrar las desaprobaciones:

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

#Construcción de pilas de registro

Como se mencionó anteriormente, el driver stack le permite combinar múltiples canales en un solo canal de registro para mayor comodidad. Para ilustrar cómo usar pilas de registro, veamos un ejemplo de configuración que podría encontrar en una aplicación en producción:

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

Analicemos esta configuración. Primero, observe que nuestro canal stack agrega dos canales mediante su opción channels: syslog y slack. Por lo tanto, al registrar mensajes, ambos canales tendrán la oportunidad de registrar el mensaje. Sin embargo, como veremos a continuación, si estos canales realmente registran el mensaje puede depender de la severidad o "nivel" del mensaje.

#Niveles de registro

Tome nota de la opción level presente en las configuraciones de los canales syslog y slack en el ejemplo anterior. Esta opción determina el nivel mínimo que debe tener un mensaje para que el canal lo registre. Monolog, que impulsa los servicios de registro de Laravel, ofrece todos los niveles de registro definidos en la especificación RFC 5424. En orden descendente de severidad, estos niveles son: emergency, alert, critical, error, warning, notice, info y debug.

Entonces, imagine que registramos un mensaje usando el método debug:

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

Dada nuestra configuración, el canal syslog escribirá el mensaje en el registro del sistema; sin embargo, dado que el mensaje no es critical ni superior, no se enviará a Slack. Pero si registramos un mensaje emergency, se enviará tanto al registro del sistema como a Slack, ya que el nivel emergency está por encima del umbral mínimo para ambos canales:

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

#Escritura de mensajes de registro

Puede escribir información en los registros usando la facade Log. Como se mencionó antes, el logger proporciona los ocho niveles de registro definidos en la especificación RFC 5424: emergency, alert, critical, error, warning, notice, info y debug:

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);

Puede llamar a cualquiera de estos métodos para registrar un mensaje en el nivel correspondiente. Por defecto, el mensaje se escribirá en el canal de registro predeterminado configurado en su archivo de configuración 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
{
    /**
     * Mostrar el perfil del usuario dado.
     */
    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)
        ]);
    }
}

#Información contextual

Se puede pasar un arreglo de datos contextuales a los métodos de registro. Estos datos contextuales serán formateados y mostrados junto con el mensaje de registro:

use Illuminate\Support\Facades\Log;

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

Ocasionalmente, puede que desee especificar información contextual que se incluya en todas las entradas de registro posteriores en un canal particular. Por ejemplo, puede querer registrar un ID de solicitud asociado con cada petición entrante a su aplicación. Para lograr esto, puede llamar al método withContext de la facade Log:

<?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
{
    /**
     * Manejar una solicitud entrante.
     *
     * @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;
    }
}

Si desea compartir información contextual en todos los canales de registro, puede invocar el método Log::shareContext(). Este método proporcionará la información contextual a todos los canales creados y a cualquier canal que se cree posteriormente:

<?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
{
    /**
     * Manejar una solicitud entrante.
     *
     * @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
        ]);

        // ...
    }
}

#Escritura en canales específicos

A veces puede que desee registrar un mensaje en un canal distinto al canal predeterminado de su aplicación. Puede usar el método channel de la facade Log para obtener y registrar en cualquier canal definido en su archivo de configuración:

use Illuminate\Support\Facades\Log;

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

Si desea crear una pila de registro bajo demanda que consista en múltiples canales, puede usar el método stack:

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

#Canales bajo demanda

También es posible crear un canal bajo demanda proporcionando la configuración en tiempo de ejecución sin que esta configuración esté presente en el archivo logging de su aplicación. Para lograr esto, puede pasar un arreglo de configuración al método build de la facade Log:

use Illuminate\Support\Facades\Log;

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

También puede querer incluir un canal bajo demanda en una pila de registro bajo demanda. Esto se logra incluyendo la instancia de su canal bajo demanda en el arreglo pasado al método stack:

use Illuminate\Support\Facades\Log;

$channel = Log::build([
  'driver' => 'single',
  'path' => storage_path('logs/custom.log'),
]);

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

#Personalización de canales Monolog

#Personalización de Monolog para canales

A veces puede necesitar control total sobre cómo se configura Monolog para un canal existente. Por ejemplo, puede querer configurar una implementación personalizada de Monolog FormatterInterface para el canal single incorporado en Laravel.

Para comenzar, defina un arreglo tap en la configuración del canal. El arreglo tap debe contener una lista de clases que tengan la oportunidad de personalizar (o "intervenir") la instancia de Monolog después de que se cree. No existe una ubicación convencional para estas clases, por lo que puede crear un directorio dentro de su aplicación para contenerlas:

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

Una vez que haya configurado la opción tap en su canal, estará listo para definir la clase que personalizará su instancia de Monolog. Esta clase solo necesita un método: __invoke, que recibe una instancia de Illuminate\Log\Logger. La instancia Illuminate\Log\Logger delega todas las llamadas de método a la instancia subyacente de Monolog:

<?php

namespace App\Logging;

use Illuminate\Log\Logger;
use Monolog\Formatter\LineFormatter;

class CustomizeFormatter
{
    /**
     * Personalizar la instancia del logger dada.
     */
    public function __invoke(Logger $logger): void
    {
        foreach ($logger->getHandlers() as $handler) {
            $handler->setFormatter(new LineFormatter(
                '[%datetime%] %channel%.%level_name%: %message% %context% %extra%'
            ));
        }
    }
}

#Creación de canales con handlers Monolog

Monolog tiene una variedad de handlers disponibles y Laravel no incluye un canal incorporado para cada uno. En algunos casos, puede querer crear un canal personalizado que sea simplemente una instancia de un handler Monolog específico que no tenga un driver Laravel correspondiente. Estos canales pueden crearse fácilmente usando el driver monolog.

Al usar el driver monolog, la opción de configuración handler se usa para especificar qué handler se instanciará. Opcionalmente, cualquier parámetro del constructor que el handler necesite puede especificarse usando la opción with:

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

#Formateadores Monolog

Al usar el driver monolog, el formateador por defecto será LineFormatter de Monolog. Sin embargo, puede personalizar el tipo de formateador pasado al handler usando las opciones formatter y formatter_with:

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

Si está usando un handler Monolog que puede proporcionar su propio formateador, puede establecer el valor de la opción formatter a default:

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

#Procesadores Monolog

Monolog también puede procesar mensajes antes de registrarlos. Puede crear sus propios procesadores o usar los procesadores existentes que ofrece Monolog.

Si desea personalizar los procesadores para un driver monolog, agregue un valor processors en la configuración de su canal:

 'memory' => [
     'driver' => 'monolog',
     'handler' => Monolog\Handler\StreamHandler::class,
     'with' => [
         'stream' => 'php://stderr',
     ],
     'processors' => [
         // Sintaxis simple...
         Monolog\Processor\MemoryUsageProcessor::class,

         // Con opciones...
         [
            'processor' => Monolog\Processor\PsrLogMessageProcessor::class,
            'with' => ['removeUsedContextFields' => true],
        ],
     ],
 ],

#Creación de canales personalizados mediante factories

Si desea definir un canal completamente personalizado en el que tenga control total sobre la instanciación y configuración de Monolog, puede especificar un tipo de driver custom en su archivo config/logging.php. Su configuración debe incluir una opción via que contenga el nombre de la clase factory que será invocada para crear la instancia de Monolog:

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

Una vez que haya configurado el canal con driver custom, estará listo para definir la clase que creará su instancia de Monolog. Esta clase solo necesita un método __invoke que debe devolver la instancia del logger Monolog. El método recibirá el arreglo de configuración del canal como único argumento:

<?php

namespace App\Logging;

use Monolog\Logger;

class CreateCustomLogger
{
    /**
     * Crear una instancia personalizada de Monolog.
     */
    public function __invoke(array $config): Logger
    {
        return new Logger(/* ... */);
    }
}

#Visualización en tiempo real de mensajes de registro con Pail

A menudo puede necesitar visualizar en tiempo real los registros de su aplicación. Por ejemplo, al depurar un problema o al monitorear los registros para tipos específicos de errores.

Laravel Pail es un paquete que le permite explorar fácilmente los archivos de registro de su aplicación Laravel directamente desde la línea de comandos. A diferencia del comando estándar tail, Pail está diseñado para funcionar con cualquier driver de registro, incluyendo Sentry o Flare. Además, Pail ofrece un conjunto de filtros útiles para ayudarle a encontrar rápidamente lo que busca.

#Instalación

Para comenzar, instale Pail en su proyecto usando el gestor de paquetes Composer:

composer require laravel/pail

#Uso

Para comenzar a visualizar los registros, ejecute el comando pail:

php artisan pail

Para aumentar la verbosidad de la salida y evitar truncamientos (…), use la opción -v:

php artisan pail -v

Para máxima verbosidad y mostrar trazas de pila de excepciones, use la opción -vv:

php artisan pail -vv

Para detener la visualización en tiempo real, presione Ctrl+C en cualquier momento.

#Filtrado de registros

#--filter

Puede usar la opción --filter para filtrar registros por tipo, archivo, mensaje y contenido de la traza de pila:

php artisan pail --filter="QueryException"

#--message

Para filtrar registros solo por su mensaje, puede usar la opción --message:

php artisan pail --message="User created"

#--level

La opción --level puede usarse para filtrar registros por su nivel de registro:

php artisan pail --level=error

--user

Para mostrar solo los registros que se escribieron mientras un usuario dado estaba autenticado, puede proporcionar el ID del usuario a la opción --user:

php artisan pail --user=1