Signal Path: De la métrica al post-mortem

Monitoring no es observabilidad

El monitoring responde preguntas que ya sabías que ibas a hacer: ¿el contenedor está arriba?, ¿la CPU pasó 80%?, ¿el endpoint responde? La observabilidad te deja responder preguntas que no anticipaste: ¿por qué solo algunas requests de /checkout tardaron 8 segundos entre las 14:02 y las 14:07?

La materia prima son los datos que tu sistema emite —la telemetría— y las tres señales clásicas son métricas, logs y trazas. Cada una responde una pregunta distinta, y el valor real aparece cuando las conectas.

Los cuatro Golden Signals

Latencia (cuánto tardan las requests), tráfico (cuánto trabajo entra), errores (cuántas fallan) y saturación (qué tan cerca del límite estás). Con esos cuatro números respondes en diez segundos si un servicio está sano.

Dos métodos derivados te ordenan el trabajo: RED (Rate, Errors, Duration) mira el servicio desde el usuario; USE (Utilization, Saturation, Errors) mira el recurso — CPU, memoria, disco, conexiones de base. Un buen dashboard usa los dos, en ese orden: primero impacto, después causa.

Percentiles, no promedios

Si 99 requests tardan 100 ms y una tarda 10 s, el promedio te miente y ese usuario se fue. Por eso se mide p50 (experiencia típica), p95 (la que se usa para acuerdos) y p99 (la cola larga, donde viven los timeouts y los reintentos).

Tres tipos de métrica alcanzan para casi todo

Un counter solo sube y cuenta eventos: requests, errores, mensajes procesados. Un gauge sube y baja y mide un estado instantáneo: conexiones abiertas, items en cola, memoria. Un histogram reparte observaciones en buckets y es lo que te permite calcular percentiles de latencia del lado del servidor.

La instrumentación mínima de cualquier servicio HTTP son dos métricas: un counter de requests con labels route, method y status, y un histogram de duración con las mismas labels.

Prometheus en Docker Compose

services:
  prometheus:
    image: prom/prometheus:latest
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.retention.time=15d
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prom-data:/prometheus
    ports: ["9090:9090"]

El scrape config apunta a tu servicio por nombre de red interna: en Compose (y en un stack de Coolify o Portainer) los contenedores se ven entre sí por su nombre de servicio, así que targets: ['api:3000'] alcanza. Nunca expongas /metrics a internet sin protección.

Las tres queries que vas a usar siempre

# tráfico (req/s)
sum(rate(http_requests_total[5m]))

# error rate (proporción de 5xx)
sum(rate(http_requests_total{status=~"5.."}[5m]))
/ sum(rate(http_requests_total[5m]))

# latencia p95
histogram_quantile(0.95,
  sum by (le) (rate(http_request_duration_seconds_bucket[5m])))

El orden importa más que los paneles

Un dashboard operativo se lee de arriba hacia abajo como un triage. Capa 1: impacto — disponibilidad, error rate, latencia, presupuesto de error. Capa 2: RED — tráfico, errores y duración por ruta. Capa 3: saturación — CPU, memoria, réplicas, reinicios, pool de conexiones. Capa 4 y 5 (a partir del módulo 6): logs y trazas del período que estás mirando.

Grafana también va en el compose

  grafana:
    image: grafana/grafana:latest
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
      - GF_USERS_ALLOW_SIGN_UP=false
    volumes:
      - grafana-data:/var/lib/grafana
      - ./grafana/provisioning:/etc/grafana/provisioning:ro
    ports: ["3001:3000"]

El volumen de provisioning es lo que separa un juguete de algo operable: datasources y dashboards definidos por archivo, versionados en git, reproducibles en otro VPS. Un dashboard hecho a mano en la UI y no exportado se pierde el día que el volumen se rompe.

Variables: un tablero, muchos servicios

En vez de clonar el dashboard por servicio, define una variable $service con una query label_values(http_requests_total, service) y úsala en todas las consultas. El mismo tablero sirve para tu API, tu worker y el bot de WhatsApp.

Tres siglas que no son sinónimos

El SLI es lo que mides (disponibilidad = 99,92%). El SLO es la meta interna que te pones (99,9% en 30 días). El SLA es un compromiso contractual con dinero o créditos de por medio. Casi ningún servicio necesita SLA; casi todos deberían tener SLO.

El presupuesto de error

Si el SLO es 99,9%, tienes permitido fallar el 0,1%. En 30 días eso son 43 minutos y 12 segundos de indisponibilidad. Ese presupuesto es una herramienta de decisión: mientras te sobre budget, puedes desplegar rápido y tomar riesgos; cuando lo quemaste, la prioridad pasa a ser estabilizar.

SLO 99.9%   → 43m 12s / 30 días
SLO 99.95%  → 21m 36s / 30 días
SLO 99.99%  →  4m 19s / 30 días

Burn rate: la velocidad de quema

El burn rate es cuánto más rápido de lo permitido estás gastando el presupuesto: error_ratio / (1 − SLO). Un burn rate de 1× consume el budget exactamente en 30 días. Un 14,4× lo consume en poco más de dos días — eso amerita despertar a alguien. Un 3× sostenido no es urgente esta noche, pero destruye el mes.

Recording rules: calcula una vez

groups:
  - name: slo
    interval: 30s
    rules:
      - record: job:http_error_ratio:rate5m
        expr: |
          sum(rate(http_requests_total{status=~"5.."}[5m]))
          / sum(rate(http_requests_total[5m]))
      - record: job:http_availability:ratio30d
        expr: 1 - (
          sum(rate(http_requests_total{status=~"5.."}[30d]))
          / sum(rate(http_requests_total[30d])))

El test de las tres de la mañana

Antes de crear una alerta, responde: si esto suena a las 3 AM, ¿alguien tiene que levantarse y hacer algo ahora? Si la respuesta es no, no es una página: es un ticket, o directamente ruido. La fatiga de alertas es la forma más rápida de que un equipo deje de mirar el celular.

Alertas multi-ventana de burn rate

La receta estándar de Google usa dos ventanas por severidad, para detectar rápido sin dispararse por un pico de treinta segundos: la ventana larga confirma que el problema es real, la corta confirma que sigue pasando.

groups:
  - name: slo-alerts
    rules:
      - alert: ErrorBudgetFastBurn
        expr: |
          job:http_error_ratio:rate1h > (14.4 * 0.001)
          and job:http_error_ratio:rate5m > (14.4 * 0.001)
        for: 2m
        labels: { severity: page }
        annotations:
          summary: "Quema rápida del presupuesto de error"
          runbook: "https://git.tu-dominio/runbooks/availability.md"

      - alert: ErrorBudgetSlowBurn
        expr: |
          job:http_error_ratio:rate6h > (6 * 0.001)
          and job:http_error_ratio:rate30m > (6 * 0.001)
        for: 15m
        labels: { severity: ticket }

Alertmanager decide quién se entera

Prometheus detecta la condición; Alertmanager hace el resto: agrupa alertas relacionadas para no mandar veinte mensajes, deduplica, silencia durante mantenimientos e inhibe alertas hijas cuando ya disparó la padre. La ruta se define por label: severity: page va al canal que despierta, severity: ticket al que se lee en horario laboral.

Toda alerta necesita un runbook

La anotación runbook no es decorativa: es el link que la persona de guardia abre medio dormida. Si la alerta no tiene runbook, todavía no está terminada.

Un log es un evento, no una frase

Log en texto libre: Error al procesar el pedido del usuario. Log estructurado:

{"ts":"2026-09-08T14:03:11Z","level":"error","service":"api",
 "route":"/orders/:id","status":500,"duration_ms":831,
 "trace_id":"b2fe643bc4d341a1f7076f265910e649","order_id":"o_8812",
 "msg":"payment gateway timeout"}

El segundo se puede filtrar, agrupar y contar. Los campos mínimos que no pueden faltar: timestamp, level, service, route, status, duration_ms y trace_id. Ese último campo es el que va a conectar este log con su traza en el módulo 8.

Loki no es Elasticsearch

Loki no indexa el contenido del log: indexa solo las labels del stream y guarda el resto comprimido. Por eso es barato de correr en un VPS, y por eso las labels tienen que ser pocas y de baja cardinalidad: service, env, level. Nada más.

Recolección en Docker

  loki:
    image: grafana/loki:latest
    command: -config.file=/etc/loki/local-config.yaml
    volumes: [ "loki-data:/loki" ]

  alloy:
    image: grafana/alloy:latest
    volumes:
      - ./alloy/config.alloy:/etc/alloy/config.alloy:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
    command: run /etc/alloy/config.alloy

Alloy descubre los contenedores por el socket de Docker, les pega labels a partir del nombre y las etiquetas del contenedor, y empuja a Loki. Alternativa más simple si tu VPS ya está ordenado: el driver de logs de Docker apuntando directo a Loki.

LogQL en tres movimientos

# todos los errores del servicio
{service="api", level="error"}

# solo 5xx, parseando el JSON
{service="api"} | json | status >= 500

# tasa de errores por ruta, últimos 5 minutos
sum by (route) (
  rate({service="api"} | json | status >= 500 [5m]))

Traza, span y contexto

Una traza es el recorrido completo de una request a través de tu sistema. Cada etapa medible es un span: la request HTTP entrante, la query a Postgres, el GET a la API de pagos, el job que se encoló. Los spans forman un árbol, y ahí se ve inmediatamente dónde se fue el tiempo:

POST /orders                    2.41s
├── auth.verify                  38ms
├── db.query orders_insert      142ms
├── http POST payments.api      2.14s   ←
└── queue.publish order.created  21ms

La conclusión no es "la app está lenta": es "la pasarela de pagos se está comiendo el 89% del tiempo". Son dos conversaciones completamente distintas.

OpenTelemetry: instrumentar una vez

OTel es el estándar abierto que te evita quedar atado a un proveedor: instrumentas con su SDK y después decides a dónde mandas los datos — Tempo hoy, Datadog o Grafana Cloud mañana, sin tocar el código de la app.

La auto-instrumentación cubre lo obvio (servidor HTTP, cliente HTTP, driver de base, Redis) con muy poco código. Los spans manuales los agregas donde está tu lógica cara: el cálculo pesado, la llamada al LLM, el render del PDF.

El Collector como amortiguador

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    command: ["--config=/etc/otel/config.yaml"]
    volumes: [ "./otel/config.yaml:/etc/otel/config.yaml:ro" ]
    ports: ["4318:4318"]   # OTLP/HTTP

  tempo:
    image: grafana/tempo:latest
    command: ["-config.file=/etc/tempo.yaml"]
    volumes:
      - ./tempo/tempo.yaml:/etc/tempo.yaml:ro
      - tempo-data:/var/tempo

La app habla OTLP con el Collector, y el Collector decide qué hacer: filtrar spans de health checks, samplear, agregar atributos de entorno, y exportar a Tempo. Cambiar de backend después es cambiar un exporter, no redeployar la aplicación.

TraceQL para encontrar la aguja

{ resource.service.name = "api" && duration > 1s }
{ span.http.status_code >= 500 }
{ name = "http POST payments.api" && duration > 2s }

Una llave común: trace_id

Las tres señales que armaste hasta aquí viven en bases distintas. Lo que las conecta es un identificador que viaja con la request: el trace_id. Si tu histogram lo adjunta como exemplar, tu log lo escribe como campo y tu traza lo tiene por definición, puedes recorrer el camino completo sin escribir una sola query a mano.

Exemplars: de la métrica a la traza

Un exemplar es un punto concreto adjuntado a un bucket del histogram, con el trace_id de una request real que cayó ahí. En el gráfico de latencia aparece como un puntito sobre la curva: haces click y se abre la traza que produjo ese valor.

# Prometheus necesita el feature habilitado
command:
  - --enable-feature=exemplar-storage

# y el scrape en formato OpenMetrics
scrape_configs:
  - job_name: api
    static_configs: [{ targets: ["api:3000"] }]

Del lado de la app, la librería de Prometheus tiene que registrar la observación con el exemplar del trace activo. En Node con prom-client se pasa como tercer argumento del observe(); en Python, con exemplar=.

Derived fields: del log a la traza

En la configuración del datasource de Loki defines un campo derivado que detecta el trace_id en el JSON y lo convierte en un botón que abre Tempo:

derivedFields:
  - name: TraceID
    matcherRegex: '"trace_id":"(\w+)"'
    url: '${__value.raw}'
    datasourceUid: tempo

Y en el datasource de Tempo activas el camino inverso (Trace to logs): desde un span, saltar a los logs de ese mismo trace_id en la ventana de tiempo del span. Ida y vuelta cerrada.

El recorrido completo

Alerta de burn rate
      ↓  (link del runbook)
Dashboard: p95 en 12s desde las 14:02
      ↓  (click en el exemplar)
Traza: POST /orders — 11.8s en payments.api
      ↓  (Trace to logs)
Log: "payment gateway timeout" order_id=o_8812
      ↓
Causa encontrada — 4 minutos desde la alerta

Las cuatro etapas y los tres relojes

Un incidente se detecta, se reconoce, se mitiga y se resuelve — y cada tramo tiene su métrica. MTTD (detectar): del primer error al alerta. MTTA (reconocer): del alerta a que alguien lo tome. MTTR (restaurar): del inicio al servicio normal. Si no mides los tres por separado, no sabes cuál mejorar: un MTTD de 20 minutos no se arregla con más gente de guardia, se arregla con mejores alertas.

Severidad: defínela antes de necesitarla

SEV1  Servicio caído o pérdida de datos.
      Todos los usuarios. Se despierta gente. Comms de inmediato.
SEV2  Degradación seria: SLO en riesgo, funcionalidad
      importante rota. Se atiende ya, en horario o fuera.
SEV3  Impacto acotado o con workaround.
      Ticket, se resuelve en horario laboral.

El criterio es siempre impacto en el usuario, nunca cuánto código hay que tocar. Un typo en el CSS del checkout que impide comprar es SEV1; un worker de reportes caído puede ser SEV3.

Anatomía de un runbook que sirve

Un runbook es para alguien que abre el celular a las 3 AM, no para el que escribió el sistema. Cinco secciones:

1. Síntoma — qué alerta disparó y qué está viendo el usuario.
2. Verificación — las queries exactas, copiables, con links al dashboard.
3. Mitigación — comandos concretos, en orden, del menos al más destructivo.
4. Escalación — a quién llamar y a partir de qué minuto.
5. Post-incidente — qué guardar antes de que se pierda: trace_ids, capturas, ventana horaria.

Post-mortem sin culpables, en serio

"Blameless" no es un gesto amable: es lo único que hace que la gente cuente lo que realmente pasó. Si el que apretó el botón sabe que va a quedar señalado, la próxima vez el timeline va a tener huecos justo donde estaba la información útil. La pregunta correcta nunca es quién se equivocó, sino qué hizo que esa acción pareciera razonable en ese momento.

Las seis secciones

1. Resumen        — 3 líneas: qué pasó, a quién afectó, cuánto duró.
2. Impacto        — usuarios, requests fallidas, presupuesto de error
                    consumido, dinero si aplica.
3. Timeline       — con horas exactas: primer error, alerta, ack,
                    mitigación, resolución. De ahí salen MTTD/MTTA/MTTR.
4. Causa          — la técnica y también la contribuyente (por qué el
                    sistema permitió que pasara).
5. Qué funcionó   — sí, esta sección va. La alerta que disparó bien y
                    el runbook que sirvió también son resultados.
6. Action items   — cada uno con dueño, fecha y ticket. Sin dueño no
                    es un action item, es un comentario.

GameDay: romper a propósito, en horario

Un GameDay es un incidente planificado: eliges un día, avisas al equipo, inyectas fallas reales y verificas si tu observabilidad las detecta. Es la única forma honesta de saber si el stack sirve — porque el día del incidente real no quieres descubrir que el alerta nunca estuvo bien configurado.

Hipótesis:  "Si el proveedor de pagos empieza a devolver 500,
             el alerta fast burn dispara en menos de 5 minutos y
             el runbook nos lleva a la causa en menos de 10."
Inyección:  proxy que devuelve 500 en el 30% de las llamadas
Observación: ¿disparó? ¿en cuánto? ¿el runbook alcanzó?
Aprendizaje: qué faltó — un span, un panel, un paso del runbook

Tres fallas para empezar

Dependencia externa lenta o rota, saturación de recursos (CPU al límite o pool de conexiones agotado), y pérdida de un contenedor (matarlo y ver si el sistema se recupera solo). Con esas tres ya vas a encontrar al menos un hueco en tu instrumentación.