heimdall-logger 0.1.1

Asynchronous logging lib

:satellite: Heimdall Logger :satellite:

Resumo

Este projeto foi desenvolvido como resultado de um estudo sobre sistemas assíncronos e, da necessidade de prover um serviço flexível, que pudesse ser estendido a diversos cenários e formas de aplicação, podendo ser utilizado tanto para a finalidade de log's síncronos quanto assíncronos. As funcionalidades do heimdall-logger serão mais bem discutidas nas seções pertinentes. Este módulo tem como objetivo permitir:

• Realizar logs de forma síncrona e assíncrona
• Realizar logs nos formatos LOG, TXT e JSON (Outros formatos serão implementados posteriormente)
• Realizar callback do log para api's de acordo com o a necessidade do usuário

Ao longo do desenvolvimento do projeto, outras integrações poderão ser adicionadas, desde que, sejam efetuadas respeitando as diretrizes e padrões adotados neste projeto, esta decisão foi tomada com a finalidade de manter a integridade conceitual do projeto. Sinta-se à vontade para contribuir com o mesmo.

Roadmap

1. Melhorar a funcionalidade de escrita para arquivos JSON.
2. Melhoria e aumento da profundidade dos testes da aplicação.
3. Implantação outros formatos de saída para os arquivos de log (Ex: XML, CSV).
4. Adicionar funcionalidades de stream e funcionalidades de escrita mais personalizáveis.
5. Implantação de prova de conceito para providers em bancos de dados. (SQL, MongoDB, MySQL, PostgreSQl, entre outros)

Setup

Para rodar o projeto heimdall-logger localmente.

1. Realize o clone desta aplicação para seu diretório de projetos
2. Certifique-se de possuir o make instalado em seu OS
3. Crie um ambiente virtual utilizando gerenciador de sua preferência > (pyenv, virtualenv, anaconda...).
4. Dentro deste diretório será possível verificar a criação da pasta: heimdall-logger
5. Execute o comando:

make install-requeriments

    ou caso não possua o make, poderá rodar o comando:

pip install -r requirements.txt

Seguido de:

pip install -r requirements-dev.txt

7. Se todos os pacotes foram instalados corretamente você poderá executar:

make run-demo

Será possível observar no seu console, o log de todos os oito níveis existentes nesta lib sendo exibidos

Para rodar a suite de testes execute:

make test-coverage

    ou caso não possua o make, poderá rodar o comando:

pytest --cov-report term-missing --cov=project/

Ou ainda, de acordo com a preferência do desenvolvedor, os testes poderão ser executados via plugin da sua IDE ou editor de códigos preferida, recomendo a Python Test Explorer for Visual Studio Code ou ainda Test Explorer UI.

Utilização

Para realizar a instalação do heimdall-logger:

pip install heimdall-logger

Após realizar a instalação, você poderá importar as funcionalidades que utilizará para criar a instância de log, de acordo com sua necessidade. Ao importar o heimdall-logger, serão expostos os seguintes módulos:

from heimdall_logger import (
  Extension,
  Level,
  FileDataLog,
  ApiSendLog,
  SyncLogger,
  AsyncLogger
)

Tendo importado os módulos necessários para implantar o log no contexto desejado vamos instânciar todas as dependências da seguinte forma:

Para gerarmos nosso arquivo de log utilizaremos o modulo FileDataLog (vide a seção Overview):

_log_file_data = FileDataLog(
    log_extension=Extension.LOG,
    log_name="[NOME_DESEJADO_PARA_O_ARQUIVO_DE_LOG]",
    log_path="[CAMINHO_DESEJADO_PARA_GRAVAÇÃO_DO_LOG]"
)

Caso seja necessário podemos também chamar uma API e enviar nossos dados de log para ela da seguinte forma:

_api_send_log = ApiSendLog(
    api_route="[ROTA_DA_API_A_QUAL_DESEJA_ENVIAR_O_LOG]",
    api_method="[METODO_HTTP]",
    api_headers="[CASO_PRECISE_ENVIE_OS_CABEÇALHOS_COMO_DICT]"
)

E finalmente criamos nossa instância de log:

sync_logger = SyncLogger(
    project_name="[NOME_DO_PROJETO_EM_CONTEXTO]",
    file_data=_log_file_data,
    api_callback=_api_send_log
)

Ou então:

async_logger = AsyncLogger(
    project_name="",
    file_data=object,
    api_callback=object
)

Perceba que não enviamos o atributo pattern em nenhuma das duas formas, isso se deve ao fato de que o padrão pré-configurado nos atende em todos os cenário, não sendo seu caso, é possível configurar um novo padrão da seguinte forma:

padrão pré-configurado:

_pattern = "[{level}][{datetime}] - {transaction} - {project_name}.{class_name}.{function_name} - {message}"

padrão customizado:

_pattern = "[{level}][{datetime}] | {transaction} | {project_name}_{class_name}_{function_name}: {message}"

Desde que seja respeitado o nome dos parâmetros (level, datetime, transaction, project_name, class_name, function_name e message) o log será gravado no padrão que for mais conveniente ao seu proposito. Dito isto, basta enviar na instancia do SyncLogger ou do AsyncLogger, atributo "pattern" ao novo padrão desejado.

Muito bem, configuramos nossa instancia de log com todas as possibilidades, para realizar o log, basta então chamar a função de log:

sync_logger.log(level=Level.INFO,message="MongoDB connection",transaction="start db connection")

Ou então:

async_logger.async_log(level=Level.INFO,message="MongoDB connection",transaction="end dbconnection")

No metodo log podemos enviar como parâmetro:

class.log:
  - message = "[MENSAGEM_QUE_DESEJA_GRAVAR]"
  - transaction = "[TAG_QUE_IDENTIFICA_O_ESTADO_DA_TRANSACAO]"
  - level = Level.INFO | .CRITICAL | .DEBUG | .ERROR | .FATAL | .NOTICE | .TRACE | WARNING | UNSET
  - error = Exception("um tipo qualquer de exceção")

Overview

Significado e casos de uso de cada modulo:

Extension:

O modulo Extension, é um enumerator que possui todos os formatos de arquivos que a biblioteca consegue processar. À medida que mais formatos forem adicionados, serão incluidos nesse modulo.

Extension:
  - LOG
  - TXT
  - JSON

Level:

Já no modulo Level, que também é um enumerator, expomos os diversos níveis de log com que o heimdall-logger trabalha.

Level:
  - CRITICAL
  - DEBUG
  - ERROR
  - FATAL
  - INFO
  - NOTICE
  - TRACE
  - WARNING
  - UNSET

FileDataLog:

O módulo FileDataLog, permite especificar qual extensão de arquivo de log, gostaríamos que nossos dados fossem gravados, permite ainda que especifiquemos qual o nome do arquivo de log e em qual diretório este arquivo será gravado. Este módulo poderá ou não ser passado de acordo com o contexto de utilização dos módulos SyncLogger e AsyncLogger.

log_file_data = FileDataLog(
    log_extension=Extension.JSON,
    log_name="logfile",
    log_path=""
)

ApiSendLog:

O módulo ApiSendLog, permite realizar o log das informações, realizando uma chamada via protocolo http, na qual enviará a um recurso qualquer, as informações de log, de forma síncrona ou assíncrona. Para que tal ação seja possível, você deverá informar ao modulo, qual verbo http sua api utiliza, qual a rota, e caso exista algum parâmetro de cabeçalho, tal como um token de autorização, poderá ser enviado em api_headers.

api_send_log = ApiSendLog(
    api_route="",
    api_method="",
    api_headers={}
)

SyncLogger e AsyncLogger:

Com o heimdall-logger, é possível realizar logs de forma síncrona (SyncLogger) ou assíncrona (AsyncLogger), você tem liberdade para utilizar ambos os modelos de acordo com o contexto o qual seu sistema se encontra, para isso, na instância do método você deverá informar o nome do projeto (este é um parâmetro obrigatório), poderá informar um provedor de escrita de arquivos e, também de envio de dados para uma api a seu critério. Caso, nosso padrão de log não atenda sua necessidade, você poderá customizar este padrão e enviar um template-string com o padrão desejado.

sync_logger = SyncLogger(
    project_name="",
    file_data=object,
    api_callback=object,
    pattern=""
)

async_logger = AsyncLogger(
    project_name="",
    file_data=object,
    api_callback=object,
    pattern=""
)