Logging V2 for both MQL4 and MQL5 - biblioteca para MetaTrader 5

Classe CDebugLogger V2: Um utilitário de registro abrangente para MQL4/5

A classe CDebugLogger é um utilitário de registro poderoso e flexível, projetado especificamente para ambientes MQL4/5. É uma ferramenta essencial para os desenvolvedores que precisam monitorar, depurar e rastrear o comportamento de seus aplicativos com precisão.

Nesta nova versão da classe CDebugLogger, introduzi vários aprimoramentos para aumentar sua funcionalidade e versatilidade. Esses aprimoramentos incluem um mecanismo de debounce para evitar o registro excessivo em sistemas orientados por eventos, como OnTick, OnTimer e OnChartEvent, bem como novas opções de filtragem e silenciamento para ajudar os desenvolvedores a se concentrarem nas entradas de registro mais relevantes.

Decidi lançar essa versão atualizada como uma base de código separada para dar aos usuários a liberdade de escolher a implementação que melhor atenda às suas necessidades. Quer você prefira a versão original ou esta aprimorada, agora você tem a opção de selecionar a ferramenta de registro que se adapta ao seu fluxo de trabalho e aos requisitos do projeto.

A seguir, exploramos os principais recursos e capacidades dessa classe aprimorada.

Principais recursos

• Vários níveis de registro: A classe CDebugLogger oferece suporte ao registro em log em diferentes níveis de importância, incluindo INFO, WARNING, ERROR e DEBUG. Isso permite que os desenvolvedores filtrem e se concentrem em mensagens de importância específica.
• Inclusão de carimbo de data/hora: Os desenvolvedores podem optar por incluir carimbos de data/hora em suas mensagens de registro, com formatos personalizáveis. Esse recurso é fundamental para rastrear a hora exata dos eventos e depurar problemas sensíveis ao tempo.
• Registro em log de arquivos: A classe oferece suporte robusto para registro em log de arquivos. Os desenvolvedores podem ativar ou desativar o registro em arquivo, especificar o caminho do arquivo de registro e escolher se desejam salvar os registros em uma pasta comum. Além disso, os registros podem ser salvos em um formato CSV, o que facilita a análise e a análise.
• Informações contextuais: Para aumentar a clareza das mensagens de registro, a classe CDebugLogger permite a inclusão de assinaturas de funções, nomes de arquivos e números de linhas. Essas informações contextuais ajudam a identificar o local exato dos problemas no código.
• Palavras-chave silenciosas: Um recurso exclusivo dessa classe é a capacidade de silenciar os registros que contêm palavras-chave específicas. Isso é particularmente útil para evitar que informações sensíveis, como senhas ou dados confidenciais, sejam registradas.
• Filtrar palavras-chave: Outro recurso exclusivo dessa classe é a capacidade de filtrar os logs que contêm palavras-chave específicas. Isso é particularmente útil para a depuração, concentrando-se apenas nos registros que são relevantes para problemas específicos. Os desenvolvedores podem restringir a saída de log para incluir apenas mensagens que contenham determinados termos, facilitando a identificação e a solução de problemas relacionados a esses termos sem serem sobrecarregados por entradas de log não relacionadas.
  
• Rejeitar o registro em log para eventos: Para evitar spam de registro e registro excessivo em sistemas orientados por eventos (como OnTick, OnTimer e OnChartEvent), a classe CDebugLogger inclui um mecanismo de debouncing. Esse recurso garante que entradas de registro repetidas do mesmo evento sejam temporariamente suprimidas, permitindo que apenas alterações únicas ou significativas sejam registradas. Isso é particularmente útil para reduzir o ruído nos registros e evitar a degradação do desempenho em ambientes de eventos de alta frequência.
  

Exemplo de uso

Abaixo está um exemplo de como inicializar e usar a classe CDebugLogger:

// Inicialize o registrador com o registro de nível INFO em um arquivo
CDebugLogger logger(INFO, true, "log.txt", true, TIME_DATE | TIME_MINUTES, false, true, true, true);

// Registre uma mensagem simples
logger.Log(INFO, "This is an info message");

// Silenciar uma palavra-chave
logger.AddSilentKeyword("password");

// Registre uma mensagem que será silenciada
logger.Log(INFO, "User entered password: 1234");

// Ativar o registro de arquivos
logger.EnableFileLogging(true, "debug.log", false);

// Remover uma palavra-chave silenciada
logger.RemoveSilentKeyword("password");

// Registre uma mensagem após remover a palavra-chave da lista de silêncio
logger.Log(INFO, "User entered password: 1234");

// Adicione uma palavra-chave para filtrar os registros
logger.AddFilterKeyword("success");

// Registre uma mensagem que será filtrada
logger.Log(INFO, "Operation failed");

// Registre uma mensagem que passará pelo filtro
logger.Log(INFO, "Operation successful");

// Remover uma palavra-chave do filtro
logger.RemoveFilterKeyword("success");

// Inicializar usando a função genérica Log
logging.Initialize(WARNING, true, "warnings.log", true, TIME_SECONDS, true, false, true, true);

// Registre um aviso usando a função genérica Log
Log(WARNING, "This is a warning message");

Exemplo de script

Para utilizar a classe CDebugLogger em um script, basta incluir a biblioteca necessária no início do arquivo, conforme mostrado abaixo:

//--- É importante incluir esse arquivo de cabeçalho antes de todos os outros
#include <Logging.mqh>  


//+------------------------------------------------------------------+
//| Função de início do programa de script|
//+------------------------------------------------------------------+
void OnStart()
{
   //--- Inicialize o registrador com o nível INFO, registrando em um arquivo
   //--- Incluindo registros de data e hora e salvando no formato CSV
   int log_options = 0; // NOME DO ARQUIVO | LINHA | FUNCSIG;
   logging.Initialize(INFO, true, "example_log.txt", true, TIME_DATE | TIME_MINUTES | TIME_SECONDS, false, log_options, true);

   //--- Registre uma mensagem informativa simples
   Log(INFO, "Script started successfully.");

   //--- Registre uma mensagem de aviso
   Log(WARNING, "This is a warning message.");

   //--- Registre uma mensagem de erro
   Log(ERROR, "This is an error message.");

   //--- Registre uma mensagem de depuração
   Log(DEBUG, "This is a debug message for debugging purposes.");

   //--- Adicione uma palavra-chave para silenciar os registros que contenham 'password'
   logging.AddSilentKeyword("password");

   //--- Tentativa de registrar uma mensagem contendo a palavra-chave silenced
   Log(INFO, "User entered password: 12348"); // Essa mensagem será silenciada

   //--- Remover a palavra-chave silenciada
   logging.RemoveSilentKeyword("password");

   //--- Registre a mensagem novamente, agora ela será registrada
   Log(INFO, "User entered password: 1234");

   //--- Use a função genérica Log para registrar uma mensagem
   Log(INFO, "This message is logged using the generic Log function.");

   //--- Use a macro Print para registrar uma mensagem no nível INFO
   Print("This message is logged using the Print macro.");

   //--- Demonstrar o registro em log com diferentes combinações de opções
   logging.Initialize(INFO, true, "log_with_options.txt", true, TIME_DATE | TIME_MINUTES, false, FILENAME | LINE, true);
   Log(INFO, "This log includes only the file name and line number.");

   logging.Initialize(INFO, true, "log_with_funcsig.txt", true, TIME_DATE | TIME_MINUTES | TIME_SECONDS, false, FUNCSIG, true);
   Log(INFO, "This log includes only the function signature.");

   logging.Initialize(INFO, true, "log_custom_order.txt", true, TIME_MINUTES, false, LINE | FILENAME | FUNCSIG, true);
   Log(INFO, "This log includes line number, file name, and function signature in a custom order.");

   //--- Adicione uma palavra-chave para filtrar os registros que contêm "important
   logging.AddFilterKeyword("important");

   //--- Registre algumas mensagens para demonstrar o filtro
   Log(INFO, "This is an important message."); // Essa mensagem ficará visível
   Log(INFO, "This is a regular message.");    // Essa mensagem não será visível

   //--- Remova a palavra-chave filter para mostrar todos os registros
   logging.RemoveFilterKeyword("important");

   //--- Registre uma mensagem final indicando o fim do script
   Log(INFO, "Script execution completed.");
}

Exemplo de saída CSV:

Timestamp,Level,Message
"2024.09.01 18:31:44","INFO","Script started successfully."
"2024.09.01 18:31:44","WARNING","This is a warning message."
"2024.09.01 18:31:44","ERROR","This is an error message."
"2024.09.01 18:31:44","DEBUG","This is a debug message for debugging purposes."
"2024.09.01 18:31:44","INFO","User entered password: 1234"
"2024.09.01 18:31:44","INFO","This message is logged using the generic Log function."
"2024.09.01 18:31:44","INFO","This message is logged using the Print macro."

Timestamp,Level,Message,Filename,Line
"2024.09.01 18:31","INFO","This log includes only the file name and line number.","Logging.mq5","135"

Timestamp,Level,Message,Funcsig
"2024.09.01 18:31:44","INFO","This log includes only the function signature.","void OnStart()"

Timestamp,Level,Message,Filename,Line,Funcsig
"18:31","INFO","This log includes line number, file name, and function signature in a custom order.","Logging.mq5","141","void OnStart()"
"18:31","INFO","This is an important message.","Logging.mq5","147","void OnStart()"
"18:31","INFO","Script execution completed.","Logging.mq5","154","void OnStart()"

#include <Logging.mqh>

//+------------------------------------------------------------------+
//| Função de inicialização especializada|
//+------------------------------------------------------------------+
int OnInit()
{  int log_options = LINE | FUNCSIG; // FILENAME | LINE | FUNCSIG; ou 0
   logging.Initialize(INFO, false, "example_log.txt", true, TIME_DATE | TIME_MINUTES | TIME_SECONDS, false, log_options, false);
//--- criar cronômetro
   EventSetMillisecondTimer(1);
//---
   return(INIT_SUCCEEDED); }
//+------------------------------------------------------------------+
//| Função de desinicialização de especialista|
//+------------------------------------------------------------------+
void OnDeinit(const int reason)
{
//--- destruir o cronômetro
   EventKillTimer(); }

int counter = 0;
datetime last_time = 0; //--- Armazena a última vez que o contador foi atualizado
//+------------------------------------------------------------------+
//| Função de cronômetro|
//+------------------------------------------------------------------+
void OnTimer()
{  logging.BeginEvent(); //--- Iniciar um novo evento
   Log(INFO, "Sample message");
   Log(INFO, "Another message");
   Log(INFO, "Sample message"); 
//--- Obter a hora atual
   datetime current_time = TimeLocal();
//--- Verifique se pelo menos 2 segundos se passaram desde a última atualização do contador
   if (current_time - last_time >= 2)
   {  //--- Atualizar o contador
      counter++;
      //--- Atualizar a última vez
      last_time = current_time;
      //--- Registre a mensagem com o novo valor do contador
      Log(INFO, "Counter value: " + IntegerToString(counter));
      //--- Você também pode registrar outra mensagem
      Log(INFO, "Updated after 2 seconds"); }
   else
   {  //--- Registre uma mensagem indicando que o temporizador está ativo, mas o contador não foi alterado
      Log(INFO, "Timer active but counter unchanged"); } }

2024.09.22 13:00:29.589 test_logging (EURUSD,H1)        2024.09.22 13:00:29 Line: 43 Function: void OnTimer() [INFO] Sample message
2024.09.22 13:00:29.589 test_logging (EURUSD,H1)        2024.09.22 13:00:29 Line: 44 Function: void OnTimer() [INFO] Another message
2024.09.22 13:00:29.589 test_logging (EURUSD,H1)        2024.09.22 13:00:29 Line: 45 Function: void OnTimer() [INFO] Sample message
2024.09.22 13:00:29.589 test_logging (EURUSD,H1)        2024.09.22 13:00:29 Line: 55 Function: void OnTimer() [INFO] Counter value: 1
2024.09.22 13:00:29.589 test_logging (EURUSD,H1)        2024.09.22 13:00:29 Line: 57 Function: void OnTimer() [INFO] Updated after 2 seconds
2024.09.22 13:00:29.605 test_logging (EURUSD,H1)        2024.09.22 13:00:29 Line: 60 Function: void OnTimer() [INFO] Timer active but counter unchanged
2024.09.22 13:00:31.001 test_logging (EURUSD,H1)        2024.09.22 13:00:31 Line: 55 Function: void OnTimer() [INFO] Counter value: 2
2024.09.22 13:00:31.001 test_logging (EURUSD,H1)        2024.09.22 13:00:31 Line: 57 Function: void OnTimer() [INFO] Updated after 2 seconds
2024.09.22 13:00:31.017 test_logging (EURUSD,H1)        2024.09.22 13:00:31 Line: 60 Function: void OnTimer() [INFO] Timer active but counter unchanged
2024.09.22 13:00:33.001 test_logging (EURUSD,H1)        2024.09.22 13:00:33 Line: 55 Function: void OnTimer() [INFO] Counter value: 3
2024.09.22 13:00:33.001 test_logging (EURUSD,H1)        2024.09.22 13:00:33 Line: 57 Function: void OnTimer() [INFO] Updated after 2 seconds
2024.09.22 13:00:33.016 test_logging (EURUSD,H1)        2024.09.22 13:00:33 Line: 60 Function: void OnTimer() [INFO] Timer active but counter unchanged

Conclusão

A classe CDebugLogger é uma ferramenta inestimável para qualquer desenvolvedor de MQL4/5. Com sua ampla gama de recursos personalizáveis, ela permite o registro e o monitoramento precisos de aplicativos, facilitando a depuração e o acompanhamento do desempenho do aplicativo. Quer você precise de um simples registro de mensagens ou de informações contextuais detalhadas, a classe CDebugLogger oferece uma solução confiável e eficiente, adaptada às suas necessidades de desenvolvimento.

Para obter mais informações sobre a classe CDebugLogger ou para explorar outras ferramentas e soluções avançadas, visite a StormWave Technologies.