# Estratégia de Monitoramento — Mud Sentinel

**Documento:** `operacao/04-monitoramento.md`  
**Versão:** 1.0.0  
**Status:** Vigente

---

## 1. Objetivo

Detectar degradação antes do cliente; cumprir SLOs; sustentar operação de ingestão, busca, grafo e IA com alertas acionáveis.

---

## 2. Pilares

1. **Metrics** — o que está quebrando/ degradando.
2. **Logs** — contexto.
3. **Traces** — onde está a latência.
4. **Synthetics** — verificação externa de caminhos P0.
5. **Status page** (evolução) — comunicação.

---

## 3. SLOs iniciais (proposta)

| Serviço | SLI | SLO alvo (MVP) |
|---------|-----|----------------|
| API disponibilidade | Success rate 5xx excl. manutenções | 99.5% mensal |
| Latência busca entidades | p95 latency | ≤ 800 ms (staging-like volume) |
| Latência ficha | p95 | ≤ 500 ms |
| Lag de ingestão | Tempo publish → searchable | ≤ 15 min p95 (fontes piloto) |
| Fila workers | Lag / depth | abaixo de limiar definido por fila |
| Escrita de auditoria | success rate | ≥ 99.9% |

Valores serão calibrados com baseline real pós-piloto; não são marketing — são orçamento de erro interno.

**Justificativa:** SLOs explícitos evitam “tudo crítico” e guiam capacity planning.

---

## 4. Métricas golden signals

Por serviço: **latency, traffic, errors, saturation**.

Métricas de domínio adicionais:

| Métrica | Por quê |
|---------|---------|
| `mud_ingest_lag_seconds` | Frescor do produto |
| `mud_graph_expansion_nodes` | Detecção de abuso/custo |
| `mud_ai_completion_tokens` | Custo e abuso |
| `mud_ai_completion_errors` | Dependência de provedor |
| `mud_audit_write_failures` | Risco compliance |
| `mud_tenant_quota_exhaustions` | UX e billing |

---

## 5. Alertas — princípios

1. Alerta ⇒ ação humana clara.
2. Severidade: page / ticket / info.
3. Preferir alertas em **sintomas** (SLO burn) a causas (CPU).
4. Runbook linkado em cada alerta paging.

Exemplos paging:

- API error budget burn rápido.
- Audit writes falhando.
- DLQ depth crescente.
- Certificados perto de expirar.
- Disco/DB saturation.

---

## 6. Dashboards mínimos

1. Overview API (RPS, p95, 5xx, saturação).
2. Ingestion (runs, lag, DLQ, por conector).
3. Search/Graph (latência, erros, timeouts).
4. AI (latência, erros, custo tokens, quotas).
5. Tenancy/Security (auth failures spike, 401/403 anômalos).

---

## 7. Tracing

- Amostragem head-based em prod (ex.: 1–5%) + always-on em erros.
- Spans em: HTTP handlers, DB, Redis, HTTP providers, LLM calls (sem payload sensível).

---

## 8. Synthetics / smoke

Jobs autenticados em staging/prod que executam:

1. Health endpoints.
2. Busca known fixture.
3. (Staging) criar caso + export soft.

Falhas geram alerta.

---

## 9. On-call e severidade

| Sev | Definição | Resposta |
|-----|-----------|----------|
| SEV1 | Outage completo / vazamento | Imediato |
| SEV2 | Degradação major (busca fora, ingestão parada) | < 30 min |
| SEV3 | Impacto parcial | horário comercial |
| SEV4 | Cosmético / low | backlog |

---

## 10. Capacidade e custo

Monitorar custo de:

- LLM tokens por tenant.
- OpenSearch storage.
- Object storage de raw.

Alertas de anomalia de custo evitam bill shock — crítico em SaaS com IA.

---

## 11. Ferramentas

OpenTelemetry + Prometheus + Grafana + Loki + Tempo/Jaeger + (opcional) pager (PagerDuty/OpsGenie).

| Alternativa all-in-one (Datadog etc.) | Prós: velocidade | Contras: custo/lock-in |
|------|------|------|
| Decisão | OTEL-first permite trocar vendors sem reescrever app | |

---

## 12. Relação com product analytics

Product analytics (funil, TTFV) usa pipeline **separado**, sem PII desnecessária, e não substitui monitoring de SRE.