Logging

Phalcon\Logger es un componente cuyo propósito es proporcionar servicios de registro (logging) para aplicaciones. Ofrece diferentes formas de almacenamiento con diversos adaptadores. También ofrece registro de transacciones, opciones de configuración, diferentes formatos y filtros. Puede utilizar el Phalcon\Logger para cada necesidad de registrar información que tenga su aplicación, desde depuración de procesos hasta el rastreo del flujo de una aplicación.

Adaptadores

Este componente hace uso de adaptadores para almacenar los mensajes. El uso de adaptadores permite una interfaz común de registro de mensajes y proporciona la capacidad de cambiar fácilmente el método de almacenamiento (backend) si es necesario. Los adaptadores soportados son:

Adaptador Descripción
Phalcon\Logger\Adapter\File Registros son almacenados en un archivo de texto
Phalcon\Logger\Adapter\Stream Registros enviados al PHP Stream
Phalcon\Logger\Adapter\Syslog Registros se almacenan en el sistema de log del sistema
Phalcon\Logger\Adapter\FirePHP Registros se envían a la extensión FirePHP

Factory

Carga la clase adaptador Logger utilizando la opción adapter

<?php

use Phalcon\Logger\Factory;

$options = [
    'name'    => 'log.txt',
    'adapter' => 'file',
];

$logger = Factory::load($options);

Creación de un Log

El siguiente ejemplo muestra cómo crear un registro y añadir mensajes a él:

<?php

use Phalcon\Logger;
use Phalcon\Logger\Adapter\File as FileAdapter;

$logger = new FileAdapter('app/logs/test.log');

// Hay diferentes niveles de registo disponibles:

$logger->critical(
    'This is a critical message'
);

$logger->emergency(
    'This is an emergency message'
);

$logger->debug(
    'This is a debug message'
);

$logger->error(
    'This is an error message'
);

$logger->info(
    'This is an info message'
);

$logger->notice(
    'This is a notice message'
);

$logger->warning(
    'This is a warning message'
);

$logger->alert(
    'This is an alert message'
);

// Puedes usar el método log() con una constante Logger:
$logger->log(
    'This is another error message',
    Logger::ERROR
);

// Si no se proporciona una constante, se asume el valor DEBUG.
$logger->log(
    'This is a message'
);

// Puedes pasar parámetros de contexto, por ejemplo
$logger->log(
    'This is a {message}', 
    [ 
        'message' => 'parameter' 
    ]
);

El registro generado está abajo:

[Tue, 28 Jul 15 22:09:02 -0500][CRITICAL] This is a critical message
[Tue, 28 Jul 15 22:09:02 -0500][EMERGENCY] This is an emergency message
[Tue, 28 Jul 15 22:09:02 -0500][DEBUG] This is a debug message
[Tue, 28 Jul 15 22:09:02 -0500][ERROR] This is an error message
[Tue, 28 Jul 15 22:09:02 -0500][INFO] This is an info message
[Tue, 28 Jul 15 22:09:02 -0500][NOTICE] This is a notice message
[Tue, 28 Jul 15 22:09:02 -0500][WARNING] This is a warning message
[Tue, 28 Jul 15 22:09:02 -0500][ALERT] This is an alert message
[Tue, 28 Jul 15 22:09:02 -0500][ERROR] This is another error message
[Tue, 28 Jul 15 22:09:02 -0500][DEBUG] This is a message
[Tue, 28 Jul 15 22:09:02 -0500][DEBUG] This is a parameter

También puede establecer un nivel de registro usando el método setLogLevel(). Este método toma una constante del Logger y sólo almacenará mensajes que son tan importantes o más importantes que la constante:

<?php

use Phalcon\Logger;
use Phalcon\Logger\Adapter\File as FileAdapter;

$logger = new FileAdapter('app/logs/test.log');

$logger->setLogLevel(
    Logger::CRITICAL
);

En el ejemplo anterior, solo los mensajes críticos y de emergencia se guardarán en el registro. Por defecto, todo está guardado.

Transacciones

Registrar datos en un adaptador, es decir, el archivo (sistema de archivos) es siempre una operación costosa en términos de rendimiento. Para combatir eso, puede aprovechar las transacciones de registro. Las transacciones almacenan datos de registro temporalmente en la memoria y luego escriben los datos en el adaptador relevante (Archivo en este caso) en una sola operación atómica.

<?php

use Phalcon\Logger\Adapter\File as FileAdapter;

// Crear el logger
$logger = new FileAdapter('app/logs/test.log');

// Comenzar una transacción
$logger->begin();

// Agregar mensajes
$logger->alert(
    'Esta es una alerta'
);

$logger->error(
    'Este es otro error'
);

// Confirmar los mensajes en el archivo
$logger->commit();

Registro de múltiples gestores

Phalcon\Logger puede enviar mensajes a múltiples controladores con una sola y única llamada:

<?php

use Phalcon\Logger;
use Phalcon\Logger\Multiple as MultipleStream;
use Phalcon\Logger\Adapter\File as FileAdapter;
use Phalcon\Logger\Adapter\Stream as StreamAdapter;

$logger = new MultipleStream();

$logger->push(
    new FileAdapter('test.log')
);

$logger->push(
    new StreamAdapter('php://stdout')
);

$logger->log(
    'Este es un mensaje'
);

$logger->log(
    'Este es un error',
    Logger::ERROR
);

$logger->error(
    'Este es otro error'
);

Los mensajes se envían a los controladores en el orden en que se registraron.

Formato de mensaje

Este componente utiliza formatters para formatear mensajes antes de enviarlos al backend. Los formateadores disponibles son:

Adaptador Descripción
Phalcon\Logger\Formatter\Line Formato de mensajes utilizando una cadena de texto de una línea
Phalcon\Logger\Formatter\Firephp Formato de mensajes que pueden ser enviados a FirePHP
Phalcon\Logger\Formatter\Json Prepara un mensaje para ser codificados con JSON
Phalcon\Logger\Formatter\Syslog Se prepara un mensaje para enviarse al syslog

Formateador de línea

Formato de mensajes utilizando una cadena de texto de una línea. El formato por defecto de los mensajes es:

[%date%][%type%] %message%

Puede cambiar el formato predeterminado utilizando setFormat(), esto le permite cambiar el formato de los mensajes registrados mediante la definición de uno propio. Las variables de formato de registro permitidas son:

Variable Descripción
%message% El mensaje que se espera registrar
%date% Fecha que del mensaje fue agregado
%type% Tipo de mensaje en mayúsculas

El siguiente ejemplo muestra cómo cambiar el formato de registro:

<?php

use Phalcon\Logger\Formatter\Line as LineFormatter;

$formatter = new LineFormatter('%date% - %message%');

// Cambiando el formato de registro
$logger->setFormatter($formatter);

Implementar tus propios formateadores

La interfaz Phalcon\Logger\FormatterInterface debe implementarse para crear su propio formateador de registro o ampliar los existentes.

Adaptadores

Los siguientes ejemplos muestran el uso básico de cada adaptador:

Stream Logger

El registro en stream escrime mensajes en una secuencia registrada valida para PHP. Lista disponible de streams:

<?php

use Phalcon\Logger\Adapter\Stream as StreamAdapter;

// Abrir el stream utilizando compresión zlib
$logger = new StreamAdapter('compress.zlib://week.log.gz');

// Escribir registros en stderr
$logger = new StreamAdapter('php://stderr');

File Logger

Este registrador usa archivos simples para registrar cualquier tipo de dato. Por defecto, todos los archivos del registrador se abren usando el modo de adición que abre los archivos para escritura solamente; colocando el puntero del archivo al final del archivo. Si el archivo no existe, se intentará crearlo. Puede cambiar este modo pasando opciones adicionales al constructor:

<?php

use Phalcon\Logger\Adapter\File as FileAdapter;

// Crear un archivo de registro en modo 'w'
$logger = new FileAdapter(
    'app/logs/test.log',
    [
        'mode' => 'w',
    ]
);

Syslog Logger

Este logger envía mensajes al sistema de registro del sistema. El comportamiento del syslog puede variar entre distintos sistemas operativos.

<?php

use Phalcon\Logger\Adapter\Syslog as SyslogAdapter;

// Uso básico
$logger = new SyslogAdapter(null);

// Configurando ident/mode/facility
$logger = new SyslogAdapter(
    'ident-name',
    [
        'option'   => LOG_NDELAY,
        'facility' => LOG_MAIL,
    ]
);

FirePHP Logger

Este registrador envía mensajes en encabezados de respuesta HTTP que se muestran por FirePHP, una Firebug extensión para Firefox.

<?php

use Phalcon\Logger;
use Phalcon\Logger\Adapter\Firephp as Firephp;

$logger = new Firephp('');

$logger->log(
    'Este es un mensaje'
);

$logger->log(
    'Este es un error',
    Logger::ERROR
);

$logger->error(
    'Este es otro error'
);

Implementar tus propios adaptadores

La interfaz Phalcon\Logger\Adapterinterface debe implementarse para crear sus propios adaptadores de registradores o ampliar los existentes.