ADR-028 — Observability

Architecture decision record — status: Accepted.

Source: docs/adr/ADR-028-observability.md

ADR-028: Observability

Estado

Accepted — 2026-08-23 · Amendment 2026-08-25 (Prom/Loki/Grafana profile; alineación IVPrior)

Contexto

Hay que diagnosticar API, jobs y fallos HTTP. FoodHub usa Prometheus + Loki + Grafana (ADR-018 allí). IVPrior no necesita Tempo/OTel el día 1, pero sí el mismo profile local opcional de métricas y logs.

Decisión

Fase V1 (ahora):

  • Logs estructurados JSON a stdout (LOG_LEVEL, correlation id). Sin cuerpos de email / PII (ADR-071).
  • Prometheus scrape de GET /api/v1/metrics (+ METRICS_BEARER_TOKEN en non-local).
  • Loki + Promtail + Grafana vía make observability-up (profile Docker). Puertos locales documentados en docs/ops/go-live/observability-stack.md.
  • Sentry (o equivalente) previsto para excepciones api + web — DSN en env; SDK puede llegar en slice siguiente.
  • Métricas de producto (Cash Recovered, DSO) siguen en dashboard / DOC-021, no en Grafana.

Fase posterior: OpenTelemetry + traces si el volumen de jobs lo exige.

Alternativas

Solo Sentry sin Prom/Grafana: insuficiente para latencia/volumen HTTP. Solo OTel día 1: costo alto para discovery.

Consecuencias

  • Logger es un puerto; no console.log en dominio.
  • Audit de producto (Postgres) ≠ Loki (ops). Misma separación que IVPrior.
  • Producción: Grafana/credenciales y scrape bearer son de IVPrior, no reutilizar stack IVPrior.