first commit
This commit is contained in:
304
TROUBLESHOOTING.md
Normal file
304
TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 🛠️ Troubleshooting & FAQ
|
||||
|
||||
## ❌ Problemas Comuns
|
||||
|
||||
### 1. "Connection refused" ao acessar http://localhost:3000
|
||||
|
||||
**Causa**: Containers não estão rodando ou porta já está em uso
|
||||
|
||||
```bash
|
||||
# Verificar status
|
||||
docker-compose ps
|
||||
|
||||
# Se não estiver rodando
|
||||
docker-compose up -d
|
||||
|
||||
# Se porta já está em uso
|
||||
lsof -i :3000
|
||||
kill -9 <PID>
|
||||
docker-compose down
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### 2. Grafana mostra "Data source is not responding"
|
||||
|
||||
**Causa**: Datasource não consegue conectar à API
|
||||
|
||||
```bash
|
||||
# Verificar se API está rodando
|
||||
docker-compose logs monitoring-api
|
||||
|
||||
# Verificar conectividade do container Grafana
|
||||
docker-compose exec grafana ping monitoring-api
|
||||
|
||||
# Reiniciar API
|
||||
docker-compose restart monitoring-api
|
||||
```
|
||||
|
||||
### 3. API retorna "Failed to authenticate"
|
||||
|
||||
**Causa**: Credenciais inválidas ou API PersonalizeIT indisponível
|
||||
|
||||
```bash
|
||||
# Verificar credenciais
|
||||
cat .env | grep API_
|
||||
|
||||
# Testar login manualmente
|
||||
curl -X POST \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"email":"seu_email@exemplo.com","password":"sua_senha"}' \
|
||||
https://api-personalizeit.zapplataforma.chat/auth/login
|
||||
|
||||
# Verificar logs
|
||||
docker-compose logs monitoring-api | grep -i "authent"
|
||||
```
|
||||
|
||||
### 4. "ENOENT: no such file or directory, open '.env'"
|
||||
|
||||
**Causa**: Arquivo .env não foi criado
|
||||
|
||||
```bash
|
||||
# Criar .env a partir do exemplo
|
||||
cp config/.env.example .env
|
||||
|
||||
# Editar com credenciais
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 5. Prometheus mostra "Unhealthy Target"
|
||||
|
||||
**Causa**: Prometheus não consegue scrape da API
|
||||
|
||||
```bash
|
||||
# Verificar URL no prometheus.yml
|
||||
# Deve ser: http://monitoring-api:5000/metrics
|
||||
|
||||
# Verificar se métrica está acessível
|
||||
curl http://localhost:5000/metrics
|
||||
|
||||
# Se vazio, significa sem dados. Tudo ok.
|
||||
```
|
||||
|
||||
### 6. "permission denied" ao executar setup.sh
|
||||
|
||||
**Causa**: Script sem permissão de execução
|
||||
|
||||
```bash
|
||||
chmod +x setup.sh test-api.sh
|
||||
./setup.sh
|
||||
```
|
||||
|
||||
### 7. Docker Compose "service not found"
|
||||
|
||||
**Causa**: Nomes dos serviços estão incorretos
|
||||
|
||||
```yaml
|
||||
# Verifique os nomes em docker-compose.yml
|
||||
# Devem ser: monitoring-api, grafana, prometheus
|
||||
```
|
||||
|
||||
### 8. "Disk space insufficient"
|
||||
|
||||
**Causa**: Volumes do Docker muito grande
|
||||
|
||||
```bash
|
||||
# Ver tamanho dos volumes
|
||||
docker volume ls
|
||||
docker system df
|
||||
|
||||
# Limpar volumes não usados
|
||||
docker volume prune
|
||||
|
||||
# Remover dados históricos
|
||||
docker-compose down -v
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## ⚙️ Otimizações
|
||||
|
||||
### Melhorar Performance
|
||||
|
||||
1. **Aumentar intervalo de refresh** (se dados menos atualizados ok)
|
||||
```env
|
||||
REFRESH_INTERVAL=60 # Era 30s
|
||||
```
|
||||
|
||||
2. **Limitar quantidade de tickets**
|
||||
```bash
|
||||
# Na query da API, adicionar paginação
|
||||
# Módulo API Client já suporta limitação
|
||||
```
|
||||
|
||||
3. **Usar Redis para cache**
|
||||
```bash
|
||||
# Adicionar ao docker-compose.yml
|
||||
# Depois modificar app.py para usar Redis
|
||||
```
|
||||
|
||||
### Reduzir Consumo de Memória
|
||||
|
||||
1. **Usar volume para dados do Grafana**
|
||||
```yaml
|
||||
volumes:
|
||||
- grafana-storage:/var/lib/grafana
|
||||
```
|
||||
|
||||
2. **Limitar workers do Gunicorn**
|
||||
```dockerfile
|
||||
CMD ["gunicorn", "--workers", "2", "--bind", "0.0.0.0:5000", "app:app"]
|
||||
```
|
||||
|
||||
## 📊 Monitoramento do Próprio Sistema
|
||||
|
||||
### Métricas da API
|
||||
```bash
|
||||
# Ver saúde da API
|
||||
curl http://localhost:5000/health
|
||||
|
||||
# Ver CPU e memória do container
|
||||
docker stats monitoring-api
|
||||
```
|
||||
|
||||
### Métricas do Grafana
|
||||
```bash
|
||||
# Ver logs do Grafana
|
||||
docker-compose logs grafana
|
||||
|
||||
# Ver consumo
|
||||
docker stats grafana
|
||||
```
|
||||
|
||||
### Métricas do Prometheus
|
||||
```bash
|
||||
# Verificar targets
|
||||
curl http://localhost:9090/api/v1/targets
|
||||
|
||||
# Verificar health
|
||||
curl http://localhost:9090/-/healthy
|
||||
```
|
||||
|
||||
## 🔐 Segurança
|
||||
|
||||
### Checklist de Segurança
|
||||
|
||||
- ✅ .env não está commitado (verificar .gitignore)
|
||||
```bash
|
||||
cat .gitignore | grep .env
|
||||
```
|
||||
|
||||
- ✅ Senhas não estão em logs
|
||||
```bash
|
||||
docker-compose logs | grep -i password
|
||||
# Não deve encontrar nada
|
||||
```
|
||||
|
||||
- ✅ HTTPS configurado (se em produção)
|
||||
```bash
|
||||
# Usar reverse proxy com SSL
|
||||
```
|
||||
|
||||
- ✅ Firewall configurado
|
||||
```bash
|
||||
# Apenas portas 3000 e 5000 acessíveis
|
||||
```
|
||||
|
||||
## 📝 Logs e Debug
|
||||
|
||||
### Ativar debug mode
|
||||
```env
|
||||
DEBUG=True # Em .env
|
||||
```
|
||||
|
||||
### Ver logs completos
|
||||
```bash
|
||||
# Tempo real
|
||||
docker-compose logs -f
|
||||
|
||||
# Últimas 100 linhas
|
||||
docker-compose logs --tail 100
|
||||
|
||||
# Apenas da API
|
||||
docker-compose logs -f monitoring-api
|
||||
```
|
||||
|
||||
### Exportar logs
|
||||
```bash
|
||||
docker-compose logs > debug.log
|
||||
cat debug.log
|
||||
```
|
||||
|
||||
### Log level em Python
|
||||
```python
|
||||
# Em app.py, modificar:
|
||||
logging.basicConfig(level=logging.DEBUG) # Era INFO
|
||||
```
|
||||
|
||||
## 🔄 Resetar Tudo
|
||||
|
||||
```bash
|
||||
# Parar todos os containers
|
||||
docker-compose down
|
||||
|
||||
# Remover volumes (dados históricos)
|
||||
docker-compose down -v
|
||||
|
||||
# Remover imagens
|
||||
docker-compose down -v --rmi all
|
||||
|
||||
# Reconstruir
|
||||
docker-compose build --no-cache
|
||||
|
||||
# Reiniciar
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 📞 Quando Nada Funciona
|
||||
|
||||
1. **Verificar Docker**
|
||||
```bash
|
||||
docker --version
|
||||
docker run hello-world
|
||||
```
|
||||
|
||||
2. **Verificar conectividade**
|
||||
```bash
|
||||
ping -c 1 api-personalizeit.zapplataforma.chat
|
||||
curl https://api-personalizeit.zapplataforma.chat/auth/login
|
||||
```
|
||||
|
||||
3. **Recriar do zero**
|
||||
```bash
|
||||
docker-compose down -v --rmi all
|
||||
rm -rf grafana-storage prometheus-storage
|
||||
rm .env
|
||||
cp config/.env.example .env
|
||||
# Configure .env
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
4. **Buscar ajuda**
|
||||
```bash
|
||||
# Coletar informações
|
||||
docker-compose ps > info.txt
|
||||
docker-compose logs >> info.txt
|
||||
curl http://localhost:5000/health >> info.txt
|
||||
# Compartilhar info.txt
|
||||
```
|
||||
|
||||
## 🚀 Performance Tips
|
||||
|
||||
| Problema | Solução |
|
||||
|----------|---------|
|
||||
| Lento | Aumentar REFRESH_INTERVAL |
|
||||
| Alto consumo memória | Reduzir workers gunicorn |
|
||||
| Muitos dados | Fazer paginação ou filtrar |
|
||||
| Sem dados | Verificar credenciais |
|
||||
| Timeouts | Aumentar timeout em api_client.py |
|
||||
| Erros de conexão | Verificar firewall/proxy |
|
||||
|
||||
## 📚 Documentação Referência
|
||||
|
||||
- [Docker Docs](https://docs.docker.com/)
|
||||
- [Flask Docs](https://flask.palletsprojects.com/)
|
||||
- [Grafana Docs](https://grafana.com/docs/)
|
||||
- [Prometheus Docs](https://prometheus.io/docs/)
|
||||
Reference in New Issue
Block a user