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
```sql
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
```sql
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
```sql
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
```python
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
```python
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
```python
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
```python
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

```python
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
```python
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
```python
# 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
```python
# 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
```python
# 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
```python
# 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
```python
# 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.