Awesome

DataLogger

DataLogger foi projetado para ser uma biblioteca simples de log com suporte a vários providers.

DataLogger was designed to be a simple logging library with support for multiple providers.

To see this read-me file in English, please click here: README

Support: developer.dlio@gmail.com

⚙️ Instalação

Para instalar em seu projeto usando boss:

$ boss install github.com/dliocode/datalogger

Instalação Manual

Adicione as seguintes pastas ao seu projeto, em Project > Options > Delphi Compiler > Search path

../src/Core
../src/Providers

📌 Índice

• Como usar
• Providers
• Dependências
• Exemplos
  • Uso Padrão
  • Criar uma nova instância do DataLogger
  • DataLogger Simple
  • Gerar log para um Provider Específico
  • Custom
  • Formato do Log
    • LogFormat
    • Como definir um formato
    • Como definir um formato em providers específicos
    • Como mudar o formato do TimeStamp
    • Tipos de Tag para criar o formato do log
  • Level
  • Disable Level
  • Only Level
  • Log Exception
  • Max Retries
  • IgnoreLogFormat
  • Name
  • LiveMode
  • Transaction

Como usar

Existem duas maneiras diferentes de usar o DataLogger: Diretamente pelo Logger ou instanciando seu próprio TDataLogger.

Samples

O primeiro destina-se apenas a ser um log compartilhado conveniente para ser usado em todo o seu aplicativo, se você escolher.

• Uses necessária:

uses DataLogger;

Providers

Um provider serve essencialmente para armazenar seus logs. Cada instância de um TDataLogger pode ter vários providers configurados.

Aqui temos uma lista com 56 providers disponíveis:

Dependências

Essas dependências se dá quando utilizado alguns providers

Informações Extras

Plataforma Android:

É necessário a permissão ACCESS_WIFI_STATE: Utilizado para capturar o MAC Address do dispositivo.

Exemplos

Uso Padrão

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  Logger
    .Trace('My Trace')
    .Debug('My Debug')
    .Info('My Info')
    .Warn('My Warn')
    .Error('My Error')
    .Success('My Success')
    .Fatal('My Fatal')
    .Custom('Custom Level', 'My Custom')
    ;

  // or

  Logger
    .T('My Trace')
    .D('My Debug')
    .I('My Info')
    .W('My Warn')
    .E('My Error')
    .S('My Success')
    .F('My Fatal')
    .C('Custom Level', 'My Custom')
    ;

  Readln;

end.

Criar uma nova instância do DataLogger

uses
  DataLogger,
  DataLogger.Provider.Console;

var
  LCustomLogger: TDataLogger;
begin
  LCustomLogger := TDataLogger.Builder;
  LCustomLogger.AddProvider(TProviderConsole.Create);

  LCustomLogger
    .Trace('My Trace')
    .Debug('My Debug')
    .Info('My Info')
    .Warn('My Warn')
    .Error('My Error')
    .Success('My Success')
    .Fatal('My Fatal')
    .Custom('Custom Level', 'My message with custom level');
  Readln;
end.

DataLogger Simple

uses
  DataLogger,
  DataLogger.Simple,
  DataLogger.Provider.Console;

begin
  // Defini o provider
  Logger.AddProvider(TProviderConsole.Create);

  //Defini no DataloggerSimple a instância do log a ser utilizado
  TDataLoggerSimple.SetDataLogger(Logger);

  // Só usar o modo simples;
  Trace('My message Trace');
  Debug('My message debug');
  Info('My message info');
  Success('My message success');
  Warn('My message warn');
  Error('My message error');
  Fatal('My message fatal');
  Custom('My Type', 'My message custom');

  Readln;
end.

Custom

O Custom é a forma de definir dar o nome para o seu próprio level.

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  Logger.Custom('Custom Level', 'My message with custom level!');

  // Output: 2022-12-01 09:00:05.500 [Custom Level] My message with custom level!	

  Readln;
end.

Formato do Log

Formato de log padrão:

${timestamp} [TID ${thread_id}] [PID ${process_id}] [SEQ ${sequence}] [${level}] [${tag}] ${message}

LogFormat

Existe algumas constantes que podem ser utilizadas:

TLoggerFormat.LOG_NAME = '${name}';
TLoggerFormat.LOG_SEQUENCE = '${sequence}';
TLoggerFormat.LOG_TIMESTAMP = '${timestamp}';
TLoggerFormat.LOG_TIMESTAMP_ISO8601 = '${timestamp_iso8601}';
TLoggerFormat.LOG_TIMESTAMP_UNIX = '${timestamp_unix}';
TLoggerFormat.LOG_THREADID = '${thread_id}';
TLoggerFormat.LOG_PROCESSID = '${process_id}';
TLoggerFormat.LOG_LEVEL = '${level}';
TLoggerFormat.LOG_LEVEL_VALUE = '${level_value}';
TLoggerFormat.LOG_TAG = '${tag}';
TLoggerFormat.LOG_MESSAGE = '${message}';

TLoggerFormat.LOG_APPNAME = '${app_name}';
TLoggerFormat.LOG_APPPATH = '${app_path}';
TLoggerFormat.LOG_APPVERSION = '${app_version}';
TLoggerFormat.LOG_APPSIZE = '${app_size}';

TLoggerFormat.LOG_COMPUTERNAME = '${computer_name}';
TLoggerFormat.LOG_USERNAME = '${username}';
TLoggerFormat.LOG_OSVERSION = '${os_version}';
TLoggerFormat.LOG_IP_LOCAL = '${ip_local}';
TLoggerFormat.LOG_MAC_ADDRESS = '${mac_address}';

Como definir um formato

Sempre defina o formato de log após adicionar todos os providers, dessa forma ele será aplicado em todos.

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Usando constant
  // Logger.SetLogFormat(Format('%s [%s] %s', 
  //   [TLoggerFormat.LOG_TIMESTAMP, TLoggerFormat.LOG_LEVEL,  TLoggerFormat.LOG_MESSAGE])
  // );

  // Gerando os logs
  Logger.Info('Minha mensagem no Log do tipo INFO');
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 2022-12-01 09:00:05.500 [INFO] Minha mensagem no Log do tipo INFO
  // Output: 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

Como definir um formato em providers específicos

• É possível definir várias configurações específicas em cada provider separado.

uses
  DataLogger,
  DataLogger.Provider.Console,
  DataLogger.Provider.TextFile;

begin
  // Formato do console '${timestamp} [${level}] ${message}'
  Logger.AddProvider(TProviderConsole.Create.SetLogFormat('${timestamp} [${level}] ${message}'));

  // Formato do text file '${timestamp} - ${message}'  
  Logger.AddProvider(TProviderTextFile.Create.SetLogFormat('${timestamp} - ${message}'));  

  // Gerando os logs
  Logger.Info('Minha mensagem no Log do tipo INFO');
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output Console: 
  // 2022-12-01 09:00:05.500 [INFO] Minha mensagem no Log do tipo INFO
  // 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  // Output TextFile: 
  // 2022-12-01 09:00:05.500 - Minha mensagem no Log do tipo INFO
  // 2022-12-01 09:00:05.600 - Minha mensagem no Log do tipo ERROR 

  Readln;
end.

Como mudar o formato do TimeStamp

• Formato de TimeStamp padrão: yyyy-mm-dd hh:mm:ss.zzz

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do Timestamp
  Logger.SetFormatTimestamp('dd/mm/yyyy hh:mm:ss')

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Usando constant
  // Logger.SetLogFormat(Format('%s [%s] %s', 
  //   [TLoggerFormat.LOG_TIMESTAMP, TLoggerFormat.LOG_LEVEL,  TLoggerFormat.LOG_MESSAGE])
  // );

  // Gerando os logs
  Logger.Info('Minha mensagem no Log do tipo INFO');
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 01/12/2022 09:00:05 [INFO] Minha mensagem no Log do tipo INFO
  // Output: 01/12/2022 09:00:05 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

Tipos de Tag para criar o formato do log

• Comum

// Exibe o nome do log. ex: Logger.SetName('SERVICE_REMOTE')
TLoggerFormat.LOG_NAME;

// Exibe a sequencia que o log foi gerado.
TLoggerFormat.LOG_SEQUENCE;

// Exibe a data e hora que foi gerado, usado o SetFormatTimestamp
TLoggerFormat.LOG_TIMESTAMP;

// Exibe a data e hora que foi gerado, no formato ISO8601.
TLoggerFormat.LOG_TIMESTAMP_ISO8601;

// Exibe a data e hora que foi gerado, no formato UNIX.
TLoggerFormat.LOG_TIMESTAMP_UNIX;

// Exibe o Id da thread que foi gerado o log.
TLoggerFormat.LOG_THREADID;

// Exibe o id do processo do app.
TLoggerFormat.LOG_PROCESSID;

// Exibe o level do log, sendo eles: TRACE / DEBUG / INFO / SUCCESS / WARN / ERROR / FATAL
TLoggerFormat.LOG_LEVEL;

// Exibe o level do log no formato numérico, sendo eles: 1=TRACE / 2=DEBUG / 3=INFO / 4=SUCCESS / 5=WARN / 6=ERROR / 7=FATAL / 8=CUSTOM
TLoggerFormat.LOG_LEVEL_VALUE;

// Exibe a tag do log, essa informação é preenchida a após a mensagem; Ex: Logger.Debug('Minha mensagem','Minha Tag');
TLoggerFormat.LOG_TAG;

// Exibe a mensagem do log, sem essa tag a mensagem não é exibida. Ex: Logger.Debug('Minha mensagem');
TLoggerFormat.LOG_MESSAGE;

• Especiais:

// Exibe o nome do app.
TLoggerFormat.LOG_APPNAME;

// Exibe a versão do app.
TLoggerFormat.LOG_APPVERSION;

// Exibe o diretório do app.
TLoggerFormat.LOG_APPPATH

// Exibe o tamanho do app em MB.
TLoggerFormat.LOG_APPSIZE

// Exibe o nome do computador.
TLoggerFormat.LOG_COMPUTERNAME;

// Exibe o nome do usuário do Sistema Operacional.
TLoggerFormat.LOG_USERNAME

// Exibe as informações do Sistema Operacional.
TLoggerFormat.LOG_OSVERSION

// Exibe o IP Local.
TLoggerFormat.LOG_IP_LOCAL

SetLevel

É possível mostrar somente os logs a partir de um level definido, com base no TLoggerLevel.

SetLevel valor padrão = TLoggerLevel.All

TLoggerLevel

• Quando definido um level, será exibido somente a opção escolhida e seus tipos superiores.
• Ex: Logger.SetLevel(TLoggerLevel.Warn); - Será registrado somente os logs com o tipo Warn / Error / Fatal / Custom.

  TLoggerLevel.All = 'Utilizado para operações internas'
  TLoggerLevel.Trace = 'Level 1'
  TLoggerLevel.Debug = 'Level 2'
  TLoggerLevel.Info = 'Level 3'
  TLoggerLevel.Success = 'Level 4'
  TLoggerLevel.Warn = 'Level 5'
  TLoggerLevel.Error = 'Level 6'
  TLoggerLevel.Fatal = 'Level 7'
  TLoggerLevel.Custom = 'Level 8'

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Definindo o Level
  Logger.SetLevel(TLoggerLevel.Warn);

  // Gerando os logs
  Logger.Info('Minha mensagem no Log do tipo INFO');
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

Disable Level

É possível desabilitar alguns levels do log, com base no TLoggerLevel.

SetDisableLevel valor padrão = []

SetDisableLevel

• Quando desabilitado será exibido somente as opções que não estão desabilitadas.
• Ex: Logger.SetDisableLevel([TLoggerLevel.Info, TLoggerLevel.Warn]); - Será registrado somente os logs com o tipo Tracer / Debug / Success / Error / Fatal / Custom.

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Definindo o DisableLevel
  Logger.SetDisableLevel([TLoggerLevel.Info, TLoggerLevel.Warn]);

  // Gerando os logs
  Logger.Debug('Minha mensagem no Log do tipo DEBUG');
  Logger.Info('Minha mensagem no Log do tipo INFO');
  Logger.Warn('Minha mensagem no Log do tipo WARN');  
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 
  // 2022-12-01 09:00:05.500 [DEBUG] Minha mensagem no Log do tipo DEBUG  
  // 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

Only Level

É possível mostrar somente alguns levels do log, com base no TLoggerLevel.

SetOnlyLevel valor padrão = [TLoggerLevel.All]

SetOnlyLevel

• Quando definido será exibido somente as opções registradas.
• Ex: Logger.SetOnlyLevel([TLoggerLevel.Error]); - Será registrado somente os logs com o tipo Error.

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Definindo o OnlyLevel
  Logger.SetOnlyLevel([TLoggerLevel.Error]);

  // Gerando os logs
  Logger.Debug('Minha mensagem no Log do tipo DEBUG');
  Logger.Info('Minha mensagem no Log do tipo INFO');
  Logger.Warn('Minha mensagem no Log do tipo WARN');  
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 
  // 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

Log Exception

É possível capturar exceções geradas pelos providers

SetLogException valor padrão = nil

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Definindo o LogException
  Logger.SetLogException(
    procedure(const Sender: TObject; const LogItem: TLoggerItem; const E: Exception; var RetriesCount: Integer)
    begin 
      // Sender - Provider que gerou a exceção, para visualizar - Sender.ClassName

      // LogItem - Contém todas as informações do log

      // E - Contém as informações da exceção

      // RetriesCount - Contém o número da tentativa realizada
      // Caso seja alterado o valor para -1, o processo é interrompido
    end
  );

  // Gerando o log
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 
  // 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

Max Retries

É possível definir o número de tentativas que o Provider deve tentar ao salvar o log.

SetMaxRetries valor padrão = 5

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Definindo o máximo de tentativas
  Logger.SetMaxRetries(5);

  // Gerando o log
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 
  // 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

IgnoreLogFormat

É possível ignorar o formato do LogFormat e salvar todos os dados gerados pelo DataLogger;

SetIgnoreLogFormat({1}, {2}, {3}, {4});
```delphi  

```delphi  
  Parâmetros:
    {1} = (Boolean) = Defini se deve ignorar o LogFormat.
    {2} = (string) = Defini qual texto vai fazer a separação das informações, semelhante ao CSV.
    {3} = (Boolean) = Defini se deve mostrar as palavras chaves de cada valor.
    {4} = (string) = Defini qual texto deve separar a palavra chave do valor.

  Logger.SetIgnoreLogFormat(True, '|', True, ' -> '); 

  {palavra_chave}           = "timestamp"
  {palavra_chave_separador} = " -> "
  {valor}                   = "2022-09-15T14:39:38.896-03:00"
  {separator}               = " | " 
  
  // output timestamp -> 2022-09-15T14:39:38.896-03:00 | timestamp_format -> 2022-09-15 14:39:38.896                 

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Ignorando o log format
  Logger.SetIgnoreLogFormat(True, '|', True, ' -> ');

  // Gerando o log
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 
  // timestamp -> 2022-09-15T14:39:38.896-03:00 | timestamp_format -> 2022-09-15 14:39:38.896 | name ->  | sequence -> 1 | thread_id -> 3804 | level -> Trace | level_value -> 1 | tag ->  | message -> My Trace | app_name -> ProviderTextFile | app_version -> 1.0.0.0 | app_path -> C:\Github\DataLogger\Samples\TextFile\Win32\Debug | app_size -> 13,24 MB | computer_name -> DESKTOP-7RP1H3K | username -> danil | os_version -> Windows 10 (Version 21H2, OS Build 19044.1889, 64-bit Edition) | process_id -> 13608 | ip_local -> 192.168.56.1

  Readln;
end.

Name

É possível definir um nome para o DataLogger que pode ser exibido no registro do log. Esse nome pode ser utilizado para diferenciar o DataLogger quando a mais de uma instância.

SetName valor padrão = ''

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${name} ${timestamp} [${level}] ${message}');

  // Definindo o name
  Logger.SetName('MyLogger');

  // Gerando o log
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 
  // MyLogger 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

LiveMode

É possível salvar os logs em tempo real, de forma que a próxima instrução do seu código só vai continuar depois que o log for salvo!

Atualmente os logs são registrados em memória e depois ele é salvo sem travar a aplicação.

SetLiveMode valor padrão = false

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create);

  // Definindo o formato do log
  Logger.SetLogFormat('${name} ${timestamp} [${level}] ${message}');

  // Definindo o LiveMode
  Logger.SetLiveMode(True);

  // Gerando o log
  Logger.Error('Minha mensagem no Log do tipo ERROR');
  
  // Output: 
  // MyLogger 2022-12-01 09:00:05.600 [ERROR] Minha mensagem no Log do tipo ERROR  

  Readln;
end.

Transaction

É possível trabalhar com Transaction, da mesma forma que é usado em outros componentes com conexão de banco de dados.

A utilização deste procedimento pode ser aplicado a seguinte situação;

Vamos contar uma pequena história:

Temos uma procedure que está fazendo uma execução, em cada etapa é gerado várias informações de log, por costume sempre salvamos essas informações, isso faz com que o nosso arquivo de texto por exemplo fique muito grande demais. <br /> Agora imagina poder salvar os dados somente se houve algum erro durante a execução ou quando necessário realmente salvar os dados.

Como habilitar

A ativação do uso da Transaction deve ser feita por Provider com a função UseTransaction(True).

Ex: Logger.AddProvider(TProviderConsole.Create.UseTransaction(True));

StartTransaction

Inicia uma nova transação.

CommitTransaction

Confirma o registra de todos os logs na transação.

RollbackTransaction

Cancela todos os logs gerados na transação.

Exemplo com Transação Simples

Sample com Transaction

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create.UseTransaction(True));

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Iniciando a transaction
  Logger.StartTransaction;

  Writeln('Iniciou a transaction');

  // Gerando o log
  Logger.Info('Minha mensagem no Log do tipo INFO 1 ');
  Logger.Info('Minha mensagem no Log do tipo INFO 2');
  Logger.Info('Minha mensagem no Log do tipo INFO 3');
  Logger.Info('Minha mensagem no Log do tipo INFO 4');
  Logger.Info('Minha mensagem no Log do tipo INFO 5');
  Logger.Info('Minha mensagem no Log do tipo INFO 6');
  Logger.Info('Minha mensagem no Log do tipo INFO 7');
  Logger.Info('Minha mensagem no Log do tipo INFO 8');
  Logger.Info('Minha mensagem no Log do tipo INFO 9');

  Writeln('Terminou os Logs');

  // Fazendo o commit
  Logger.CommitTransaction;
  Writeln('Fez os commits');

  Readln;
end.

Exemplo com Transation Aninhada

Sample com Transaction Aninhada

As transactions aninhadas dá a possibilidade de um gerenciamento maior na hora de salvar as informações.

• Apenas uma observação deve ser lembrada, só será salvo o registro final se houve commit da transação pai, ou seja, da transação que iniciou todo processo; <br /> Caso a transação pai, tenha feito rollback, as transações filhas que foram feitas commit serão ignoradas!

uses
  DataLogger,
  DataLogger.Provider.Console;

begin
  Logger.AddProvider(TProviderConsole.Create.UseTransaction(True));

  // Definindo o formato do log
  Logger.SetLogFormat('${timestamp} [${level}] ${message}');

  // Iniciando a transaction
  Logger.StartTransaction;
  try
    // Gerando o log
    Logger.Info('Minha mensagem no Log do tipo INFO 1 ');
    Logger.Info('Minha mensagem no Log do tipo INFO 2');
    Logger.Info('Minha mensagem no Log do tipo INFO 3');
    Logger.Info('Minha mensagem no Log do tipo INFO 4');

    // Iniciando 2 transaction
    Logger.StartTransaction;
    try
      Logger.Info('Minha mensagem no Log do tipo INFO 5');
      Logger.Info('Minha mensagem no Log do tipo INFO 6');
    finally
      // fazendo Rollback da segunda transaction
      Logger.RollbackTransaction;
    end;

    Logger.Info('Minha mensagem no Log do tipo INFO 7');
    Logger.Info('Minha mensagem no Log do tipo INFO 8');
    Logger.Info('Minha mensagem no Log do tipo INFO 9');
  finally
    // Fazendo o commit
    Logger.CommitTransaction;
  end;

  Readln;
end.