The online documentation is produced by a web publishing technology created by us to read the documents origins in OpenOffice Writer (ODT) and Microsoft Word (docx) formats and produces native web and PDF versions. In this way we maintain Louder project documentation update and in sync on each of its formats.
El componente Logger es un componente cuyo propósito es el crear logs usando diferentes backends mediante adaptadores, opciones de generación como formatos y filtros e implementación de transacciones.
Este componente accede a sus adaptadores usando el patrón Virtual Proxy, es decir, el objeto logger solo actúa como un Proxy al objeto real instanciado que corresponde al tipo de adaptador utilizado por el mismo. La clase Logger delega todas las tareas al adaptador que por defecto es el subcomponente FileLogger, el cual realiza el almacenamiento en archivos planos del servidor.
Adaptadores de Logger
Todos los adaptadores implementan la interface LoggerInterface que define los métodos que cada adaptador debe implementar. La interface tiene la siguiente estructura:
<?php
interface LoggerInterface {
public function begin();
public function rollback();
public function commit();
public function close();
public function log($message, $type);
}
Los adaptadores disponibles son los siguientes:
Tabla: Adaptadores disponibles en el componente Logger
Adaptador
Descripción
FileLogger
Permite escribir logs a archivos de texto plano en el servidor local.
MailLogger
Permite enviar un log a un correo electrónico automáticamente en cuanto es creado.
SAMLogger
Permite enviar logs como mensajes de un servidor de mensajería Simple Asynchronous Messaging (SAM).
DatabaseLogger
Permite grabar los logs en una tabla en la base de datos.
CompressedLogger
Permite escribir logs a archivos de texto plano comprimidos usando ZLib en el servidor local.
StreamLogger
Permite escribir logs a envolturas y protocolos de PHP que soporten escritura.
SocketLogger
Permite escribir logs a puertos TCP/UDP que tengan servidores que acepten cadenas de texto.
El desarrollador puede implementar sus propios logs implementando la interface LoggerInterface.
Un ejemplo del uso del componente Logger es el siguiente:
Ejemplo: Creación de logs usando el componente Logger
<?php
class TestController extends ApplicationController {
public function testAction(){
$logger = new Logger();
$logger->log("Esto es una prueba");
}
}
Se ha creado una instancia de la clase Logger y se ha logueado el texto "Esto es una prueba". El primer parámetro que recibe el constructor de Logger es el nombre del adaptador y el segundo el nombre del archivo, en este caso se ha asumido que el adaptador es 'File' y el nombre del log la convención logYYYYMMDD.txt.
Los logs se almacenan por defecto en el directorio 'logs' de la aplicación, sin embargo esto puede modificarse usando el método setPath(). Los mensajes de los logs se crean en modo "append" es decir, que agregar nuevos logs sobre un archivo ya existe inserta al final del archivo.
El contenido resultante del archivo es el siguiente:
[Sun, 31 Aug 08 20:12:31 -0400][DEBUG] Esto es una prueba
Por defecto el formato del log es [%date%][%type%] %message%. En el siguiente ejemplo se cambia el formato de fecha y hora y de la línea del log en general, además se cambia el nombre del log:
<?php
class TestController extends ApplicationController {
public function testAction(){
$logger = new Logger("File", "my_app.log");
$logger->setFormat("> %type% > %controller%/%action% on %application% at %date% with message: %message%");
$logger->log("Esto es una prueba");
$logger->log("Esto es otra prueba");
}
}
El formato del log ha sido modificado usando el método setFormat, el cual recibe una cadena con modificadores que son reemplazados por su valor correspondiente en el momento en que se genera el log:
> DEBUG > test/test on default at Sun, 31 Aug 08 20:00:00 -0400 with message: Esto es una prueba
> DEBUG > test/test on default at Sun, 31 Aug 08 20:00:00 -0400 with message: Esto es otra prueba
Los modificadores que acepta él método setFormat son:
Tabla: Modificadores que recibe el método setFormat
Modificador
Descripción
%type%
Indica el tipo de evento logueado. Consulte la tabla de tipos de eventos para más información.
%message%
Es el mensaje logueado como tal.
%date%
Es la fecha en que ocurre el evento. Por defecto utiliza el formato que esta asignado al modificador de la función date('r') que corresponde al formato RFC 2822.
%controller%
El controlador actual en el que se llama el log.
%action%
La acción actual en la que se llama el log.
%priority%
La prioridad con respecto al contexto y el tipo de evento.
%facility%
Indica el contexto en el se produce el log.
%url%
La URL completa pasada al enrutador antes de llamar al log.
%application%
La aplicación actual en la que se genera el log.
El formato de fecha se puede modificar usando el método setFormatDate:
Ejemplo: Cambiar el formato de fecha de un log usando setFormatDate
<?php
class TestController extends ApplicationController {
public function testAction(){
$logger = new Logger("File", "my_app.log");
$logger->setFormat("> %type% > %controller%/%action% on %application% at %date% with message: %message%");
$logger->setDateFormat("Y.m.d H:i");
$logger->log("Esto es una prueba");
}
}
El log generado es el siguiente:
> DEBUG > test/test on default at 2008.10.21 00:14 with message: Esto es una prueba
Tipos de Eventos en Logs
El componente Logger proporciona una serie de tipos de eventos que permiten clasificar cada uno de acuerdo a una gravedad ó prioridad en algunos contextos. Para definir el tipo de evento en una línea del log se pasa como segundo parámetro al método log una constante del componente logger así:
$logger->log("La memoria usada por la aplicación es ".memory_get_usage(), Logger::INFO);
Los valores de las constantes coinciden con las severidades usadas por syslog y estandarizadas en el RFC 3164 : The BSD syslog Protocol (http://tools.ietf.org/html/rfc3164) .
Adicionales a los estándar, Logger agrega los eventos CUSTOM y SPECIAL con menor severidad que los demás pero que se utilizan en contextos menos críticos. Los tipos de eventos soportados son:
Tabla: Eventos y su descripción
Tipo de Evento
Severidad
Descripción
EMERGENCY
0
Emergencia: El sistema esta inutilizable.
ALERT
1
Alerta: Mensajes de alerta.
CRITICAL
2
Critico: Propende a la que se tomen acciones de inmediato
ERROR
3
Errores: Errores ó excepciones de la aplicación
WARNING
4
Advertencias: Condiciones de Advertencia
NOTICE
5
Mensajes que ocurren en condición normal.
INFO
6
Mensajes de información.
DEBUG
7
Mensajes de debug.
CUSTOM
8
Mensajes sin clasificar generandos por el usuario final.
SPECIAL
9
Condiciones especiales fuera de un contexto de criticidad. Como por ejemplo llevar un registro de los usuarios que ingresan a la aplicación.
Métodos del mismo nombre son proporcionados en la clase Logger y realizan la misma tarea que log:
Ejemplo: Usar métodos alias para indicar la severidad de un mensaje
$logger->log("Esto es una Advertencia!", Logger::WARNING);
$logger->warning("Esto es una Advertencia!");
El tipo de evento por defecto es Logger::DEBUG.
Logger Facilities
Kumbia Enterprise Framework mantiene separados los espacios de memoria y ejecución desde el Sistema Operativo hasta el Nivel de Usuario esta información permite evaluar en que contexto se producen los mensajes de log.
Los Facility son los siguientes:
Tabla: Nombres y descripción de Facilities
Código
Nombre
Descripción
0
SO
Generada en el contexto de sistema operativo. Usualmente se relaciona con problemas con permisos ó alertas del SO.
1
HARDWARE
Relacionado con actividades
2
NETWORK
Es el contexto de comunicaciones e infraestructura de red.
3
FRAMEWORK_CORE
Contexto del núcleo del Framework.
4
FRAMEWORK_COMPONENTS
Contexto de Componentes del Framework (bundled)
5
SECURITY
Contexto de Seguridad
5
AUDIT
Contexto de Auditoria
6
USER_LEVEL
Problemas ocurridos a nivel de usuario y aplicaciones.
Para obtener el código numérico del Facility Actual se utiliza el método estático Facility::getFacility(). Por medio del facility es posible determinar el contexto en el que se originó un log. El tipo de evento visto como severidad y el facility como el contexto en el que se generó, permiten calcular la "Prioridad". Ésta es el resultado de multiplicar los códigos de ambos, la severidad y el facility.
Transacciones con Logs
Cada adaptador realiza una implementación propia de transacciones según su naturaleza. Las transacciones permiten al desarrollador decidir si los mensajes de log acumulados durante un proceso de negocio es necesario almacenarlos en los backend ó anular la operación. Los métodos begin, commit y rollback familiares en un ambiente de base de datos pueden ser usados en el archivo de log para administrar el estado de la transacción.
En el siguiente se ejemplo se ilustra mediante una transacción de negocio como el log es creado pero solo se guarda si se cumplen ciertas condiciones del procedimiento:
Ejemplo: Crear una transacción en un log
<?php
class PricesController extends WebServiceController {
public function enterpriseProcedureAction(){
$logger = new Logger("File", "procedure.log");
$logger->begin();
$customer = new Customer();
$movements = $customer->getMovement();
if(count($movement)==0){
$logger->log("No hay movimiento para el cliente '{$customer->getId()}'");
}
$firstDay = Date::getFirstDayOfYear();
$lastDay = Date::getLastDayOfYear();
$totalPrice = 0;
foreach($movements as $movement){
if(Date::between($movement->getDate(), $firstDay, $lastDay)==true){
$logger->log("El movimiento {$movement->getId()} es de este año");
if($movement->getStatus()!="F"){
$movement->setStatus("F");
$movement->save();
$totalPrice+=$movement->getPrice();
}
} else {
if($movement->getStatus()!="H"){
$movement->moveToHistorical();
}
}
}
if($totalPrice>=$cutomer->getMaxPrice()){
$logger->log("El cliente '".$customer->getId()."' ha sobrepasado su crédito");
$logger->commit();
}
$logger->rollback();
}
}
?>
API de FileLogger
public void setPath(string $path) Permite establecer el Path donde se almacenaran los logs.
public void setFormat(string $format) Establece el formato en el que se producirá cada línea del log.
public void setDateFormat(string $format) Establece el formato de fecha con los modificadores de las función date() para producir las fechas en las lineas del log.
public $path getPath() Obtiene el path actual donde se están almacenando los logs.
public void log(mixed $msg, $type=Logger::DEBUG) Agrega una líne al log de tipo $type.
public void begin() Inicia una transacción en el log.
public void rollback() Cancela una transacción en el log.
public void commit() Acepta una transacción en el log almacenando las lineas pendientes.
public void close() Cierra el log.
Uso de MailLogger
El componente Logger soporta un adaptador especial que permite que este al cerrarse se envie automáticamente a un correo electrónico. La extensión hace uso de la librería de envío de correo electrónico Swift que se distribuye con el framework.
El adaptador está diseñado para realizar el envío de e-mails usando el protocolo SMTP sin depender de la función mail() de PHP ó de la herramienta sendmail.
Todas los registros del log que son agregados se almacenan en memoria hasta que se cierra el log, se invoca el método commit ó se destruye el objeto. Debido a lo anterior es recomendable no almacenar logs muy grandes ya que pueden consumir demasiada memoria y generar una salida fatal por parte de la aplicación.
Los registros solo se pueden agregar cuando se activa una transacción en el log, por defecto una es iniciada automáticamente. También se puede usar el método begin() para iniciarla.
Es necesario que el servidor pueda establecer conexiones salientes a puertos seguros (465) e inseguros (25) y que el servidor SMTP esté disponible al tratar de realizar el envio del log pues de lo contrario se generará una excepción.
La extensión de PHP php_openssl debe estar cargada para hacer uso de este adaptador.
El siguiente es un ejemplo del uso de MailLogger enviando un mensaje desde una cuenta de Gmail:
Ejemplo: Crear un MailLogger que envia los mensajes a un correo de Gmail
$log = new Logger("Mail", "support@example.com", array(
"server" => "smtp.gmail.com",
"secureConnection" => true,
"username" => "company.support@gmail.com",
"password" => "98j2ue12",
"subject" => "Problema en la aplicación"
));
$log->log("Un Message de Error", Logger::ERROR);
$log->log("Un Message Critico", Logger::CRITICAL);
$log->close();
Al cerrar el log se envia un mail con los 2 mensajes acumulados internamente en el log. Para realizar conexiones seguras por TLS se debe establecer el parámetro "secureConnection" a true.
Cuando no se establece el asunto del mensaje MailLogger utiliza el siguiente formato:
MailLog: nombreAplicacion – Fecha usando formato RFC2822
Si se desea enviar el log a varios e-mails se puede pasar un array como segundo parámetro al instanciar el log:
Ejemplo: Enviando los mensajes del MailLogger a varios correos electronicos
$log = new Logger("Mail", array(
"Soporte al Cliente" => "customer.support@example.com",
"Soporte Tecnico" => "technical.support@example.com",
"anothermail@example.com"
), array(
"server" => "smtp.gmail.com",
"secureConnection" => true,
"username" => "company.support@gmail.com",
"password" => "98j2ue12",
"subject" => "Problema en la aplicación"
));
$log->log("Un Message de Error", Logger::ERROR);
$log->log("Un Message Critico", Logger::CRITICAL);
$log->close();
Uso de DatabaseLogger
FALTA
Uso de CompressedLogger
El adaptador CompressedLogger permite escribir logs a archivos de texto plano comprimidos usando zlib en el servidor local. La extensión de PHP zlib debe estar cargada para hacer uso de este adaptador.
La ventaja de el uso de este tipo de logs es que ahorran sustancialmente espacio de disco aunque requieren de mayores requerimientos de procesamiento.
Ejemplo: Crear un log comprimido con Logger
$logger = new Logger("Compressed", "my_app.log.gz");
$logger->log("Esta cadena será comprimida en el log");
$logger->close();
Al igual que FileLogger los registro se agregan en modo append es decir que nuevos mensajes se agregan al final del archivo.
public void setPath(string $path) Permite establecer el Path donde se almacenaran los logs.
public void setFormat(string $format) Establece el formato en el que se producirá cada línea del log.
public void setDateFormat(string $format) Establece el formato de fecha con los modificadores de las función date() para producir las fechas en las lineas del log.
public $path getPath() Obtiene el path actual donde se están almacenando los logs.
public void log(mixed $msg, $type=Logger::DEBUG) Agrega una líne al log de tipo $type.
public void begin() Inicia una transacción en el log.
public void rollback() Cancela una transacción en el log.
public void commit() Acepta una transacción en el log almacenando las lineas pendientes.
public void close() Cierra el log.
Uso de SAMLogger
El adaptador SAMLogger permite enviar logs a un servicio de mensajes que soporten Simple Asynchronous Messaging como el IBM WebSphere MQSeries. Este adaptador requiere de a extensión SAM que permite el envio de mensajes de logs a aplicaciones basadas en el WebSphere Application Server que usen el protocolo de mensajes WebSphere Platform Messaging (WPM). La extensión puede ser descargada de PECL.
Ejemplo: Enviar mensajes de log a WebSphere Messaging Server
//Conectarse a un servidor SAM con WebSphere Messaging Server
$logger = new Logger("SAM", null, array(
'host => '192.168.10.100',
'port' => 1506',
'broker' => 'webspherebroker'
));
$logger->log("Esto es una alerta", Logger::ALERT);
//Conectarse a un servidor SAM de una aplicación en WebSphere Application Server
$logger = new Logger("SAM", null, array(
'endpoints => '192.168.10.100:7278:MyMessagingBoostrap',
'bus' => Bus1',
'targetchain' => 'InboundMessaging'
));
$logger->log("Esto es una alerta", Logger::ALERT);
Uso de StreamLogger
Este adaptador es el más flexible y potente de los adaptadores de Logger ya que permite escribir logs a diferentes recursos cuya escritura por stream este soportada por PHP.
En los siguientes ejemplos se ilustra el uso de este adaptador:
Ejemplo: Enviar mensajes de Log usando el adaptador StreamLogger
//Este log será enviado a un archivo
$logger = new Logger("Stream", "file://mylog.txt");
$logger->log("Un log de ejemplo");
$logger->close();
//Este log será enviado a un archivo comprimido con gzip
$logger = new Logger("Stream", "compress.zlib://mylog.txt.gz");
//Este log será enviado a un archivo comprimido con bzip2
$logger = new Logger("Stream", "compress.bzip2://mylog.txt.gz");
//Este log será enviado a un archivo comprimido con bzip2
$logger = new Logger("Stream", "compress.bzip2://mylog.txt.bz2");
//Este log será enviado a un archivo mediante SSH
$logger = new Logger("Stream", 'ssh2.sftp://user:password@example.com:22/path/to/file.txt");
//Este log será enviado a un archivo mediante FTP
$logger = new Logger("Stream", "ftp://user:password@example.com/path/to/file.txt");
//Este log será enviado a un archivo mediante FTP seguro
$logger = new Logger("Stream", "ftps://user:password@example.com/path/to/file.txt");
//Este log será enviado a la salida estándar
$logger = new Logger("Stream", "php://stdout");
//Este log será enviado a la salida de errores
$logger = new Logger("Stream", "php://stderr");
//Este log será enviado a memoria
$logger = new Logger("Stream", "php://memory");
//Este log será enviado a memoria, en caso que los datos tengan un tamaño superior a 2MB serán escritos a disco
$logger = new Logger("Stream", "php://temp");
//Cambiar limite a 10MB – 1073741824 bytes
$logger = new Logger("Stream", "php://temp/maxmemory:1073741824");
En las opciones del Stream puede establecerse el modo de escritura que tendrá en Log de esta forma:
$logger = new Logger("Stream", "file://my_log.txt", array(
"mode" => "a"
));
Los posibles modos de escritura son:
Tabla: Modos de escritura de logs usando StreamLogger
Modo
Descripción
a
Agrega logs al final del archivo existente. Si no existe lo crea.
ab
Agrega logs al final del archivo existe. La escritura es binaria. Este es el modo predeterminado para StreamLogger, FileLogger y CompressedLogger.
w
Escribe logs en el archivo. Lo trunca si existe y lo crea si no existe.
wb
Escribe logs en el archivo. Lo trunca si existe y lo crea si no existe. La escritura es binaria.
x
Escribe logs en el archivo. Si ya existe genera una excepción.
Uso de SocketLogger
Permite escribir logs a puertos TCP/UDP que tengan servidores ó servicios que acepten cadenas de texto. Los servidores de sockets pueden replicar logs a otros servidores mediante carácteristicas de bajo nivel.
Ejemplo: Enviar mensajes de logs usando sockets TCP/UDP
//Escribir a un servidor TCP en el puerto 1589
$logger = new Logger("Socket", "tcp://192.168.0.10:1589");
//Escribir a un servidor TCP en el puerto 1589 usando una conexión segura
$logger = new Logger("Socket", "ssl://192.168.0.10:1589");
//Escribir a un servidor UDP en el puerto 111
$logger = new Logger("Socket", "udp://192.168.0.10:111");
