🔧 Guia de Troubleshooting - CSuite

Versão: 1.0
Última Atualização: 2025-01-02
Responsável: Equipe de Suporte e Operações

📋 Índice

1. Visão Geral
2. Problemas Comuns
3. Problemas por Serviço
4. Problemas de Infraestrutura
5. Problemas de Performance
6. Problemas de Dados
7. Ferramentas de Diagnóstico
8. Escalation

🎯 Visão Geral

Este guia fornece soluções para problemas comuns encontrados no ecossistema CSuite, ajudando a resolver questões rapidamente sem necessidade de escalation.

Como Usar Este Guia

1. Identifique o sintoma: O que não está funcionando?
2. Verifique logs: Consulte logs do serviço afetado
3. Siga os passos: Execute os passos de diagnóstico
4. Aplique a solução: Siga as instruções de correção
5. Se não resolver: Escale conforme Escalation

🐛 Problemas Comuns

Problema: Serviço não responde

Sintomas:
- Timeout em requisições
- Health check falhando
- 502/503/504 errors

Diagnóstico:

# Verificar status do serviço
docker service ls | grep csuite

# Verificar logs
docker service logs csuite-gateway_csuite-gateway --tail 100

# Verificar health check
curl http://localhost:8080/health

Soluções:
1. Serviço parado:
bash docker service scale csuite-gateway_csuite-gateway=1

1. Recursos insuficientes:
   bash # Verificar uso de recursos docker stats # Aumentar recursos se necessário

2. Erro no código:

3. Verificar logs para erros
4. Verificar KNOWN_ISSUES.md
5. Rollback se necessário

Problema: Erro de autenticação

Sintomas:
- 401 Unauthorized
- Token inválido
- Sessão expirada

Diagnóstico:

# Verificar token
curl -H "Authorization: Bearer <token>" http://localhost:8080/api/v1/health

# Verificar logs de autenticação
docker service logs csuite-gateway_csuite-gateway | grep -i auth

Soluções:
1. Token expirado:
- Renovar token
- Verificar expiração configurada

1. Token inválido:
2. Verificar formato do token

3. Verificar secret key

4. Credenciais incorretas:

5. Verificar usuário/senha
6. Resetar senha se necessário

Problema: Erro de conexão com banco

Sintomas:
- Erro "Connection refused"
- Erro "Can't connect to MySQL server"
- Timeout em queries

Diagnóstico:

# Verificar status do MySQL
docker service ls | grep mysql

# Testar conexão
docker exec -it <mysql-container> mysql -u root -p -e "SELECT 1"

# Verificar logs
docker service logs csuite-mysql_mysql --tail 100

Soluções:
1. MySQL parado:
bash docker service scale csuite-mysql_mysql=1

1. Credenciais incorretas:
2. Verificar secrets do Docker Swarm

3. Verificar variáveis de ambiente

4. Rede:

5. Verificar network do Docker
6. Verificar firewall

Problema: Erro 404 Not Found

Sintomas:
- Endpoint não encontrado
- Documento não encontrado
- Recurso não existe

Diagnóstico:

# Verificar rota
curl -v http://localhost:8080/api/v1/endpoint

# Verificar logs
docker service logs csuite-gateway_csuite-gateway | grep 404

Soluções:
1. Rota incorreta:
- Verificar URL
- Verificar documentação da API

1. Versão incorreta:
2. Verificar versão da API (v1, v2)

3. Verificar API_VERSIONING.md

4. Recurso não existe:

5. Verificar se recurso foi criado
6. Verificar permissões

🔌 Problemas por Serviço

Gateway (csuite-gateway)

Problema: Gateway não roteia requisições

Diagnóstico:

# Verificar Traefik
docker service logs csuite-gateway_traefik --tail 100

# Verificar rotas
curl http://localhost:8080/api/v1/health

Soluções:
1. Traefik não configurado:
- Verificar labels no docker-stack.yml
- Reiniciar serviço

1. Porta incorreta:
2. Verificar mapeamento de portas
3. Verificar firewall

Context API (csuite-context)

Problema: Context não retorna dados

Diagnóstico:

# Verificar logs
docker service logs csuite-context_context-api --tail 100

# Testar endpoint
curl http://localhost:8080/api/v1/context/entity/123

Soluções:
1. Banco sem dados:
- Verificar se dados foram carregados
- Executar scripts de inicialização

1. Query lenta:
2. Verificar índices
3. Otimizar query

Executive API (csuite-executive)

Problema: Decisões não sendo processadas

Diagnóstico:

# Verificar logs
docker service logs csuite-executive_executive-api --tail 100

# Verificar fila de decisões
# (depende da implementação)

Soluções:
1. Fila bloqueada:
- Verificar processamento
- Reiniciar worker se necessário

1. Políticas não encontradas:
2. Verificar registro de políticas
3. Verificar banco de dados

Agent Loop

Problema: Agentes não executam

Diagnóstico:

# Verificar logs do agent loop
docker service logs csuite-agent_agent-loop --tail 100

# Verificar status dos agentes
# (depende da implementação)

Soluções:
1. Agente desabilitado:
- Verificar configuração
- Habilitar agente

1. Erro em política:
2. Verificar logs de erro
3. Verificar políticas registradas

🏗️ Problemas de Infraestrutura

Problema: Docker Swarm não funciona

Sintomas:
- Serviços não iniciam
- Erro "node is not a swarm manager"
- Erro de rede

Diagnóstico:

# Verificar status do swarm
docker info | grep Swarm

# Verificar nodes
docker node ls

# Verificar rede
docker network ls

Soluções:
1. Swarm não inicializado:
bash docker swarm init

1. Node não é manager:
   bash # Promover node docker node promote <node-id>

2. Rede não existe:
   bash # Criar rede docker network create --driver overlay csuite-network

Problema: Disco cheio

Sintomas:
- Erro "No space left on device"
- Serviços falhando
- Imagens não podem ser criadas

Diagnóstico:

# Verificar uso de disco
df -h

# Verificar uso do Docker
docker system df

Soluções:
1. Limpar imagens não usadas:
bash docker image prune -a

1. Limpar volumes não usados:
   bash docker volume prune

2. Limpar sistema completo:
   bash docker system prune -a --volumes

⚠️ Cuidado: Comandos acima podem remover dados. Fazer backup antes.

Problema: Memória insuficiente

Sintomas:
- OOM (Out of Memory) errors
- Serviços sendo mortos
- Performance degradada

Diagnóstico:

# Verificar uso de memória
free -h

# Verificar uso por container
docker stats

Soluções:
1. Aumentar limites:
- Ajustar limites no docker-stack.yml
- Adicionar mais memória ao servidor

1. Otimizar uso:
2. Reduzir número de réplicas
3. Otimizar queries
4. Limpar cache

⚡ Problemas de Performance

Problema: Respostas lentas

Sintomas:
- Latência alta
- Timeouts
- Usuários reclamando

Diagnóstico:

# Verificar latência
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:8080/api/v1/health

# Verificar métricas
# (Grafana/Prometheus se disponível)

Soluções:
1. Queries lentas:
- Verificar índices
- Otimizar queries
- Adicionar cache

1. Recursos insuficientes:
2. Aumentar CPU/memória

3. Escalar serviços

4. Rede:

5. Verificar latência de rede
6. Verificar firewall rules

Problema: Alto uso de CPU

Sintomas:
- CPU em 100%
- Serviços lentos
- Timeouts

Diagnóstico:

# Verificar uso de CPU
top
htop

# Verificar por container
docker stats

Soluções:
1. Processo específico:
- Identificar processo
- Otimizar código
- Adicionar limites

1. Queries pesadas:
2. Otimizar queries
3. Adicionar índices
4. Cachear resultados

Problema: Alto uso de memória

Sintomas:
- Memória esgotando
- OOM errors
- Swap sendo usado

Diagnóstico:

# Verificar uso de memória
free -h

# Verificar por processo
ps aux --sort=-%mem | head

Soluções:
1. Memory leak:
- Identificar processo
- Corrigir leak
- Reiniciar serviço temporariamente

1. Cache excessivo:
2. Reduzir tamanho de cache
3. Limpar cache periodicamente

💾 Problemas de Dados

Problema: Dados inconsistentes

Sintomas:
- Dados não batem
- Relatórios incorretos
- Integridade comprometida

Diagnóstico:

-- Verificar integridade
SELECT * FROM information_schema.TABLE_CONSTRAINTS 
WHERE TABLE_SCHEMA = 'csuite';

-- Verificar dados
SELECT COUNT(*) FROM table_name;

Soluções:
1. Corrigir dados:
- Executar scripts de correção
- Validar após correção

1. Prevenir:
2. Adicionar constraints
3. Validar antes de inserir
4. Transações para operações críticas

Problema: Dados não aparecem

Sintomas:
- Dados inseridos não aparecem
- Queries retornam vazio
- Cache desatualizado

Diagnóstico:

-- Verificar se dados existem
SELECT * FROM table_name WHERE id = 123;

-- Verificar transações pendentes
SHOW PROCESSLIST;

Soluções:
1. Transação não commitada:
- Verificar transações abertas
- Commit ou rollback

1. Cache desatualizado:
2. Limpar cache

3. Invalidar cache específico

4. Filtros incorretos:

5. Verificar WHERE clause
6. Verificar permissões

🛠️ Ferramentas de Diagnóstico

Logs

Ver logs de serviço:

# Logs em tempo real
docker service logs -f csuite-gateway_csuite-gateway

# Últimas 100 linhas
docker service logs --tail 100 csuite-gateway_csuite-gateway

# Logs com timestamp
docker service logs --timestamps csuite-gateway_csuite-gateway

Ver logs de container:

# Logs de container específico
docker logs <container-id>

# Logs com follow
docker logs -f <container-id>

Health Checks

Verificar health de serviço:

# Health check via API
curl http://localhost:8080/health

# Health check via Docker
docker service inspect csuite-gateway_csuite-gateway | grep -A 10 HealthCheck

Métricas

Ver métricas (se Prometheus/Grafana disponível):
- Acessar Grafana: http://localhost:3000
- Verificar dashboards
- Analisar métricas de performance

Debug

Modo debug:

# Habilitar debug em serviço
# (depende da implementação)

# Ver variáveis de ambiente
docker service inspect csuite-gateway_csuite-gateway | grep -A 20 Env

📞 Escalation

Quando Escalar

Escalar imediatamente se:
- Problema crítico (P1)
- Dados comprometidos
- Sistema completamente inoperante
- Não há solução conhecida

Mais informações: SUPPORT_CONTACTS.md

Informações para Escalation

Ao escalar, fornecer:
1. Descrição do problema:
- O que está acontecendo?
- Quando começou?
- Impacto?

1. Diagnóstico realizado:
2. O que foi verificado?
3. Logs relevantes

4. Erros encontrados

5. Tentativas de solução:

6. O que foi tentado?

7. Resultados?

8. Ambiente:

9. Serviço afetado
10. Versão
11. Ambiente (staging/prod)

🔗 Documentos Relacionados

• KNOWN_ISSUES.md - Problemas conhecidos
• SUPPORT_CONTACTS.md - Contatos de suporte
• FAQ.md - Perguntas frequentes
• SECURITY_INCIDENT_RESPONSE.md - Incidentes de segurança

Última Revisão: 2025-01-02
Próxima Revisão: 2025-04-02 (trimestral)