Log

1Apresentação

É absolutamente necessário poder acompanhar a execução do código de uma aplicação. Durante o desenvolvimento, ou quando é preciso fazer alguma depuração, queremos saber quais funções são executadas e em que ordem. Para uma aplicação em produção, queremos rastrear todos os erros, para poder tratá-los especificamente.

O Temma oferece um mecanismo de log baseado no objeto \Temma\Base\Log.

2Log simples

A maneira mais fácil de escrever uma mensagem de log é chamar o método estático l(), informando a ele a mensagem a ser escrita no arquivo de log como parâmetro. A mensagem pode ser uma string de caracteres (que será exibida tal como está), ou qualquer dado PHP (que será então serializado com a função print_r).

Aqui estão alguns exemplos:

\Temma\Base\Log::l("Mensagem que será escrita sistematicamente");
\Temma\Base\Log::l(['zone' => 'internal', 'idx' => 3]);
  • Linha 1: A mensagem de texto obrigatoriamente aparecerá no arquivo de log.
  • Linha 2: Os dados fornecidos como parâmetro também obrigatoriamente serão escritos no arquivo de log, depois de terem sido convertidos em uma representação textual.

Para facilitar as chamadas ao objeto de log, pode-se usar um alias: 

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

TµLog::l("Mensagem que será escrita sistematicamente");

3Log avançado

Para utilizá-lo, basta chamar o método estático log(), fornecendo a ele 3 parâmetros (os dois primeiros são opcionais):

  • Uma classe de log, ou seja, um rótulo que permitirá ao sistema saber o limiar de criticidade a partir do qual a mensagem aparecerá.
  • Um nível de criticidade, na forma de uma string curta, que serve para indicar se se trata de uma simples mensagem de depuração, ou de uma informação relatando um erro crítico.
  • O texto da mensagem de log. Pode ser uma string (que será exibida tal como está), ou qualquer dado PHP (que será então serializado com a função print_r).

Aqui está a lista dos níveis de criticidade gerenciados pelo \Temma\Base\Log:

  • DEBUG: mensagem de depuração (criticidade mais baixa)
  • INFO: mensagem de informação (nível padrão das mensagens cuja criticidade não é especificada)
  • NOTE: notificação; mensagem normal, mas significativa (limiar padrão)
  • WARN: mensagem de alerta; a aplicação não funciona normalmente, mas pode continuar a funcionar
  • ERROR: mensagem de erro; a aplicação não funciona normalmente e deve parar
  • CRIT: mensagem de erro crítico; a aplicação corre o risco de danificar seu ambiente (criticidade mais alta)

Para que uma mensagem seja escrita no arquivo de log, seu nível de criticidade deve ser maior ou igual ao limiar previsto para sua classe de log. As classes de log são definidas no arquivo de configuração etc/temma.php (veja configuração).
Uma mensagem de log com nível de criticidade indefinido é considerada uma mensagem de informação (INFO).
Se a classe de uma mensagem não for definida, ela recebe uma classe padrão, cujo limiar de aparição é NOTE.

Aqui estão alguns exemplos:

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

TµLog::log("Mensagem de log usando os limiares padrão.");
TµLog::log('NOTE', "Registro vinculado à classe padrão.");
TµLog::log('myapp', 'DEBUG', "Esta é uma mensagem de depuração.");
TµLog::log('data', 'INFO', ['zone' => 'internal', 'idx' => 3]);
  • Linha 1: Criamos um alias para facilitar a chamada ao objeto de log.
  • Linha 3: Esta mensagem tem uma criticidade padrão (INFO), e uma classe padrão (default, cujo limiar é NOTE). Como a criticidade é menos importante que o limiar, a mensagem não aparecerá.
  • Linha 4: Esta mensagem tem a criticidade NOTE, e uma classe padrão (default, cujo limiar é NOTE). Como a criticidade é igual ao limiar, a mensagem aparecerá.
  • Linha 5: Esta mensagem tem a criticidade DEBUG (a menos importante), e é para a classe myapp. Se o limiar dessa classe estiver definido como DEBUG, a mensagem aparecerá.
  • Linha 6: Esta mensagem tem a criticidade INFO, e a classe data. Se o limiar dessa classe estiver definido como INFO ou DEBUG, a mensagem aparecerá. Como a mensagem é um array associativo, o sistema de log vai exibi-la depois de convertida em texto.

4Controle do log

É possível modificar o comportamento do log, chamando métodos estáticos do objeto \Temma\Base\Log:

  • disable() para desativar o log.
  • enable() para reativar o log.
  • logToStdOut() para ativar a escrita do log na saída padrão. Pode receber um parâmetro booleano opcional (true para ativar, false para desativar).
  • logToStdErr() para ativar a escrita do log na saída de erro. Pode receber um parâmetro booleano opcional (true para ativar, false para desativar).
  • setLogFile($path) para redefinir o caminho do arquivo de log.
  • addCallback($function) para adicionar uma função a ser chamada a cada log.
    Essa função deve receber os seguintes parâmetros:
    • (string) Identificador da requisição.
    • (string) Mensagem de log.
    • (string) Nível de criticidade (opcional).
    • (string) Classe de log (opcional).

Normalmente, não há necessidade de chamar esses métodos, já que o sistema de log é inicializado pelo framework.