first commit

This commit is contained in:
2026-02-09 17:14:40 -03:00
commit 52791b718c
22 changed files with 2651 additions and 0 deletions

304
TROUBLESHOOTING.md Normal file
View 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/)