RouteBreaker

Sistema completo de monitoramento de estabilidade de internet em Python, projetado para rodar por horas/dias, registrando métricas e gerando evidências (gráficos/relatórios) para comprovar problemas de ping, perda de pacotes, jitter, download/upload e rotas (traceroute/mtr).

🎯 Características Principais

Monitoramento contínuo de múltiplos destinos (ping, latência, perda, jitter)
Detecção automática de eventos e instabilidades com thresholds configuráveis
Testes de rota (MTR/Traceroute) periódicos e quando eventos são detectados
Testes de velocidade (download/upload) periódicos ou sob demanda
Dashboard web em tempo real com gráficos interativos
Sessões de teste - salve e analise testes individuais
Persistência em SQLite com fila assíncrona para evitar travamentos
Relatórios e gráficos automáticos (HTML e PDF)
Análise automática com OpenAI (GPT-5-mini) para interpretação de problemas

📊 Diagrama de Fluxo do Sistema

┌─────────────────────────────────────────────────────────────────┐
│                        RouteBreaker System                       │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
        ┌────────────────────────────────────────┐
        │       MonitorService (Core)            │
        │  ┌──────────────────────────────────┐  │
        │  │  StateManager                    │  │
        │  │  - RUNNING / PAUSED / STOPPED   │  │
        │  └──────────────────────────────────┘  │
        └────────────────────────────────────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
        ▼           ▼           ▼
┌──────────┐  ┌──────────┐  ┌──────────┐
│  Ping    │  │ Speedtest│  │Path Test │
│  Monitor │  │  Loop    │  │  Loop    │
│  (Cont.) │  │(Periodic)│  │(Periodic)│
└──────────┘  └──────────┘  └──────────┘
    │             │             │
    │             │             │
    ▼             ▼             ▼
┌──────────────────────────────────────┐
│        PersistentQueue               │
│  (Thread-safe async batch writes)    │
└──────────────────────────────────────┘
    │
    ▼
┌──────────────────────────────────────┐
│      SQLite Database                 │
│  - ping_samples                      │
│  - ping_aggregates                   │
│  - events                            │
│  - route_tests                       │
│  - speed_tests                       │
│  - test_sessions                     │
│  - system_info                       │
│  - overall_status                    │
└──────────────────────────────────────┘
    │
    ├──────────────────────────────────┐
    │                                  │
    ▼                                  ▼
┌──────────────────┐          ┌──────────────────┐
│  Aggregator      │          │ Event Detector   │
│  (Window-based)  │          │ (Thresholds)     │
└──────────────────┘          └──────────────────┘
    │                                  │
    └──────────┬───────────────────────┘
               │
               ▼
        ┌──────────────┐
        │   WebSocket  │
        │  Broadcast   │
        └──────────────┘
               │
        ┌──────┴──────┐
        │             │
        ▼             ▼
┌──────────┐   ┌──────────┐
│  Dashboard│   │  API REST│
│  (Web UI) │   │ Endpoints│
└──────────┘   └──────────┘

Loops Periódicos em Execução

Ping Monitor - Executa pings continuamente para todos os targets habilitados
Speedtest Loop - Executa testes de velocidade periodicamente (config: speedtest_cooldown_minutes)
Path Test Loop - Executa testes de rota (MTR/Traceroute) periodicamente para diferentes targets em ciclo (config: traceroute_cooldown_minutes)
System Info Loop - Coleta informações do sistema a cada 5 minutos (CPU, RAM, IP público, gateway)
Cleanup Loop - Remove dados antigos e faz downsample periodicamente (config: cleanup_schedule_minutes)

🚀 Instalação

Requisitos

Python 3.8+
Linux (principal), Windows/macOS com limitações

Dependências do Sistema

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y python3-pip traceroute mtr-tiny

# Para ICMP nativo (opcional, mas recomendado)
sudo setcap cap_net_raw+ep $(which python3)

Instalação Python

git clone https://github.com/pedro-dalben/RouteBreaker.git
cd RouteBreaker
pip install -r requirements.txt

⚙️ Configuração

Copie o arquivo de configuração de exemplo:

cp config.example.yaml config.yaml

Edite config.yaml conforme necessário. Principais configurações:

targets: Lista de destinos para monitorar (DNS, CDNs, etc.)
monitoring.ping_interval_seconds: Intervalo entre pings (padrão: 1s)
monitoring.aggregate_window_seconds: Janela de agregação (padrão: 60s)
thresholds: Thresholds para detecção de eventos
- high_latency_ms: Latência alta (padrão: 150ms)
- packet_loss_percent: Perda de pacotes (padrão: 5.0%)
- jitter_ms: Jitter alto (padrão: 30.0ms)
- consecutive_timeouts: Timeouts consecutivos (padrão: 3)
cooldowns:
- traceroute_cooldown_minutes: Cooldown entre testes de rota (padrão: 5min)
- speedtest_cooldown_minutes: Cooldown entre speedtests (padrão: 15min)
retention.retention_days: Dias de retenção de dados (padrão: 30)
openai.model: Modelo OpenAI (gpt-5-mini, gpt-5-nano, gpt-5)

Configure a chave da API OpenAI (opcional, apenas para análise):

export OPENAI_API_KEY="sua-chave-aqui"

Ou adicione diretamente em config.yaml:

openai:
  api_key: "sua-chave-aqui"

🔐 Permissões ICMP

O RouteBreaker tenta usar ICMP nativo (via icmplib) primeiro. Se não tiver permissões:

Linux

# Opção 1: Executar como root (não recomendado)
sudo python -m routebreaker monitor start

# Opção 2: Dar capacidade ao Python (recomendado)
sudo setcap cap_net_raw+ep $(which python3)

# Opção 3: Usar fallback automático (subprocess ping ou TCP)
# O sistema detecta automaticamente e usa o melhor método disponível

Fallbacks Automáticos

O sistema usa automaticamente na seguinte ordem:

icmplib (ICMP nativo, melhor performance)
subprocess ping (se icmplib não disponível)
TCP connect (porta 443, 80, 53 - último recurso)

O método usado é registrado automaticamente no banco de dados e visível no dashboard.

💻 Uso

Validação do Ambiente

Antes de começar, valide seu ambiente:

python -m routebreaker doctor

Este comando verifica:

Comandos necessários (ping, traceroute, mtr)
Permissões ICMP
Dependências Python
Porta do dashboard disponível

Dashboard Web (Recomendado)

O método mais fácil é usar o dashboard web, que inicia automaticamente o monitoramento:

python -m routebreaker serve

Acesse http://localhost:8000 no navegador.

Modo sem interface web (apenas monitoramento):

python -m routebreaker serve --no-web

Usar porta personalizada:

python -m routebreaker serve --port 8001

Comandos CLI (Alternativo)

Se preferir usar comandos CLI separados:

# Iniciar monitoramento
python -m routebreaker monitor start

# Ver status
python -m routebreaker status

# Pausar (mantém dados em memória)
python -m routebreaker monitor pause

# Parar completamente
python -m routebreaker monitor stop

# Gerar relatório
python -m routebreaker report

# Exportar dados
python -m routebreaker export --format csv --out exports/

# Análise com IA
python -m routebreaker analyze

🌐 Dashboard Web - Funcionalidades Completas

Início Rápido

Execute python -m routebreaker serve
Acesse http://localhost:8000
Clique em "Iniciar Teste Completo" ou "Modo Live Pool"

Controles Principais

Botões de Controle

▶ Iniciar Teste Completo: Inicia um teste completo com sessão salva, incluindo:
- Teste de velocidade inicial
- Teste de rota inicial
- Todos os loops periódicos
- Dados salvos com ID de sessão para relatórios posteriores
📡 Modo Live Pool: Modo de monitoramento contínuo sem sessão formal (sem speedtest/route tests automáticos)
⏸ Pausar: Pausa temporariamente o monitoramento (mantém dados em memória)
⏹ Parar: Para completamente o monitoramento
Timer de Execução: Mostra quanto tempo o teste está rodando (formato HH:MM:SS)

Abas do Dashboard

📊 Overview (Visão Geral)

Status Geral: Status atual da conectividade (OK, Degradado, Ruim, Down)
Gráfico de Velocidade: Download/Upload em tempo real
Gráfico de Latência: Latência de todos os targets em tempo real
Gráfico de Perda de Pacotes: Perda de pacotes em tempo real
Últimos Eventos: Lista dos eventos mais recentes detectados

📈 Ping

Gráfico detalhado de latência para cada target
Linhas coloridas para cada destino monitorado
Atualização em tempo real via WebSocket

📉 Perda

Gráfico de perda de pacotes por target
Visualização clara de problemas de conectividade

📊 Jitter

Gráfico de jitter (variação de latência)
Identifica instabilidades na conexão

🚀 Velocidade

Gráfico de download e upload
Histórico de testes de velocidade
Tabela com últimos resultados (timestamp, download, upload, ping, servidor)

🛣️ Rotas

Lista de testes de rota realizados
Visualização de hops problemáticos
Informações de perda por hop (quando disponível via MTR)

⚙️ Controles

Histórico de Testes: Tabela com todos os testes realizados
- ID da sessão
- Data/hora de início e fim
- Duração
- Tipo (Teste Completo / Live Pool)
- Status (running / completed)
- Botão "Ver" para gerar relatório da sessão específica
Gerar Relatório PDF: Gera relatório HTML/PDF do teste atual
Análise com IA: Analisa os dados usando OpenAI para identificar problemas

Atualizações em Tempo Real

O dashboard usa WebSocket para atualizações em tempo real:

Gráficos atualizados automaticamente conforme novos dados chegam
Eventos aparecem imediatamente quando detectados
Status geral atualizado continuamente
Speedtests e route tests aparecem assim que completam

Funcionalidades Avançadas

Sessões de Teste

Cada "Teste Completo" cria uma sessão única com ID
Sessões podem ser visualizadas no histórico
Relatórios podem ser gerados para sessões específicas
Análise com IA pode ser feita por sessão

Limpeza Automática

Ao iniciar novo teste, gráficos são limpos automaticamente
Dados antigos são mantidos no banco, mas não aparecem nos gráficos
Cada teste começa com visualização limpa

📡 API REST Completa

A API está disponível quando o dashboard está rodando em http://localhost:8000/api/:

Controle do Monitor

GET /api/status - Status do monitor (stopped/running/paused)
GET /api/monitor/info - Informações do monitor (status, session_id, is_live_pool)
POST /api/monitor/start?is_live_pool=false - Inicia monitoramento
POST /api/monitor/pause - Pausa monitoramento
POST /api/monitor/stop - Para monitoramento

Dados e Métricas

GET /api/metrics/recent?limit=100 - Métricas recentes (agregados)
GET /api/events?limit=100&event_type=high_latency - Lista de eventos
GET /api/events/{event_id}/context - Contexto completo de um evento
GET /api/routes?limit=50 - Testes de rota realizados
GET /api/speedtests?limit=50 - Testes de velocidade
GET /api/stats?target=google-dns-1&from_time=...&to_time=... - Estatísticas agregadas
GET /api/overall-status?limit=100 - Status geral atual e histórico

Sessões de Teste

GET /api/test-sessions?limit=50 - Lista todas as sessões de teste
- Retorna: id, name, start_time, end_time, duration, status, is_live_pool

Relatórios e Análise

POST /api/report/generate?session_id=13 - Gera relatório (opcionalmente para uma sessão específica)
- Retorna: html_path, pdf_path (se disponível)
POST /api/analyze?session_id=13 - Analisa dados com IA (opcionalmente para uma sessão específica)
- Retorna: path para arquivos de análise (md e json)

Arquivos Estáticos

GET /reports/{file_path} - Acessa relatórios gerados
GET / - Interface web do dashboard

🔌 WebSocket

Conecte-se via WebSocket em ws://localhost:8000/ws para receber atualizações em tempo real:

Tipos de Mensagens

{
  "type": "aggregate",
  "aggregate": {
    "target": "google-dns-1",
    "window_start": "2024-01-01T12:00:00",
    "avg_latency": 45.2,
    "packet_loss_percent": 0.0,
    "jitter_ms": 5.3
  }
}

{
  "type": "ping_sample",
  "sample": {
    "target": "google-dns-1",
    "timestamp": "2024-01-01T12:00:05",
    "latency_ms": 42.1,
    "packet_lost": false
  }
}

{
  "type": "event",
  "event": {
    "timestamp": "2024-01-01T12:05:00",
    "event_type": "high_latency",
    "severity": "medium",
    "target": "google-dns-1"
  }
}

{
  "type": "overall_status",
  "status": {
    "timestamp": "2024-01-01T12:00:00",
    "status": "ok",
    "affected_targets": []
  }
}

{
  "type": "speedtest",
  "speedtest": {
    "timestamp": "2024-01-01T12:00:00",
    "download_mbps": 95.3,
    "upload_mbps": 45.2,
    "ping_ms": 12.5
  }
}

{
  "type": "route_test",
  "route_test": {
    "timestamp": "2024-01-01T12:00:00",
    "target": "google-dns-1",
    "engine_used": "mtr_json",
    "hops": [...]
  }
}

💾 Estrutura de Dados

Os dados são armazenados em SQLite (routebreaker.db por padrão) com as seguintes tabelas:

Tabelas Principais

ping_samples: Amostras individuais de ping
- timestamp, target, latency_ms, packet_lost, error, method_used, test_session_id
ping_aggregates: Agregações por janela temporal
- window_start, window_end, target, avg_latency, min_latency, max_latency, packet_loss_percent, jitter_ms, sample_count, test_session_id
events: Eventos detectados (alta latência, perda, etc.)
- timestamp, event_type, severity, target, details, context_window_start, context_window_end, test_session_id
route_tests: Resultados de traceroute/MTR
- timestamp, target, event_id, engine_used, raw_output, hops (JSON), test_session_id
speed_tests: Testes de velocidade
- timestamp, event_id, download_mbps, upload_mbps, ping_ms, server_info (JSON), test_session_id
test_sessions: Sessões de teste
- id, name, start_time, end_time, status, is_live_pool
system_info: Informações do sistema
- timestamp, public_ip, gateway, interface, ping_method_per_target, cpu_percent, ram_percent
overall_status: Status geral da conectividade
- timestamp, window_start, window_end, status, affected_targets, details, test_session_id

🔄 Retenção e Limpeza

O sistema automaticamente:

Remove dados mais antigos que retention_days
Faz downsample de dados após downsample_after_hours
Limpeza periódica a cada cleanup_schedule_minutes

Configure em config.yaml:

retention:
  retention_days: 30
  downsample_after_hours: 24
  downsample_interval_seconds: 10
  cleanup_schedule_minutes: 60

📄 Relatórios

Geração de Relatórios

Os relatórios são gerados em HTML e opcionalmente em PDF (se weasyprint estiver instalado).

Via Dashboard:

Clique em "Gerar Relatório PDF" na aba Controles

Via API:

curl -X POST "http://localhost:8000/api/report/generate?session_id=13"

Via CLI:

python -m routebreaker report
python -m routebreaker report --from 2024-01-01 --to 2024-01-31

Conteúdo dos Relatórios

Período de execução: Início, fim e duração
Estatísticas gerais: Latência média/máxima, perda de pacotes, jitter, eventos
Resumo de velocidade: Médias de download/upload/ping
Análise de rotas: Hops problemáticos, períodos de oscilação
Gráficos interativos: Latência, perda, jitter, velocidade
Lista de eventos: Todos os eventos detectados com detalhes

Análise com IA

A análise com IA gera dois arquivos:

ai_analysis.md - Análise em Markdown legível
ai_analysis.json - Dados estruturados

A análise inclui:

Causas prováveis: Identificação de problemas (ISP, rota, local)
Evidências: Dados que sustentam as conclusões
Padrões temporais: Horários problemáticos
Hops suspeitos: Pontos na rota com problemas
Próximos testes: Recomendações de testes adicionais
Mensagem para ISP: Texto pronto para abrir chamado

A IA recebe apenas dados resumidos e evidências selecionadas para otimizar custos e tokens.

🛠️ Troubleshooting

ICMP não funciona

O sistema usa fallback automático. Se precisar de ICMP nativo:

sudo setcap cap_net_raw+ep $(which python3)

Porta 8000 já está em uso

Use outra porta:

python -m routebreaker serve --port 8001

Banco de dados muito grande

Ajuste a retenção em config.yaml:

retention:
  retention_days: 15
  downsample_after_hours: 12

Gráficos não atualizam

Verifique se o WebSocket está conectado (status no canto superior direito)
Recarregue a página (F5)
Verifique o console do navegador para erros

Speedtest não roda periodicamente

Verifique speedtest_cooldown_minutes no config
Verifique os logs para erros
Certifique-se de que não está em "Modo Live Pool" (que não executa speedtests automáticos)

🔬 Desenvolvimento

Executar Testes

python -m pytest routebreaker/tests/

Estrutura do Projeto

routebreaker/
├── monitoring/         # Monitoramento de ping
│   ├── ping_monitor.py      # Monitor contínuo de ping
│   ├── aggregator.py        # Agregação de janelas temporais
│   └── event_detector.py    # Detecção de eventos
├── network_tests/     # Testes de rede
│   ├── path_test.py         # Traceroute/MTR
│   ├── speedtest.py         # Testes de velocidade
│   └── connectivity.py      # DNS, HTTP checks
├── storage/           # Persistência
│   ├── database.py          # Modelos SQLAlchemy
│   ├── repositories.py      # Repositórios de dados
│   └── exporters.py         # Exportação CSV/JSON
├── api/               # API REST e WebSocket
│   ├── app.py               # FastAPI app
│   ├── routes.py            # Endpoints REST
│   └── websocket.py         # WebSocket handler
├── ui/                # Interface web
│   └── index.html           # Dashboard HTML/JS
├── reports/           # Geração de relatórios
│   ├── generator.py         # Gerador de relatórios HTML/PDF
│   ├── charts.py            # Gráficos Plotly
│   └── ai_analyzer.py       # Integração OpenAI
├── core/              # Componentes core
│   ├── monitor_service.py   # Serviço principal
│   ├── queue.py             # Fila assíncrona
│   ├── state_manager.py     # Gerenciamento de estado
│   └── logging.py           # Logging estruturado
├── tools/             # Ferramentas auxiliares
│   └── doctor.py            # Validação de ambiente
└── tests/             # Testes unitários

📝 Licença

Este projeto está sob a licença MIT.

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue ou pull request.

Name		Name	Last commit message	Last commit date
routebreaker		routebreaker
.gitignore		.gitignore
README.md		README.md
config.example.yaml		config.example.yaml
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation

RouteBreaker

🎯 Características Principais

📊 Diagrama de Fluxo do Sistema

Loops Periódicos em Execução

🚀 Instalação

Requisitos

Dependências do Sistema

Instalação Python

⚙️ Configuração

🔐 Permissões ICMP

Linux

Fallbacks Automáticos

💻 Uso

Validação do Ambiente

Dashboard Web (Recomendado)

Comandos CLI (Alternativo)

🌐 Dashboard Web - Funcionalidades Completas

Início Rápido

Controles Principais

Botões de Controle

Abas do Dashboard

📊 Overview (Visão Geral)

📈 Ping

📉 Perda

📊 Jitter

🚀 Velocidade

🛣️ Rotas

⚙️ Controles

Atualizações em Tempo Real

Funcionalidades Avançadas

Sessões de Teste

Limpeza Automática

📡 API REST Completa

Controle do Monitor

Dados e Métricas

Sessões de Teste

Relatórios e Análise

Arquivos Estáticos

🔌 WebSocket

Tipos de Mensagens

💾 Estrutura de Dados

Tabelas Principais

🔄 Retenção e Limpeza

📄 Relatórios

Geração de Relatórios

Conteúdo dos Relatórios

Análise com IA

🛠️ Troubleshooting

ICMP não funciona

Porta 8000 já está em uso

Banco de dados muito grande

Gráficos não atualizam

Speedtest não roda periodicamente

🔬 Desenvolvimento

Executar Testes

Estrutura do Projeto

📝 Licença

🤝 Contribuindo

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages