Métricas Prometheus Padronizadas - C-Suite

Visão Geral

Este documento descreve o sistema de métricas Prometheus padronizado para todos os apps do ecossistema C-Suite.

Módulo de Métricas

Localização

O módulo principal está em: common_metrics.py (raiz do projeto)

Características

• Métricas padrão: HTTP requests, latência, erros, cache, banco de dados
• Router FastAPI: Endpoint /metrics automático
• Middleware: Coleta automática de métricas HTTP
• Métricas customizadas: Suporte a métricas de negócio

Uso Básico

1. Adicionar Métricas ao App

from fastapi import FastAPI
from common_metrics import create_metrics_router, create_metrics_middleware

app = FastAPI()

# Adiciona router de métricas
metrics_router = create_metrics_router("csuite-executive")
app.include_router(metrics_router)

# Adiciona middleware para coleta automática
app.middleware("http")(create_metrics_middleware("csuite-executive"))

2. Registrar Métricas Customizadas

from common_metrics import business_metrics, errors_total, cache_hits

# Métrica de negócio
business_metrics.labels(
    metric_name="decisions_today",
    org_id=1,
    app="csuite-executive"
).set(1250)

# Erro
errors_total.labels(
    error_type="ValidationError",
    app="csuite-executive"
).inc()

# Cache hit
cache_hits.labels(
    cache_type="policy",
    app="csuite-executive"
).inc()

3. Métricas de Banco de Dados

from common_metrics import database_query_duration, database_connections
import time

# Medir duração de query
start = time.time()
result = db.execute(query)
duration = time.time() - start

database_query_duration.labels(
    database="csuite",
    query_type="SELECT",
    app="csuite-executive"
).observe(duration)

# Conexões ativas
database_connections.labels(
    database="csuite",
    app="csuite-executive"
).set(active_connections)

Métricas Disponíveis

HTTP

• http_requests_total: Total de requisições HTTP
• http_request_duration_seconds: Duração de requisições HTTP
• http_request_size_bytes: Tamanho de requisições HTTP
• http_response_size_bytes: Tamanho de respostas HTTP
• http_active_requests: Requisições HTTP ativas

Banco de Dados

• database_connections_active: Conexões de banco ativas
• database_query_duration_seconds: Duração de queries

Cache

• cache_hits_total: Total de cache hits
• cache_misses_total: Total de cache misses
• cache_operations_total: Total de operações de cache

APIs Externas

• external_api_calls_total: Total de chamadas a APIs externas
• external_api_duration_seconds: Duração de chamadas a APIs externas

Erros

• errors_total: Total de erros por tipo

Negócio

• business_metric: Métricas de negócio customizadas

Configuração do Prometheus

Arquivo de Configuração

O arquivo prometheus/prometheus.yml contém a configuração unificada para todos os apps.

Jobs Configurados

• 4c-decision-api
• 4c-executor
• 4c-feature-service
• 4c-scoring-service
• csuite-executive
• 4c-suite
• csuite-sales-manager-manager-api
• csuite-sales-manager-decision-api
• csuite-context

Scrape Interval

• Apps: 15 segundos
• Infrastructure: 30 segundos

Alertas

Arquivo de Alertas

O arquivo prometheus/alerts.yml contém alertas unificados para todos os apps.

Alertas Configurados

1. Disponibilidade

2. AppDown: App não está respondendo

3. Erros HTTP

4. HighErrorRate: Taxa de erro > 1%

5. CriticalErrorRate: Taxa de erro > 5%

6. Latência

7. HighLatency: P95 > 1s

8. CriticalLatency: P95 > 5s

9. Banco de Dados

10. HighDatabaseConnections: > 80 conexões

11. SlowDatabaseQueries: P95 > 1s

12. Cache

13. LowCacheHitRate: Taxa de hit < 50%

14. APIs Externas

15. ExternalAPIFailure: Taxa de falha > 10%

16. Erros Gerais

17. HighErrorCount: > 10 erros/segundo

18. Negócio

19. BusinessMetricAnomaly: Desvio > 20% da média

Grafana Dashboards

Dashboard Unificado

Criar dashboard no Grafana que consolide métricas de todos os apps:

• Visão geral do organismo
• Métricas por app
• Métricas de negócio
• Alertas consolidados

Queries Úteis

# Taxa de requisições por app
sum(rate(http_requests_total[5m])) by (app)

# Latência P95 por app
histogram_quantile(0.95,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le, app)
)

# Taxa de erro por app
sum(rate(http_requests_total{status=~"5.."}[5m])) by (app)
/
sum(rate(http_requests_total[5m])) by (app)

# Taxa de cache hit
sum(rate(cache_hits_total[10m])) by (cache_type, app)
/
(sum(rate(cache_hits_total[10m])) by (cache_type, app) +
 sum(rate(cache_misses_total[10m])) by (cache_type, app))

Integração nos Apps

4c-suite

from common_metrics import create_metrics_router, create_metrics_middleware

metrics_router = create_metrics_router("4c-suite")
app.include_router(metrics_router)
app.middleware("http")(create_metrics_middleware("4c-suite"))

csuite-executive

from common_metrics import create_metrics_router, create_metrics_middleware

metrics_router = create_metrics_router("csuite-executive")
app.include_router(metrics_router)
app.middleware("http")(create_metrics_middleware("csuite-executive"))

csuite-sales-manager

from common_metrics import create_metrics_router, create_metrics_middleware

# Manager API
metrics_router = create_metrics_router("csuite-sales-manager-manager-api")
app.include_router(metrics_router)
app.middleware("http")(create_metrics_middleware("csuite-sales-manager-manager-api"))

# Decision API
metrics_router = create_metrics_router("csuite-sales-manager-decision-api")
app.include_router(metrics_router)
app.middleware("http")(create_metrics_middleware("csuite-sales-manager-decision-api"))

Próximos Passos

1. ✅ Módulo de métricas criado
2. ✅ Configuração Prometheus unificada criada
3. ✅ Alertas unificados criados
4. ⏳ Integrar métricas em todos os apps
5. ⏳ Criar dashboard Grafana unificado
6. ⏳ Configurar Alertmanager
7. ⏳ Adicionar métricas de negócio específicas