Estrategia de Observabilidad¶

Proposito¶

Definir como monitoreamos, diagnosticamos, y entendemos el comportamiento del sistema en produccion. Los tres pilares: logs, metricas, y trazas.

1. Los Tres Pilares¶

                    OBSERVABILIDAD
                    /     |      \
                   /      |       \
              LOGS    METRICAS    TRAZAS
              (Que paso?) (Como va?) (Donde tardo?)

Logs: Que paso?¶

Registros de eventos discretos. Para investigar problemas especificos.

Metricas: Como va?¶

Valores numericos agregados en el tiempo. Para dashboards y alertas.

Trazas: Donde tardo?¶

Seguimiento de una request a traves de multiples servicios. Para entender latencia.

2. Logs¶

Formato: JSON estructurado¶

{
  "timestamp": "2025-03-24T10:30:15.123Z",
  "level": "error",
  "service": "booking-api",
  "traceId": "abc-123-def",
  "userId": "user-456",
  "action": "booking.create",
  "message": "Failed to create booking: slot already taken",
  "error": {
    "code": "SLOT_ALREADY_BOOKED",
    "doctorId": "doc-789",
    "date": "2025-03-25",
    "startTime": "09:00"
  },
  "duration_ms": 45
}

Que loggear (y que NO)¶

Loggear	NO loggear
Errores con contexto (que fallo, con que datos)	Passwords, tokens, o datos de salud
Acciones de negocio (booking creado, cancelado)	Cada query SQL (demasiado ruido)
Requests lentos (> umbral)	Request/response bodies completos
Intentos de login fallidos (seguridad)	Datos personales en texto plano
Cambios de estado significativos	Logs de debug en produccion

Niveles de Log¶

Nivel	Cuando	Ejemplo
ERROR	Algo fallo y requiere atencion	"Failed to connect to database"
WARN	Algo inesperado pero no critico	"Retry 2/3 sending email"
INFO	Acciones de negocio relevantes	"Booking b-123 created by patient p-456"
DEBUG	Solo en desarrollo/staging	"Query result: 15 available slots"

Herramientas recomendadas¶

Desarrollo: pino o winston (NestJS).
Agregacion: ELK Stack (Elasticsearch + Logstash + Kibana) o Grafana Loki.
Cloud: AWS CloudWatch Logs, Datadog Logs.

3. Metricas¶

Metricas clave del sistema (RED Method)¶

Metrica	Que mide	SLI	SLO
Rate	Requests por segundo	req/s por endpoint	Baseline + 20%
Errors	Porcentaje de errores (5xx)	5xx / total requests	< 1%
Duration	Latencia de requests	p95 response time	< 500ms

Metricas de negocio¶

Metrica	Descripcion	Alerta si
bookings_created_total	Turnos reservados (counter)	< 10 en 1 hora (horario laboral)
bookings_cancelled_total	Turnos cancelados (counter)	> 50% de creados
booking_conflict_total	Conflictos de concurrencia	> 5 en 5 min
login_failed_total	Logins fallidos	> 100 en 10 min (posible ataque)
active_users_gauge	Usuarios con sesion activa	N/A (informativo)

Metricas de infraestructura¶

Metrica	Alerta si
CPU usage	> 80% por 5 min
Memory usage	> 85%
DB connections active	> 80% del pool
DB query duration p95	> 200ms
Disk usage	> 80%

Herramientas recomendadas¶

Recoleccion: Prometheus (pull) o StatsD (push).
Visualizacion: Grafana.
Cloud: Datadog, New Relic, AWS CloudWatch.

4. Trazas (Distributed Tracing)¶

Cuando necesitas trazas¶

Cuando una request pasa por multiples servicios.
Cuando necesitas entender donde se gasta el tiempo.
Para diagnosticar latencia intermitente.

Ejemplo de traza del flujo de reserva¶

[POST /api/v1/bookings] (total: 120ms)
  |
  +-- [AuthGuard: verify JWT] (5ms)
  |
  +-- [BookingService.create] (100ms)
  |     |
  |     +-- [AvailabilityCheck: query DB] (30ms)
  |     |
  |     +-- [BookingRepo.save: INSERT with lock] (50ms)
  |     |
  |     +-- [EventEmitter: BookingConfirmed] (5ms)
  |     |
  |     +-- [NotificationQueue: enqueue email] (15ms)
  |
  +-- [Serialize response] (2ms)

Herramientas recomendadas¶

Instrumentacion: OpenTelemetry (estandar abierto).
Backend: Jaeger, Zipkin, o Grafana Tempo.
Cloud: Datadog APM, AWS X-Ray.

5. Alertas¶

Principios de alertas¶

Alerta sobre sintomas, no causas. Alerta "API latencia > 1s" no "CPU > 80%" (el CPU alto puede no afectar al usuario).
Cada alerta debe ser actionable. Si no puedes hacer nada cuando suena, no es una alerta.
Evita alert fatigue. Pocas alertas criticas que siempre importan > muchas alertas que se ignoran.

Alertas criticas (despiertan a alguien)¶

Alerta	Condicion	Runbook
API Down	Health check falla 3 veces consecutivas	runbook-api-down.md
Error rate alto	> 5% de requests son 5xx por 5 min	runbook-high-error-rate.md
BD no responde	Connection timeout > 30s	runbook-db-connection.md
Latencia extrema	p95 > 3s por 5 min	runbook-high-latency.md

Alertas de warning (revisa en horario laboral)¶

Alerta	Condicion
Pool de conexiones alto	> 70% del pool en uso
Disco casi lleno	> 80% de uso
Certificado por expirar	< 14 dias para expirar
Muchos logins fallidos	> 50 en 10 min

6. Dashboards¶

Dashboard 1: Overview del Sistema¶

Request rate (req/s)
Error rate (%)
Latencia p50, p95, p99
Usuarios activos
Health check status

Dashboard 2: Bookings (Negocio)¶

Bookings creados por hora
Bookings cancelados por hora
Conflictos de concurrencia
Top especialidades por reservas
Tasa de no-show

Dashboard 3: Infraestructura¶

CPU / Memory por instancia
Conexiones activas a BD
Query duration p95
Cola de notificaciones (pending / processed / failed)

Checklist de Completitud¶

Tres pilares documentados (logs, metricas, trazas)
Formato de logs definido
Metricas RED + negocio + infra
Alertas con condiciones y runbooks
Dashboards definidos
Revisada por otro ingeniero

Archivos relacionados¶

_template.runbook.md - Plantilla de runbook
ci-cd-pipeline.md - Pipeline CI/CD
infrastructure-as-code.md - IaC
../02-architecture/system-design.md - Arquitectura