🏠 Início / 📚 Documentação / Operations / Monitoring Guide

Monitoring Guide

📊 Guia de Monitoramento - CSuite

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

📋 Índice

  1. Visão Geral
  2. Stack de Monitoramento
  3. Métricas
  4. Logs
  5. Alertas
  6. Dashboards
  7. Troubleshooting

🎯 Visão Geral

Este guia descreve como monitorar o ecossistema CSuite, incluindo métricas, logs, alertas e dashboards.

Objetivos

  1. Visibilidade: Entender o estado do sistema
  2. Detecção: Identificar problemas rapidamente
  3. Análise: Investigar causas de problemas
  4. Otimização: Melhorar performance baseado em dados

🛠️ Stack de Monitoramento

Componentes Atuais

Métricas:
- 🟡 Prometheus - Coleta de métricas (planejado)
- 🟡 Grafana - Visualização (planejado)
- ✅ Docker Stats - Métricas básicas

Logs:
- ✅ Docker Logs - Logs de containers
- 🟡 ELK Stack - Elasticsearch, Logstash, Kibana (planejado)
- ✅ File Logs - Logs em arquivos

Tracing:
- 🟡 Jaeger/Zipkin - Distributed tracing (planejado)

APM:
- 🟡 Application Performance Monitoring (planejado)

📈 Métricas

Métricas de Infraestrutura

CPU:

# Ver uso de CPU
docker stats

# Ver CPU por serviço
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

Memória:

# Ver uso de memória
free -h

# Ver memória por container
docker stats --format "table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}"

Disco:

# Ver uso de disco
df -h

# Ver uso do Docker
docker system df

Rede:

# Ver estatísticas de rede
docker stats --format "table {{.Name}}\t{{.NetIO}}"

Métricas de Aplicação

Health Checks:

# Health check do gateway
curl http://localhost:8080/health

# Health check de todos os serviços
# (depende da implementação)

Taxa de Requisições:
- Requests por segundo (RPS)
- Requests por minuto (RPM)
- Requests por hora (RPH)

Latência:
- Tempo de resposta (p50, p95, p99)
- Tempo de processamento
- Tempo de banco de dados

Taxa de Erro:
- Erros por segundo
- Taxa de erro (%)
- Erros por tipo (4xx, 5xx)

Exemplo de métricas (se Prometheus implementado):

from prometheus_client import Counter, Histogram

# Contador de requisições
requests_total = Counter('http_requests_total', 'Total HTTP requests')

# Histograma de latência
request_duration = Histogram('http_request_duration_seconds', 'HTTP request duration')

Métricas de Negócio

Decisões:
- Decisões processadas por minuto
- Decisões por tipo
- Taxa de sucesso de decisões

Agentes:
- Agentes ativos
- Execuções de agentes
- Performance de agentes

Políticas:
- Políticas executadas
- Outcomes gerados
- Políticas por tipo

📝 Logs

Estrutura de Logs

Formato recomendado:

{
  "timestamp": "2025-01-02T10:30:00Z",
  "level": "INFO",
  "service": "csuite-gateway",
  "message": "Request processed",
  "request_id": "abc123",
  "user_id": "user123",
  "endpoint": "/api/v1/endpoint",
  "method": "GET",
  "status_code": 200,
  "duration_ms": 45
}

Ver Logs

Docker Logs:

# Logs de serviço
docker service logs csuite-gateway_csuite-gateway

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

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

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

# Logs desde timestamp
docker service logs --since 2025-01-02T10:00:00 csuite-gateway_csuite-gateway

Logs de Container:

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

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

# Últimas 50 linhas
docker logs --tail 50 <container-id>

Filtrar Logs:

# Filtrar por nível
docker service logs csuite-gateway_csuite-gateway | grep ERROR

# Filtrar por texto
docker service logs csuite-gateway_csuite-gateway | grep "authentication failed"

# Filtrar por timestamp
docker service logs csuite-gateway_csuite-gateway | grep "2025-01-02"

Níveis de Log

Níveis:
- DEBUG: Informações detalhadas para debugging
- INFO: Informações gerais sobre operação
- WARNING: Avisos sobre situações anômalas
- ERROR: Erros que não impedem operação
- CRITICAL: Erros críticos que impedem operação

Configuração:

import logging

# Configurar nível
logging.basicConfig(level=logging.INFO)

# Por ambiente
if os.getenv("DEBUG"):
    logging.basicConfig(level=logging.DEBUG)

🚨 Alertas

Alertas Críticos (P1)

Quando alertar:
- Serviço completamente inoperante
- Health check falhando por > 5 minutos
- Taxa de erro > 10%
- CPU > 95% por > 10 minutos
- Memória esgotada
- Disco > 90%

Ações:
- Notificar imediatamente equipe on-call
- Criar incidente
- Iniciar investigação

Alertas Altos (P2)

Quando alertar:
- Latência p95 > 1 segundo por > 5 minutos
- Taxa de erro > 5% por > 10 minutos
- CPU > 80% por > 30 minutos
- Memória > 85%
- Disco > 80%

Ações:
- Notificar equipe
- Investigar causa
- Monitorar evolução

Alertas Médios (P3)

Quando alertar:
- Latência p95 > 500ms por > 15 minutos
- Taxa de erro > 1% por > 30 minutos
- CPU > 70% por > 1 hora
- Memória > 75%

Ações:
- Registrar para análise
- Investigar se persistir
- Otimizar se necessário

Configuração de Alertas

Exemplo (se Prometheus/Alertmanager implementado):

# alertmanager.yml
groups:
  - name: csuite_alerts
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
        for: 5m
        annotations:
          summary: "High error rate detected"
          description: "Error rate is {{ $value }} errors/sec"

📊 Dashboards

Dashboard de Infraestrutura

Métricas a exibir:
- CPU usage por serviço
- Memória usage por serviço
- Disco usage
- Network I/O
- Container status

Exemplo (Grafana):
- Painel de CPU
- Painel de Memória
- Painel de Disco
- Painel de Rede
- Lista de serviços

Dashboard de Aplicação

Métricas a exibir:
- Requests por segundo
- Latência (p50, p95, p99)
- Taxa de erro
- Status codes (2xx, 4xx, 5xx)
- Endpoints mais acessados

Exemplo (Grafana):
- Gráfico de RPS
- Gráfico de latência
- Gráfico de taxa de erro
- Tabela de status codes
- Top endpoints

Dashboard de Negócio

Métricas a exibir:
- Decisões processadas
- Agentes ativos
- Políticas executadas
- Outcomes gerados
- Performance de decisões

Exemplo (Grafana):
- Gráfico de decisões/minuto
- Gráfico de agentes ativos
- Tabela de políticas
- Gráfico de outcomes

🔍 Troubleshooting

Problema: Métricas não aparecem

Diagnóstico:

# Verificar se Prometheus está rodando
docker ps | grep prometheus

# Verificar endpoints de métricas
curl http://localhost:9090/metrics

Solução:
- Verificar se métricas estão sendo expostas
- Verificar configuração do Prometheus
- Verificar rede entre serviços

Problema: Logs não aparecem

Diagnóstico:

# Verificar se logs estão sendo gerados
docker service logs csuite-gateway_csuite-gateway --tail 10

# Verificar configuração de logging
# (depende da implementação)

Solução:
- Verificar nível de log configurado
- Verificar se logs estão sendo escritos
- Verificar permissões de arquivo

Problema: Alertas não disparam

Diagnóstico:

# Verificar configuração de alertas
# (depende da implementação)

# Testar alerta manualmente
# (depende da ferramenta)

Solução:
- Verificar regras de alerta
- Verificar thresholds
- Verificar notificações configuradas

📚 Próximos Passos

Melhorias Planejadas

Q1 2025:
- [ ] Implementar Prometheus
- [ ] Implementar Grafana
- [ ] Configurar dashboards básicos
- [ ] Configurar alertas críticos

Q2 2025:
- [ ] Implementar ELK Stack
- [ ] Centralizar logs
- [ ] Implementar distributed tracing
- [ ] APM básico

Q3 2025:
- [ ] Dashboards avançados
- [ ] Alertas inteligentes
- [ ] Análise preditiva
- [ ] Otimização baseada em métricas

🔗 Documentos Relacionados

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

🔊 Text-to-Speech

1.0x
1.0
Pronto para reproduzir