Log

1Presentación

Es absolutamente necesario poder seguir la ejecución del código de una aplicación. Durante el desarrollo, o cuando hay que hacer alguna depuración, queremos saber qué funciones se ejecutan y en qué orden. Para una aplicación en producción, queremos rastrear todos los errores, para poder tratarlos específicamente.

Temma ofrece un mecanismo de log basado en el objeto \Temma\Base\Log.

2Log simple

La forma más sencilla de escribir un mensaje de log es llamar al método estático l(), dándole como parámetro el mensaje que se debe escribir en el archivo de log. El mensaje puede ser una cadena de caracteres (que se mostrará tal cual), o cualquier dato PHP (que se serializará entonces con la función print_r).

Aquí tienes algunos ejemplos:

\Temma\Base\Log::l("Mensaje que se escribirá sistemáticamente");
\Temma\Base\Log::l(['zone' => 'internal', 'idx' => 3]);
  • Línea 1: El mensaje de texto aparecerá necesariamente en el archivo de log.
  • Línea 2: Los datos proporcionados como parámetro también se escribirán necesariamente en el archivo de log, después de haber sido convertidos a una representación textual.

Para facilitar las llamadas al objeto de log, se puede usar un alias: 

use \Temma\Base\Log as TµLog;

TµLog::l("Mensaje que se escribirá sistemáticamente");

3Log avanzado

Para usarlo, basta con llamar al método estático log(), proporcionándole 3 parámetros (los dos primeros son opcionales):

  • Una clase de log, es decir una etiqueta que permitirá al sistema conocer el umbral de criticidad a partir del cual el mensaje aparecerá.
  • Un nivel de criticidad, en forma de una cadena de caracteres corta, que sirve para indicar si se trata de un simple mensaje de depuración, o de una información que informa de un error crítico.
  • El texto del mensaje de log. Puede ser una cadena de caracteres (que se mostrará tal cual), o cualquier dato PHP (que se serializará entonces con la función print_r).

Aquí tienes la lista de los niveles de criticidad gestionados por \Temma\Base\Log:

  • DEBUG: mensaje de depuración (criticidad más baja)
  • INFO: mensaje de información (nivel por defecto de los mensajes cuya criticidad no se especifica)
  • NOTE: notificación; mensaje normal pero significativo (umbral por defecto)
  • WARN: mensaje de alerta; la aplicación no funciona normalmente pero puede seguir funcionando
  • ERROR: mensaje de error; la aplicación no funciona normalmente y debe detenerse
  • CRIT: mensaje de error crítico; la aplicación corre el riesgo de dañar su entorno (criticidad más alta)

Para que un mensaje se escriba en el archivo de log, su nivel de criticidad debe ser mayor o igual al umbral definido para su clase de log. Las clases de log se definen en el archivo de configuración etc/temma.php (ver Configuración).
Un mensaje de log con un nivel de criticidad indefinido se considera un mensaje de información (INFO).
Si la clase de un mensaje no está definida, se le asigna una clase por defecto, cuyo umbral de aparición es NOTE.

Aquí tienes algunos ejemplos:

use \Temma\Base\Log as TµLog;

TµLog::log("Mensaje de log usando los umbrales por defecto.");
TµLog::log('NOTE', "Registro vinculado a la clase por defecto.");
TµLog::log('myapp', 'DEBUG', "Este es un mensaje de depuración.");
TµLog::log('data', 'INFO', ['zone' => 'internal', 'idx' => 3]);
  • Línea 1: Creamos un alias para facilitar la llamada al objeto de log.
  • Línea 3: Este mensaje tiene una criticidad por defecto (INFO), y una clase por defecto (default, cuyo umbral es NOTE). Al ser la criticidad menos importante que el umbral, el mensaje no aparecerá.
  • Línea 4: Este mensaje tiene la criticidad NOTE, y una clase por defecto (default, cuyo umbral es NOTE). Al ser la criticidad igual al umbral, el mensaje aparecerá.
  • Línea 5: Este mensaje tiene la criticidad DEBUG (la menos importante), y pertenece a la clase myapp. Si el umbral de esta clase está fijado en DEBUG, el mensaje aparecerá.
  • Línea 6: Este mensaje tiene la criticidad INFO, y la clase data. Si el umbral de esta clase está fijado en INFO o DEBUG, el mensaje aparecerá. Al ser el mensaje un array asociativo, el sistema de log lo mostrará después de convertirlo a texto.

4Control del log

Es posible modificar el comportamiento del log, llamando a métodos estáticos del objeto \Temma\Base\Log:

  • disable() para desactivar el log.
  • enable() para reactivar el log.
  • logToStdOut() para activar la escritura del log en la salida estándar. Puede tomar un parámetro booleano opcional (true para activar, false para desactivar).
  • logToStdErr() para activar la escritura del log en la salida de error. Puede tomar un parámetro booleano opcional (true para activar, false para desactivar).
  • setLogFile($path) para redefinir la ruta del archivo de log.
  • addCallback($function) para añadir una función que se llamará en cada log.
    Esta función debe recibir los siguientes parámetros:
    • (string) Identificador de la petición.
    • (string) Mensaje de log.
    • (string) Nivel de criticidad (opcional).
    • (string) Clase de log (opcional).

Generalmente, no hay necesidad de llamar a estos métodos, ya que el sistema de log es inicializado por el framework.