backend-observability

Backend observability

Cuándo usar

• Crear un servicio nuevo o un endpoint sensible.
• Investigar un incidente y faltan datos.
• Definir alertas o dashboards.

Pilares

1. Logs — eventos discretos, con contexto, estructurados (JSON).
2. Métricas — series temporales agregables.
3. Trazas — el camino de un request por varios servicios.

Sin los tres, falta una pata: logs sin métricas no escalan, métricas sin trazas no explican causa.

Logs

• Estructurados ({"ts":..., "level":..., "msg":..., "request_id":..., ...}), nunca strings sueltos.
• Niveles bien usados:
  • DEBUG — detalle de desarrollo. Off en producción.
  • INFO — eventos esperados (request servido, job ok). Bajo volumen.
  • WARN — anomalía recuperada (reintento, fallback). Mirar tendencias.
  • ERROR — fallo no recuperado en un request/job. Debería alertar si sube.
  • FATAL — el proceso no puede continuar.
• Un log por evento de negocio. No logs decorativos cada 3 líneas.
• request_id propagado en todo log de la cadena. Si no podés correlacionar, no podés debuggear.

Qué NUNCA loguear

• Contraseñas, tokens, claves, header Authorization, cookies de sesión.
• PII completa: número de tarjeta, RUT/DNI, mail, teléfono. Hashear o truncar si hace falta.
• Cuerpo de request/response salvo en debug local explícito.
• Stack traces a clientes (sí internamente).

Métricas — Four Golden Signals

Para todo servicio:

1. Latency — p50, p95, p99 por endpoint. Promedio miente.
2. Traffic — requests/seg, por ruta y método.
3. Errors — tasa de 5xx (y 4xx interesantes como 429).
4. Saturation — CPU, memoria, conexiones a BD, cola.

Para jobs: éxito/falla/duración/cola.

Convenciones

• Histogramas, no solo contadores, para latencias.
• Cardinalidad bajo control: user_id como label rompe Prometheus.
• Nombres consistentes: http_request_duration_seconds, db_query_duration_seconds.

Trazas

• OpenTelemetry como estándar. Cliente + auto-instrumentación + exportador a Jaeger/Tempo/Honeycomb.
• Propagá traceparent entre servicios.
• Span por unidad de trabajo significativa (request, query, llamada externa, job).
• Atributos útiles: http.route, db.statement (sanitizado), messaging.destination.