LuaLogging: uma API simples para usar os recursos de log em Lua

LuaLogging
Uma API simples para usar recursos de log em Lua

## Introdução

LuaLogging fornece uma API simples para usar recursos de log em Lua. O design se baseia em log4j. No momento, LuaLogging oferece suporte a resultados em consoles, arquivos, emails, soquetes e sql com o uso de appenders.

LuaLogging define uma única variável global, uma tabela chamada `logging`, que contém uma função para criar novos `logger`s.

Este construtor de `logger`s recebe uma função (chamada appender) que será chamada sempre que houver uma mensagem de log for escrita.

Uma função appender aceita três argumentos:

- self: o objeto logger
- level: o nível de log
- message: a mensagem a ser registrada

## Instalação

LuaLogging é distribuído como um conjunto de arquivos Lua e segue o modelo de pacotes de Lua 5.1, portanto, ele deve ser "instalado". Se você está usando Lua 5.0, por favor consulte a seção Configuração do Compat-5.1 para obter informações sobre como instalar corretamente os módulos.

## Objetos logger

Um objeto logger oferece os métodos a seguir, que escrevem mensagens de log.

Para cada um dos métodos a seguir, o parâmetro `message` pode ser qualquer valor Lua e não apenas strings. Quando necessário, `message` é convertido em uma string.

O parâmetro `level` pode ser uma das variáveis relacionadas a seguir. Os valores são apresentados em ordem de importância decrescente, assim, o nível mínimo é definido como `logging.WARN`, portanto, as mensagens dos níveis `logging.INFO` e `logging.DEBUG` não são registradas.

logging.DEBUG
  O nível DEBUG designa eventos informativos detalhados que são os mais úteis quando se depura um aplicativo.
logging.INFO
  O nível INFO designa as mensagens informativas que evidenciam o andamento do aplicativo em um nível menos detalhado.
logging.WARN
  O nível WARN designa situações potencialmente danosas.
logging.ERROR
  O nível ERROR designa eventos de erro que podem ainda permitir que a aplicação continue a ser executado.
logging.FATAL
  O nível FATAL designa eventos de erro muito graves que, presumivelmente, podem levar o aplicativo a ser encerrado.

### Métodos

logger:log (level, message)
  Registra uma mensagem com o nível especificado.
logger:debug (message)
  Registra uma mensagem com o nível DEBUG.
logger:info (message)
  Registra uma mensagem com o nível INFO.
logger:warn (message)
  Registra uma mensagem com o nível WARN.
logger:error (message)
  Registra uma mensagem com o nível ERROR.
logger:fatal (message)
  Registra uma mensagem com o nível FATAL.
logger:setLevel (level)
  Este método define um nível mínimo para que as mensagens sejam registradas.

## Exemplos

O exemplo a seguir cria um logger que imprime (ou executa a ação da função de impressão) o nível e a mensagem na saída padrão.

    require "logging"

    local logger = logging.new(function(self, level, message)
                                 print(level, message)
                                 return true
                               end)

    logger:setLevel (logging.WARN)
    logger:log(logging.INFO, "enviando email")

    logger:info("tentando contatar o servidor")
    logger:warn("o servidor ainda não respondeu")
    logger:error("o servidor não pode ser alcançado")

Após executar o exemplo anterior, as linhas a seguir serão mostradas na saída padrão. Observe que as solicitações de log do nível INFO não são tratadas porque o nível mínimo está definido como WARN.

    WARN o servidor ainda não respondeu
    ERROR o servidor não pode ser alcançado

## Appenders

Os appenders a seguir são incluídos na distribuição padrão.

- Console
- Arquivo
- SQL
- Soquete
- Email

## Atualização da versão 1.0.0

Fazer a atualização do LuaLogging 1.0.0 é muito fácil. O objeto `logger` é totalmente compatível. Basta alterar o código que cria o objeto.

O construtor `logger` da versão 1.0.0 aceitava um único argumento, que era um nome de arquivo. Para atualizar para a versão 1.1.0, você deve criar um objeto `logging.file`, passando o nome do arquivo como argumento. Isso é tudo.