docs/logging_system.md

Sistema de Logging Avançado

Visão Geral

O sistema de logging avançado foi projetado para fornecer monitoramento abrangente e análise detalhada de todas as operações do sistema de análise financeira. Utiliza SQLite3 para armazenamento persistente e oferece uma interface web para visualização e análise dos logs.

Arquitetura do Sistema

Componentes Principais

1. DatabaseLogger (src/core/database_logger.py)

   • Gerenciador principal do sistema de logging
   • Conexão e operações com banco SQLite3
   • Armazenamento estruturado de logs, métricas e eventos

2. Decoradores de Logging (src/utils/logging_decorators.py)

   • Decoradores para logging automático de funções
   • Gerenciador de contexto para blocos de código
   • Utilitários para logging rápido

3. Visualizador de Logs (src/ui/log_viewer.py)

   • Interface web para visualização de logs
   • Filtros avançados e busca
   • Estatísticas e gráficos
   • Exportação de dados

Estrutura do Banco de Dados

Tabela: logs

CREATE TABLE logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT NOT NULL,
    level TEXT NOT NULL,
    category TEXT NOT NULL,
    message TEXT NOT NULL,
    function_name TEXT,
    file_name TEXT,
    line_number INTEGER,
    execution_time REAL,
    metadata TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Tabela: performance_metrics

CREATE TABLE performance_metrics (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT NOT NULL,
    metric_name TEXT NOT NULL,
    metric_value REAL NOT NULL,
    unit TEXT,
    category TEXT,
    metadata TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Tabela: system_events

CREATE TABLE system_events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT NOT NULL,
    event_type TEXT NOT NULL,
    event_name TEXT NOT NULL,
    description TEXT,
    severity TEXT NOT NULL,
    metadata TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Níveis de Log

• DEBUG: Informações detalhadas para depuração
• INFO: Informações gerais sobre operações
• WARNING: Avisos sobre situações potencialmente problemáticas
• ERROR: Erros que não impedem a execução
• CRITICAL: Erros críticos que podem interromper o sistema

Categorias de Log

• SYSTEM: Eventos do sistema (inicialização, configuração)
• API: Chamadas de API e integrações externas
• AI_MODEL: Uso de modelos de IA e análises
• MARKET_ANALYSIS: Análises de mercado e trading
• USER_INTERACTION: Interações do usuário com a interface
• PERFORMANCE: Métricas de performance e otimização
• SECURITY: Eventos relacionados à segurança
• DATABASE: Operações de banco de dados

Uso dos Decoradores

@log_execution

from src.utils.logging_decorators import log_execution
from src.core.database_logger import LogCategory

@log_execution(LogCategory.MARKET_ANALYSIS, log_performance=True)
def analyze_market_data(data):
    # Sua função aqui
    return result

@log_api_call

from src.utils.logging_decorators import log_api_call

@log_api_call("external_api")
def call_external_service(params):
    # Chamada para API externa
    return response

@log_ai_model_usage

from src.utils.logging_decorators import log_ai_model_usage

@log_ai_model_usage("sentiment_analysis")
def analyze_sentiment(text):
    # Análise de sentimento
    return sentiment

Gerenciador de Contexto

from src.utils.logging_decorators import LoggingContext
from src.core.database_logger import LogLevel, LogCategory

with LoggingContext("Processamento de dados", LogLevel.INFO, LogCategory.SYSTEM):
    # Seu código aqui
    process_data()

Logging Rápido

from src.utils.logging_decorators import quick_log
from src.core.database_logger import LogLevel, LogCategory

# Log simples
quick_log("Operação concluída", LogLevel.INFO, LogCategory.SYSTEM)

# Log com metadados
quick_log(
    "Análise finalizada", 
    LogLevel.INFO, 
    LogCategory.MARKET_ANALYSIS,
    metadata={'duration': 1.5, 'symbols': ['BTCUSDT', 'ETHUSDT']}
)

Interface de Visualização

A interface web oferece:

Funcionalidades Principais

• Visualização de Logs: Tabela paginada com filtros
• Estatísticas: Contadores por nível e categoria
• Gráficos: Métricas de performance e timeline
• Busca: Pesquisa por termos específicos
• Exportação: CSV, JSON e HTML

Filtros Disponíveis

• Nível de Log: DEBUG, INFO, WARNING, ERROR, CRITICAL
• Categoria: Todas as categorias disponíveis
• Período: Últimas horas, dias ou intervalo personalizado
• Função: Filtrar por nome da função
• Arquivo: Filtrar por arquivo de origem

Configuração e Inicialização

Inicialização Básica

from src.core.database_logger import DatabaseLogger

# Inicializar logger
db_logger = DatabaseLogger('logs/application.db')

# Log simples
db_logger.log(
    level=LogLevel.INFO,
    category=LogCategory.SYSTEM,
    message="Sistema inicializado"
)

Configuração Avançada

# Log com metadados
db_logger.log(
    level=LogLevel.INFO,
    category=LogCategory.API,
    message="Chamada API realizada",
    function_name="call_api",
    file_name="api_client.py",
    line_number=45,
    execution_time=0.250,
    metadata={'endpoint': '/market/data', 'status': 200}
)

# Métrica de performance
db_logger.log_performance_metric(
    metric_name="response_time",
    metric_value=0.150,
    unit="seconds",
    category="api_performance"
)

# Evento do sistema
db_logger.log_system_event(
    event_type="STARTUP",
    event_name="SERVICE_STARTED",
    description="Serviço de análise iniciado com sucesso",
    severity="INFO"
)

Manutenção e Limpeza

Limpeza Automática

# Remover logs mais antigos que 30 dias
db_logger.cleanup_old_logs(days=30)

# Remover métricas mais antigas que 7 dias
db_logger.cleanup_old_metrics(days=7)

# Remover eventos mais antigos que 90 dias
db_logger.cleanup_old_events(days=90)

Estatísticas do Sistema

# Obter estatísticas gerais
stats = db_logger.get_log_statistics()
print(f"Total de logs: {stats['total_logs']}")
print(f"Logs por nível: {stats['by_level']}")
print(f"Logs por categoria: {stats['by_category']}")

Monitoramento e Alertas

Detecção de Problemas

O sistema automaticamente monitora:

• Erros Críticos: Logs de nível CRITICAL
• Taxa de Erros: Proporção de logs ERROR/WARNING
• Performance: Métricas de tempo de execução
• Disponibilidade: Eventos de sistema

Exemplo de Monitoramento

# Verificar logs de erro nas últimas 24 horas
error_logs = db_logger.get_logs(
    level_filter="ERROR",
    hours_back=24
)

if len(error_logs) > 10:
    # Enviar alerta
    db_logger.log_system_event(
        event_type="ALERT",
        event_name="HIGH_ERROR_RATE",
        description=f"Taxa alta de erros detectada: {len(error_logs)} erros em 24h",
        severity="WARNING"
    )

Integração com a Aplicação

O sistema está totalmente integrado com:

• Análise de Sentimento: Logs de uso de modelos IA
• Análise Técnica: Métricas de performance
• API Calls: Monitoramento de chamadas externas
• Interface Gradio: Logs de interação do usuário
• Sistema Ensemble: Logs de decisões de IA

Boas Práticas

1. Use níveis apropriados: DEBUG para desenvolvimento, INFO para operações normais
2. Inclua contexto: Sempre adicione metadados relevantes
3. Monitore performance: Use métricas para identificar gargalos
4. Mantenha limpo: Configure limpeza automática de logs antigos
5. Analise regularmente: Use a interface para identificar padrões

Troubleshooting

Problemas Comuns

1. Banco não inicializa

   • Verificar permissões da pasta logs/
   • Verificar espaço em disco

2. Performance lenta

   • Executar limpeza de logs antigos
   • Verificar índices do banco

3. Interface não carrega

   • Verificar se o banco existe
   • Verificar logs de erro do sistema

Comandos de Diagnóstico

# Verificar saúde do banco
db_logger.get_database_info()

# Testar conexão
db_logger.test_connection()

# Estatísticas de uso
stats = db_logger.get_log_statistics()

Conclusão

O sistema de logging avançado fornece visibilidade completa sobre todas as operações do sistema, permitindo:

• Monitoramento em tempo real
• Análise de performance
• Detecção de problemas
• Auditoria de operações
• Otimização contínua

Para mais informações, consulte os arquivos de código fonte ou a interface web de logs.