Troubleshooting

Este guia ajuda a diagnosticar e resolver problemas comuns no Sinapse.

Problemas de Inicialização

API não inicia

Erro: [Errno 48] Address already in use

Diagnóstico:

# Linux/macOS
lsof -i :8000

# Windows
netstat -ano | findstr :8000

Solução:

# Matar processo usando a porta
kill -9 <PID>

# Ou usar outra porta
export API_PORT=8001
uvicorn main:app --port 8001

Erro: connection to server at "localhost" (127.0.0.1), port 5432 failed

Diagnóstico:

# Verificar se PostgreSQL está rodando
systemctl status postgresql
docker ps | grep postgres

# Testar conexão
psql -h localhost -U sinapse_user -d sinapse_db -c "SELECT 1"

Solução:

# Iniciar PostgreSQL
systemctl start postgresql
# ou
docker start sinapse-postgres

# Verificar logs
journalctl -u postgresql -n 50
docker logs sinapse-postgres

Erro: ModuleNotFoundError: No module named 'fastapi'

Diagnóstico:

# Verificar ambiente ativo
which python
python --version

# Listar pacotes instalados
pip list | grep fastapi

Solução:

# Ativar ambiente correto
source venv/bin/activate  # ou conda activate api_sinapse

# Reinstalar dependências
pip install -r requirements.txt

# Verificar instalação
python -c "import fastapi; print(fastapi.__version__)"

Erro: PermissionError: [Errno 13] Permission denied

Diagnóstico:

# Verificar permissões
ls -la logs/
ls -la uploads/

Solução:

# Criar diretórios necessários
mkdir -p logs uploads

# Ajustar permissões
chmod 755 logs uploads

# Se usando Docker
docker exec sinapse-api chmod -R 755 /app/logs /app/uploads

Migrações falhando

alembic.util.exc.CommandError: Can't locate revision identified by 'abc123'

Solução:

# Verificar estado atual
alembic current

# Verificar histórico
alembic history

# Forçar estado (CUIDADO!)
alembic stamp head

# Recriar do zero (APENAS desenvolvimento)
alembic downgrade base
alembic upgrade head

Problemas de Autenticação

Diagnóstico:

# Verificar hash da senha
from core.security import verify_password, get_password_hash

# No shell Python
password = "admin123"
hashed = get_password_hash(password)
print(verify_password(password, hashed))  # Deve ser True

Possíveis causas:

Usuário inativo:

SELECT email, ativo FROM usuarios WHERE email = '[email protected]';

Token expirado:

# Verificar configuração
grep JWT .env

Secret key mudou:

# Tokens antigos ficam inválidos se SECRET_KEY mudar
# Solução: fazer novo login

Erro 403 Forbidden

Diagnóstico:

# Verificar permissões do usuário
curl -X GET http://localhost:8000/api/v1/usuarios/me \
  -H "Authorization: Bearer $TOKEN" | jq .permissoes

Solução:

-- Verificar grupos e permissões
SELECT 
    u.email,
    g.nome as grupo,
    p.codigo as permissao
FROM usuarios u
LEFT JOIN usuario_grupo ug ON u.id = ug.usuario_id
LEFT JOIN grupos g ON ug.grupo_id = g.id
LEFT JOIN grupo_permissao gp ON g.id = gp.grupo_id
LEFT JOIN permissoes p ON gp.permissao_id = p.id
WHERE u.email = '[email protected]';

Problemas de Performance

API lenta

1. Identificar gargalos:

# Adicionar profiling temporário
from datetime import datetime

# No endpoint problemático
start = datetime.now()
# ... código ...
print(f"Tempo gasto: {(datetime.now() - start).total_seconds()}s")

2. Verificar queries N+1:

# Habilitar logs SQL
# .env
DB_ECHO=true

# Procurar por múltiplas queries similares nos logs

3. Otimizar queries:

# Ruim - N+1 queries
usuarios = await db.execute(select(UsuarioModel))
for usuario in usuarios:
    permissoes = await db.execute(
        select(PermissaoModel).where(...)
    )

# Bom - 1 query com join
usuarios = await db.execute(
    select(UsuarioModel)
    .options(selectinload(UsuarioModel.permissoes))
)

Memória alta

Diagnóstico:

# Monitorar uso de memória
ps aux | grep python
htop  # ou top

# Com Docker
docker stats sinapse-api

Soluções:

Limitar workers:

API_WORKERS=2  # Reduzir número de workers

Paginação obrigatória:

# Forçar limite máximo
if size > 100:
    size = 100

Garbage collection:

import gc

# Após operações pesadas
gc.collect()

Problemas de Dados

Dados corrompidos

Sintomas:

Erros de encoding
JSONDecodeError
Constraint violations

Diagnóstico:

-- Verificar constraints
SELECT 
    conname,
    contype,
    conrelid::regclass AS table_name
FROM pg_constraint
WHERE contype = 'f'  -- foreign keys
AND NOT convalidated;

-- Verificar dados órfãos
SELECT u.* 
FROM usuarios u
LEFT JOIN grupos g ON u.grupo_id = g.id
WHERE u.grupo_id IS NOT NULL 
AND g.id IS NULL;

Solução:

-- Backup antes!
pg_dump sinapse_db > backup_$(date +%Y%m%d).sql

-- Limpar dados órfãos
DELETE FROM usuario_permissao 
WHERE usuario_id NOT IN (SELECT id FROM usuarios);

-- Recriar constraints
ALTER TABLE usuarios 
ADD CONSTRAINT fk_usuario_grupo 
FOREIGN KEY (grupo_id) REFERENCES grupos(id);

Importação falha

Para arquivos grandes:

# Processar em chunks
import pandas as pd

chunk_size = 1000
for chunk in pd.read_csv('dados.csv', chunksize=chunk_size):
    await processar_chunk(chunk)
    await db.commit()  # Commit por chunk

Problemas de Integração

Webhook não dispara

Verificar:

URL está acessível
Certificado SSL válido
Timeout adequado
Payload correto

Debug:

import httpx
import json

# Testar manualmente
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://webhook.url/endpoint",
        json={"test": "data"},
        timeout=30
    )
    print(f"Status: {response.status_code}")
    print(f"Response: {response.text}")

API externa timeout

Solução:

# Aumentar timeout
async with httpx.AsyncClient(timeout=60) as client:
    response = await client.get(url)

# Implementar retry
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
async def call_external_api():
    # ...

Logs e Diagnóstico

Localização dos logs

# Desenvolvimento
tail -f logs/sinapse.log
tail -f logs/access.log

# Docker
docker logs -f sinapse-api

# Systemd
journalctl -u sinapse -f

Aumentar nível de log

# .env
LOG_LEVEL=DEBUG

# Ou em runtime
import logging
logging.getLogger("modules.agravos").setLevel(logging.DEBUG)

Queries úteis para debug

-- Últimas requisições
SELECT 
    created_at,
    user_id,
    method,
    path,
    status_code,
    duration_ms
FROM api_logs
ORDER BY created_at DESC
LIMIT 20;

-- Erros recentes
SELECT 
    timestamp,
    level,
    message,
    extra_data
FROM application_logs
WHERE level >= 'ERROR'
AND timestamp > NOW() - INTERVAL '1 hour'
ORDER BY timestamp DESC;

-- Usuários ativos
SELECT 
    u.email,
    COUNT(DISTINCT al.id) as requests,
    MAX(al.created_at) as last_activity
FROM usuarios u
JOIN api_logs al ON u.id = al.user_id
WHERE al.created_at > NOW() - INTERVAL '24 hours'
GROUP BY u.email
ORDER BY requests DESC;

Monitoramento de Saúde

Health checks

# Básico
curl http://localhost:8000/api/v1/health

# Detalhado
curl http://localhost:8000/api/v1/health/detailed

Métricas Prometheus

# Se configurado
curl http://localhost:8000/metrics

Script de monitoramento

#!/bin/bash
# monitor.sh

while true; do
    STATUS=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8000/api/v1/health)
    
    if [ $STATUS -ne 200 ]; then
        echo "$(date): API DOWN - Status: $STATUS"
        # Enviar alerta
        # systemctl restart sinapse
    else
        echo "$(date): API OK"
    fi
    
    sleep 30
done

Recuperação de Desastres

Backup corrompido

# Tentar recuperar parcialmente
pg_restore -v -c -e -a backup.dump

# Se falhar, restaurar tabela por tabela
pg_restore -t usuarios -v backup.dump
pg_restore -t grupos -v backup.dump

Rollback de migração

# Verificar migração problemática
alembic history

# Reverter
alembic downgrade -1

# Corrigir e reaplicar
alembic upgrade head

Contato para Suporte

Se o problema persistir:

Colete informações:
- Logs completos
- Versão do sistema
- Passos para reproduzir
- Configurações (sem senhas!)
Abra um issue:
- GitHub Issues
Emergências:
- Email: [email protected]
- Incluir: [URGENTE] no assunto

Dica: Mantenha um playbook com soluções para problemas recorrentes específicos do seu ambiente.

Troubleshooting

On this page