# Estratégia de Logs — Mud Sentinel

**Documento:** `operacao/03-logs.md`  
**Versão:** 1.0.0  
**Status:** Vigente

---

## 1. Objetivo

Padronizar logging **estruturado**, correlacionável e seguro — suporte a operação e debugging sem confundir com trilha de auditoria.

---

## 2. Distinções obrigatórias

| Canal | Propósito |
|-------|-----------|
| Application logs | Diagnóstico operacional |
| Audit events | Accountability (ver política de auditoria) |
| Metrics/traces | SLO e performance |

Não usar `log.info("user exported case")` como substituto de AuditEvent.

---

## 3. Formato

JSON em stdout (containers) com campos padrão:

```text
timestamp        ISO-8601 UTC
level            debug|info|warn|error|fatal
message          short human string
service          api|worker|web
module           catalog|graph|...
env              prod|staging|local
version          gitsha / semver
request_id       UUID
correlation_id   UUID
tenant_id        UUID | null
actor_id         string | null
event_name       optional machine key
error_type       optional
stack            only on error, sampled/redacted
```

**Justificativa:** JSON habilita Loki/ELK e consultas confiáveis; campos de correlação ligam API → workers → providers.

---

## 4. Níveis

| Nível | Uso |
|-------|-----|
| debug | Detalhe de dev; desligado/default sample em prod |
| info | Marcos de fluxo (start job, finish job) |
| warn | Degradations, retries, fallbacks |
| error | Falhas com impacto; incluir error_type |
| fatal | Processo inviável |

---

## 5. Redação e privacidade

**Proibido em logs:**

- Senhas, tokens, cookies, authorization headers.
- Payloads completos de documentos de identificação quando evitável.
- Corpo completo de prompts/respostas de IA em produção (usar ids + hashes; sample controlado em staging).
- Secrets de conectores.

**Permitido com cuidado:** IDs opacos, contagens, códigos de erro de provedor, latências.

Mascaramento automático de padrões (JWT-like, chaves) no middleware de log é desejável.

---

## 6. Correlação

- Gerar `request_id` na borda HTTP se ausente.
- Propagar `correlation_id` / W3C `traceparent` via OpenTelemetry para workers (jobs herdam contexto).
- Incluir `causation_id` do evento quando processamento for event-driven.

---

## 7. Volume e cardinalidade

- Não logar por item em loops quentes sem sampling.
- Evitar campos de alta cardinalidade sem necessidade (ex.: URL crua com tokens).
- Sampling de debug em produção.

**Justificativa:** custo de storage e ruído operacional.

---

## 8. Retenção de logs

| Ambiente | Retenção sugerida |
|----------|-------------------|
| Production | 30–90 dias hot; cold conforme custo |
| Staging | 7–30 dias |
| Local | disco do desenvolvedor |

Requisitos legais de accountability residem na **auditoria**, não nos logs.

---

## 9. Stack

OpenTelemetry SDK → collector → Loki (logs) + Tempo/Jaeger (traces) + Prometheus (metrics).  
Error tracking (Sentry) para exceptions com fingerprinting.

| Alternativa | Prós | Contras |
|-------------|------|---------|
| ELK completo | Poderoso | Mais pesado ops |
| Cloud vendor logging | Rápido | Lock-in / custo |

Escolha: OTEL como abstração para portabilidade.

---

## 10. Padrões de mensagem

- Mensagens curtas e estáveis: `ingest_run_failed`, não prosa longa variável.
- Detalhes em campos estruturados, não concatenados na message.

---

## 11. Compliance com desenvolvimento

- Library `packages/observability` (quando existir) é o **único** jeito preferencial de logar.
- Proibir `print()` em código de produção.