P5 · Cuando algo falla

Cubre: semanas 14 a 16 · En equipo

Un viernes en la noche, con una venta abierta, el procesador de pagos empieza a responder en 5 segundos en vez de 80 milisegundos. No se cayó: está lento, que es peor. Su P4 no pierde ninguna orden, pero cada comprador mira una pantalla en blanco durante segundos, las órdenes en curso se acumulan con sus asientos tomados, y el servicio de pagos le insiste sin pausa a una pasarela que no puede con lo que ya tiene. Nadie del equipo se entera hasta que alguien reclama, y cuando quieren mirar qué pasó, los logs son frases sueltas de dos procesos distintos.

Esta entrega es la última: el sistema aprende a fallar bien, a decir qué le pasa y a vigilar solo que su arquitectura siga siendo la que decidieron.

El punto de partida es su propio P4.

1. El requisito que llega

La pasarela lenta o caída no tumba la venta

  • Atributo de calidad: disponibilidad
  • Fuente del estímulo: la pasarela de pagos
  • Estímulo: durante 25 segundos, cada respuesta de la pasarela tarda 5 segundos más; en otra corrida, la pasarela no acepta conexiones
  • Artefacto: la compra (POST /orders), el servicio de pagos, el catálogo
  • Entorno: una venta en curso, con 30 compradores que envían una orden por segundo y 20 visitantes; la falla ya empezó cuando llegan
  • Respuesta: el catálogo sigue igual; la compra responde rápido: vende si puede, deja la orden en curso o dice de entrada que ahora no puede cobrar; el sistema deja de insistirle a la pasarela; cuando la pasarela vuelve, el sistema vuelve a vender solo y las órdenes en curso se completan
  • Medida de la respuesta: pasados los primeros 10 segundos de la falla, p95 de POST /orders menor que 1 s, y nunca ninguno de más de 7 s; p95 de GET /events y de GET /events/:id menor que 300 ms; 0 respuestas que no sean del negocio; mientras dura la falla, a la pasarela le llegan a lo más 15 pedidos de cobro por cada 100 intentos de compra; ninguna sesión de PostgreSQL pasa 1 s o más idle in transaction; terminada la falla, una compra vuelve a responder 201 en menos de 30 s y toda orden pending termina en menos de 30 s más, con exactamente un cobro aprobado ejecutado por cada orden pagada

Los primeros 10 segundos son para que el sistema descubra la falla: nadie puede saber que la pasarela está lenta antes de haberla esperado. Lo que el escenario mide es qué hace el sistema una vez que lo sabe.

Hay dos requisitos más, que no tienen una falla detrás:

  • Poder mirar. Un log por pedido, en un formato que una máquina pueda leer, con un identificador que siga al pedido de un proceso al otro; las cuentas de la compra en un endpoint de métricas; y un SLO escrito, con su error budget.
  • Que la arquitectura no se deshaga sola. Todo lo que decidieron en seis entregas (los límites entre módulos, de quién es cada tabla, que la compra aguanta una caída) hoy lo comprueba check, que es del curso. Desde ahora lo comprueba make fitness, que es suyo.

2. Lo que está fijo

La pasarela detrás de un proxy

  • El servicio de pagos llega a la pasarela por GATEWAY_URL, como en P4. Las pruebas ponen ahí la dirección de Toxiproxy (puerto 4101), que reenvía a la pasarela de las pruebas, y con él agregan la demora y cortan el paso.
  • Con la pasarela 5 segundos más lenta, el pedido de cobro llega a la pasarela y se aprueba; lo que tarda es la respuesta. Un cobro que su sistema dejó de esperar puede estar aprobado. La clave de idempotencia de P4 es lo que permite volver a preguntar.

La compra durante una falla

  • A las respuestas de P4 se suma una: 503 con el código PAYMENTS_UNAVAILABLE, para rechazar una compra de entrada cuando el sistema ya sabe que no puede cobrar. No crea la orden ni toma asientos. Usarla o no es decisión del equipo: lo que el escenario pide es que la respuesta, sea 202 o 503, llegue rápido.
  • Todo lo de P4 sigue valiendo: una orden pending no se pierde ni se cancela porque la pasarela falle, se completa cuando la pasarela vuelve, y no se cobra dos veces. Una compra aislada con el servicio de pagos detenido sigue respondiendo 202 (las pruebas de P4 se vuelven a correr).
  • Las pruebas de P2 siguen pidiendo 201 con la pasarela demorando 2 segundos. Su timeout hacia la pasarela tiene que dejar pasar eso.

Los logs

  • Con TINKUY_LOG distinto de off, cada proceso escribe sus logs en la salida estándar, una línea por evento, cada línea un objeto JSON.

  • El monolito escribe exactamente una línea por pedido HTTP con, al menos, estos campos:

    Campo Contenido
    requestId El identificador del pedido (texto)
    route El método y el patrón de la ruta: GET /events, GET /events/:id, GET /events/:id/seats, POST /orders, GET /orders/:id, GET /reports/sales, GET /health, GET /metrics
    status El código de estado de la respuesta (número)
    durationMs Lo que tardó en responder, en milisegundos (número)

    Puede escribir otras líneas (un mensaje publicado, un error), con los campos que quiera; solo la línea del pedido lleva route y status juntos.

  • El requestId es el valor de la cabecera X-Request-Id del pedido; si no viene, el servidor genera uno. La respuesta lo devuelve siempre en la cabecera X-Request-Id.

  • El requestId de una compra viaja en el mensaje hasta el servicio de pagos, que escribe al menos una línea JSON con ese mismo requestId cuando procesa su cobro.

Las métricas

  • GET /metrics del monolito responde 200 con texto en el formato de exposición de Prometheus. Tiene, al menos, un contador de pedidos de compra por resultado:

    tinkuy_purchase_requests_total{result="paid"} 1402
    tinkuy_purchase_requests_total{result="conflict"} 4565
    result Respuesta de POST /orders
    paid 201
    pending 202
    declined 402
    conflict 409
    invalid 400, 404, 413 o 422
    unavailable 503 con PAYMENTS_UNAVAILABLE
    error cualquier otra

    Cuenta desde que arrancó el proceso. Un resultado que no ha ocurrido puede faltar o valer 0.

make fitness

  • Corre las fitness functions del equipo y termina con código 0 solo si todas pasan. Como mínimo: las reglas de dependencia, la comprobación de ownership de los datos, una prueba de carga corta con k6 con al menos un umbral, y una prueba de falla (algo se cae y el sistema responde como su escenario dice).
  • Termina en menos de 3 minutos.
  • Se levanta y se apaga solo: no necesita nada corriendo antes, no deja nada corriendo después, y no usa los puertos 3100, 3101, 4100 ni 4101.
  • Falla cuando la arquitectura se rompe. Las pruebas lo comprueban rompiéndola.

Lo fijo de las entregas anteriores sigue fijo.

3. Lo que deciden

Al menos tres ADR nuevos, cada uno con al menos dos alternativas comparadas y con los números que respaldan cada límite:

  1. Cuánto se espera a la pasarela y cuántas veces se le insiste: timeouts y retries, y por qué esos valores.
  2. Qué hace el sistema cuando sabe que la pasarela está mal: cómo se entera, qué deja de hacer, qué le responde a quien compra y cómo se entera de que ya pasó.
  3. Qué se observa y qué se promete: los logs, las métricas, los SLI y los SLO.

4. Lo que comprueban las pruebas públicas

check corre las pruebas de P0 a P4 y después p5.public.test.ts, que tiene cuatro grupos.

Documentos

  1. docs/adr/ tiene al menos quince ADR en total, con sus secciones.
  2. docs/measurements/p5.md tiene Máquina, Antes y Después y al menos un bloque de código.
  3. docs/scenarios.md pasa el revisor y tiene al menos ocho escenarios.
  4. Los tres diagramas C4 siguen pasando el revisor.
  5. docs/slo.md tiene las secciones SLI, SLO y Error budget, al menos un objetivo escrito como porcentaje, y nombra la métrica tinkuy_purchase_requests_total.
  6. docs/architecture.md tiene las diez secciones de arc42 de su template y nombra el archivo de cada ADR de docs/adr/.

Observabilidad. El sistema se levanta con los logs prendidos.

  1. Cinco pedidos, cada uno con su X-Request-Id: la lista, un detalle, una orden que no existe (404), una compra (201) y una compra inválida (422). Cada respuesta devuelve su X-Request-Id, y un pedido sin la cabecera recibe uno generado. En la salida de make start hay exactamente una línea JSON por pedido con ese requestId, su route, su status y un durationMs numérico. En la salida de make payments hay una línea JSON con el requestId de la compra.
  2. GET /metrics antes y después de dos compras (201), un rechazo (402), un asiento tomado (409) y dos pedidos inválidos (422): tinkuy_purchase_requests_total creció exactamente 2 en paid, 1 en declined, 1 en conflict y 2 en invalid, y nada en los demás.

Fitness functions. Sin nada del sistema corriendo.

  1. make fitness termina con código 0 en menos de 3 minutos, y su salida muestra que corrieron las reglas de dependencia y una prueba con k6.
  2. Sobre una copia de su repositorio a la que las pruebas le agregan un archivo, src/http/atajo.ts, que importa src/db.ts: make fitness termina con un código distinto de 0.

La pasarela falla. El sistema se levanta con Toxiproxy entre el servicio de pagos y la pasarela. Dos veces, primero con la pasarela 5 segundos más lenta (latency) y después inalcanzable (el proxy apagado):

  1. Antes de la falla, una compra responde 201. Se pone la falla y corre gateway-fault.js con k6: 30 compradores y 20 visitantes durante 25 segundos.

    Métrica Umbral
    http_req_duration{phase:steady,name:POST /orders} (las compras de los últimos 15 segundos) p(95)<1000
    http_req_duration{name:POST /orders} (todas) max<7000
    http_req_duration{name:GET /events} y {name:GET /events/:id} p(95)<300
    unexpected_responses (una compra que no es 201, 202, 402, 409 ni 503 con PAYMENTS_UNAVAILABLE, o un GET que no es 200) rate==0

    El primer umbral y los del catálogo se multiplican por el factor de calibración. Además: hubo al menos 100 intentos de compra (todo pedido que no terminó en 409 o 422); los pedidos de cobro que recibió la pasarela durante la carga son a lo más 15 % de esos intentos; y, mirando pg_stat_activity de las dos bases de datos cada 200 ms, ninguna sesión llegó a 1 000 ms idle in transaction.

  2. Se quita la falla. Las pruebas piden una compra cada medio segundo: alguna tiene que responder 201 antes de 30 segundos. Después, ninguna orden queda pending pasados 30 segundos más.

  3. Con el sistema en reposo: las invariantes de P2, exactamente un cobro aprobado ejecutado por cada orden pagada durante y después de la falla, y ninguno por una orden que no esté pagada.

Las pruebas no buscan un circuit breaker en su código. Cuentan lo que le llega a la pasarela mientras está mal, y miden cuánto tarda la compra en responder y cuánto tarda el sistema en volver.

5. Cómo se comprueba

make -f /work/projects/p5-fallas/Makefile check

Corre make typecheck, make deps y make test de su repositorio y después las pruebas públicas de P0 a P5. Es la corrida más larga del proyecto: unos seis minutos. Para trabajar solo con las de esta entrega:

node --test --test-concurrency=1 /work/projects/p5-fallas/p5.public.test.ts

make -f /work/projects/p5-fallas/Makefile calibrate mide la máquina; aquí afecta a los umbrales de latencia del punto 11.

Sobre un P4 terminado y nada más, las pruebas de P5 terminan así (en la laptop de referencia):

P5 · documentos
  ✖ hay al menos quince ADR (los de P0 a P4, y tres de esta entrega), con sus secciones
      docs/adr/ tiene 12 ADR con nombre NNNN-titulo.md y esta entrega pide al menos 15 en total
  ...
  ✖ docs/slo.md define los SLI y los SLO de la compra y hace la cuenta de su error budget
      docs/slo.md: no existe
  ✖ docs/architecture.md tiene las secciones de arc42 y enlaza cada ADR
      docs/architecture.md: no existe

P5 · observabilidad
  ✖ cada pedido deja una línea de log en JSON con requestId, route, status y durationMs, y el requestId llega al servicio de pagos
      GET /events: la respuesta devuelve la cabecera X-Request-Id que llegó en el pedido
      + actual - expected

      + null
      - 'check-1794821840660-lista'

  ✖ GET /metrics cuenta los pedidos de compra por resultado (tinkuy_purchase_requests_total)
      GET /metrics

      404 !== 200

P5 · fitness functions
  ✖ make fitness corre las reglas de dependencia y una prueba de carga, y pasa en menos de 3 minutos
      el Makefile no tiene el objetivo fitness:
      ...
  ✖ make fitness falla cuando la capa HTTP importa la base de datos
      el Makefile no tiene el objetivo fitness

      2 !== 0


P5 · la pasarela falla
  ✖ la pasarela 5 s más lenta durante 25 s: la compra responde rápido, el catálogo no se entera y el sistema se recupera solo (30.1 s)
      http_req_duration{phase:steady,name:POST /orders}: se pedía p(95)<1000 y salió 5016.428
      con la pasarela fallando hubo 150 intentos de compra y a la pasarela le llegaron 150 pedidos de cobro: se pide que sean a lo más 15 % (el sistema tiene que dejar de insistirle a una pasarela que no responde)
      · factor de calibración 1.0 (la variable TINKUY_FACTOR): con la falla conocida, p95 de POST /orders < 1000 ms; p95 del catálogo < 300 ms
      · pasarela lenta: 150 intentos de compra (0 con 201, 150 con 202, 0 con 503 PAYMENTS_UNAVAILABLE); a la pasarela le llegaron 150 pedidos de cobro
      · p95 de POST /orders con la falla conocida 5016 ms; p95 de GET /events 2 ms, de GET /events/:id 3 ms; la sesión que más tiempo pasó "idle in transaction": 0 ms
  ✖ la pasarela inalcanzable durante 25 s: lo mismo (29.7 s)
      http_req_duration{phase:steady,name:POST /orders}: se pedía p(95)<1000 y salió 5015.134
      · factor de calibración 1.0 (la variable TINKUY_FACTOR): con la falla conocida, p95 de POST /orders < 1000 ms; p95 del catálogo < 300 ms
      · pasarela caída: 150 intentos de compra (0 con 201, 150 con 202, 0 con 503 PAYMENTS_UNAVAILABLE); a la pasarela le llegaron 0 pedidos de cobro
      · p95 de POST /orders con la falla conocida 5015 ms; p95 de GET /events 4 ms, de GET /events/:id 4 ms; la sesión que más tiempo pasó "idle in transaction": 0 ms

12 pruebas: 1 pasan, 11 fallan

Lean las dos últimas con cuidado, porque dicen qué tiene ya su P4 y qué le falta. El catálogo no se entera de la falla (2 a 4 ms) y no hay transacciones abiertas: eso lo resolvieron en P2, cuando sacaron la pasarela de la transacción. Ninguna orden se pierde: eso es P4. Lo que falta es lo otro: cada comprador espera 5 segundos para recibir un 202, en 25 segundos solo caben 150 intentos, y con la pasarela lenta cada uno le manda un cobro más a una pasarela que ya no da abasto. Con la pasarela apagada no le llega nada (no hay a quién), y por eso ahí la medida de los pedidos de cobro no dice nada: la de la latencia sí.

6. Documentos

Archivo Contenido
docs/adr/0013-… a 0015-… (o los números que sigan) Las decisiones de la sección 3
docs/scenarios.md El escenario de esta entrega, con las medidas que el equipo se compromete a cumplir
docs/measurements/p5.md ## Máquina, ## Antes y ## Después (archivo de partida: templates/measurements.md)
docs/slo.md Los SLI y los SLO de Tinkuy y la cuenta de su error budget (archivo de partida: templates/slo.md)
docs/architecture.md El documento de arquitectura final, con las secciones de arc42 que aplican y un enlace a cada ADR (archivo de partida: templates/architecture.md). Es lo que se recorre en la defensa de la semana 16
docs/c4/ Al día

Sobre el error budget: si un SLO es una fracción objetivo de eventos buenos, el presupuesto es lo que queda,

error budget=1−SLO\text{error budget} = 1 - \text{SLO}

y la cuenta que se pide es llevarlo a algo que se pueda gastar: con un SLO de 99,5 %99{,}5\,\% y 200 000 compras válidas en la ventana, 0,005⋅200 000=1 0000{,}005 \cdot 200\,000 = 1\,000 compras pueden salir mal. Cuántas gasta la falla de su escenario lo dicen sus mediciones.

7. Pistas

  • Midan la falla primero. Con su P4, Toxiproxy y la pasarela de las pruebas:

    svc start toxiproxy
    toxiproxy-cli create --listen 127.0.0.1:4001 --upstream 127.0.0.1:4000 pasarela
    GATEWAY_URL=http://127.0.0.1:4001 make payments
    toxiproxy-cli toxic add --type latency --attribute latency=5000 --toxicName lenta pasarela
    k6 run /work/projects/p5-fallas/gateway-fault.js
    toxiproxy-cli toxic remove --toxicName lenta pasarela
    toxiproxy-cli toggle pasarela        # la apaga; otra vez, la prende

    Guarden el resumen y curl -s localhost:4000/_charges | jq '.charges | length': es su sección Antes.

  • Las tácticas son las de la semana 14: timeout, retry con backoff y jitter, circuit breaker, bulkhead y load shedding, y su laboratorio es este mismo problema con otra pasarela. Ninguna se pone “por si acaso”: cada una responde a una línea de su medición.

  • Un timeout es una decisión sobre un cobro que quizá ocurrió. Antes de elegir el número, respondan qué hace el sistema con la orden cuando el timeout vence, y qué pasa si la respuesta de la pasarela era “aprobado”.

  • El sistema tiene dos procesos y la falla está detrás de uno solo. El servicio de pagos es el que ve a la pasarela; el monolito es el que le responde a quien compra. Pregúntense cómo se entera el segundo de lo que sabe el primero, o cómo lo deduce por su cuenta.

  • Cómo se vuelve. Un sistema que deja de insistir tiene que volver a probar en algún momento. Quién prueba, cada cuánto y con qué pedido decide cuánto tarda la recuperación: es la mitad del segundo ADR.

  • Los logs. Una función que recibe un objeto y escribe una línea es suficiente. Lo difícil no es el formato: es que el requestId llegue a cada lugar donde se escribe, también al otro lado de NATS. La semana 14 también cubre logs, métricas y SLO.

  • Fitness functions: la semana 15, sus apuntes y code/week-15/fitness/, cuyo run.sh corre cinco comprobaciones sobre otro sistema y resume cuáles se cumplen. Si make fitness levanta su sistema, que lo haga en puertos y bases de datos que no sean los de trabajo.

  • El documento de arquitectura no se escribe desde cero: casi todo ya está en sus ADR, diagramas y escenarios. Lo que falta es el hilo: por qué el sistema terminó siendo este. arc42 está en la guía de la semana 7.

8. Fuera de alcance

  • Otras fallas: el principal de PostgreSQL caído, la red entre el monolito y NATS, un disco lleno. El escenario es la pasarela.
  • Alertas y tableros. Se pide el dato (logs, métricas, SLO), no quién lo mira.
  • Trazas distribuidas con un estándar (traceparent, OpenTelemetry). El requestId propagado es la versión mínima de la misma idea.
  • Cancelar una orden pending que lleva mucho tiempo esperando. Vale decir en el ADR cuándo lo harían y qué tendrían que saber de la pasarela para hacerlo sin riesgo.
  • Varias instancias de cada proceso. Su circuit breaker vive en la memoria de un proceso: digan qué cambiaría con dos.