Health Checks Padronizados - C-Suite
Visão Geral
Este documento descreve o sistema de health checks padronizado para todos os apps do ecossistema C-Suite. O objetivo é ter endpoints consistentes para verificar a saúde e readiness dos serviços.
Módulo de Health Checks
Localização
O módulo principal está em: common_health.py (raiz do projeto)
Uso Básico
from fastapi import FastAPI
from common_health import create_health_router
app = FastAPI()
# Criar router de health checks
health_router = create_health_router(
app_name="meu-app",
dependencies=["database:csuite", "redis"]
)
# Incluir no app
app.include_router(health_router)
Endpoints Disponíveis
GET /health
Health check básico - verifica apenas se o app está rodando.
Resposta (200):
{
"status": "healthy",
"app": "meu-app",
"timestamp": "2025-12-01T10:30:00Z"
}
Uso: Verificar se o processo está ativo (liveness probe)
GET /ready
Readiness check - verifica se o app está pronto para receber tráfego, incluindo todas as dependências.
Resposta (200):
{
"status": "healthy",
"app": "meu-app",
"timestamp": "2025-12-01T10:30:00Z",
"dependencies": [
{
"name": "database_csuite",
"status": "healthy",
"message": "Conexão OK",
"response_time_ms": 12.34
},
{
"name": "redis",
"status": "healthy",
"message": "Conexão OK",
"response_time_ms": 2.45
}
]
}
Resposta (503) - Se dependências não estiverem saudáveis:
{
"status": "unhealthy",
"app": "meu-app",
"timestamp": "2025-12-01T10:30:00Z",
"dependencies": [
{
"name": "database_csuite",
"status": "unhealthy",
"message": "Connection refused",
"response_time_ms": 2000.0
}
]
}
Uso: Verificar se o app está pronto para receber tráfego (readiness probe)
GET /health/detailed
Health check detalhado - sempre retorna 200, mesmo se dependências estiverem com problemas. Útil para diagnóstico.
Resposta (200):
{
"status": "unhealthy",
"app": "meu-app",
"timestamp": "2025-12-01T10:30:00Z",
"dependencies": [
{
"name": "database_csuite",
"status": "unhealthy",
"message": "Connection refused",
"response_time_ms": 2000.0
}
]
}
Uso: Diagnóstico detalhado sem afetar load balancer
Dependências Suportadas
Database
Verifica conexão com banco de dados MySQL.
Sintaxe:
- database - Banco padrão (csuite)
- database:csuite - Banco C-Suite
- database:core - Banco 4C (core)
- database:staging - Banco staging
Exemplo:
health_router = create_health_router(
app_name="meu-app",
dependencies=["database:csuite"]
)
Redis
Verifica conexão com Redis.
Sintaxe:
- redis
Exemplo:
health_router = create_health_router(
app_name="meu-app",
dependencies=["redis"]
)
Variáveis de ambiente necessárias:
- REDIS_HOST (padrão: localhost)
- REDIS_PORT (padrão: 6379)
External Service
Verifica se um serviço externo está respondendo via HTTP.
Sintaxe:
- external_service:name:url
Exemplo:
health_router = create_health_router(
app_name="meu-app",
dependencies=[
"external_service:feature_service:http://feature-service:8081",
"external_service:scoring_service:http://scoring-service:8082"
]
)
Custom Checker
Você pode registrar checkers customizados:
from common_health import DependencyStatus, HealthStatus
def check_my_service() -> DependencyStatus:
# Sua lógica de verificação
try:
# Verificar algo
return DependencyStatus(
name="my_service",
status=HealthStatus.HEALTHY,
message="OK"
)
except Exception as e:
return DependencyStatus(
name="my_service",
status=HealthStatus.UNHEALTHY,
message=str(e)
)
health_router = create_health_router(
app_name="meu-app",
dependencies=["database:csuite"],
custom_checkers={"my_service": check_my_service}
)
Status de Saúde
healthy
Todas as dependências estão funcionando corretamente.
unhealthy
Uma ou mais dependências críticas estão com problemas. O app não deve receber tráfego.
degraded
Algumas dependências não críticas estão com problemas, mas o app ainda pode funcionar.
Integração com Load Balancer
Docker Swarm / Kubernetes
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
# Readiness probe
readiness_probe:
http_get:
path: /ready
port: 8000
initial_delay_seconds: 10
period_seconds: 5
timeout_seconds: 3
failure_threshold: 3
# Liveness probe
liveness_probe:
http_get:
path: /health
port: 8000
initial_delay_seconds: 30
period_seconds: 10
timeout_seconds: 5
failure_threshold: 3
Traefik
labels:
- "traefik.http.services.meu-app.loadbalancer.healthcheck.path=/health"
- "traefik.http.services.meu-app.loadbalancer.healthcheck.interval=30s"
Exemplos de Uso por App
4c-suite (Orquestrador)
health_router = create_health_router(
app_name="4c-suite",
dependencies=[
"external_service:fourc_decision_api:http://decision-api:8080",
"external_service:csuite_api:http://csuite-api:8000"
]
)
csuite-executive
health_router = create_health_router(
app_name="csuite-executive",
dependencies=["database:csuite"]
)
4c Decision API
health_router = create_health_router(
app_name="4c-decision-api",
dependencies=[
"database:core",
"redis",
"external_service:feature_service:http://feature-service:8081",
"external_service:scoring_service:http://scoring-service:8082"
]
)
Troubleshooting
Health check falha
- Verifique logs do app
- Verifique se dependências estão acessíveis
- Use
/health/detailedpara diagnóstico
Dependência sempre unhealthy
- Verifique variáveis de ambiente
- Verifique conectividade de rede
- Verifique timeouts (padrão: 2 segundos)
Response time alto
- Verifique latência de rede
- Verifique carga do banco/Redis
- Considere aumentar timeout se necessário
Próximos Passos
- ✅ Módulo de health checks criado
- ✅ Apps 4c-suite e csuite-executive atualizados
- ⏳ Adicionar health checks em todos os apps restantes
- ⏳ Configurar probes no Kubernetes/Docker Swarm
- ⏳ Integrar com monitoramento (Prometheus, Grafana)