La release 15 ya atiende el 100 % del tráfico y contesta bien, pero no deja rastro: mañana nadie podría decir qué contestó, con qué versión ni qué tan rápido. ¿Qué tiene que quedar escrito de cada request (su nombre, una línea de log, sus sumas en las métricas y, a veces, un exemplar), cómo llega cada rastro a donde alguien lo puede leer sin frenar nunca la respuesta, y quién ve lo que pasa antes de que la request llegue al gateway?
Necesitas: Docker Desktop con al menos 4 GiB libres · Python 3.11 o más nuevo, con el venv del kit: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt y source .venv/bin/activate · git e Internet la primera vez (las imágenes de RustFS, Prometheus y Fluent Bit, y la del nodo) · Los puertos 8950–8957 y 9950–9954 libres en tu Mac
Listo cuando: python verificar.py mundo en verde: todo arriba, y una foto por el ALB contesta 200 con resnet50-2026-11-01. Ya puedes practicar.
¿Algo falló al levantar? ↓
Ojo: La primera vez, crear.py baja las imágenes y construye la del nodo (≈ 2 min). Para docker compose en esta carpeta, primero export DOCKER_CONFIG=$PWD/.docker (lo crea crear.py, sin el llavero de macOS). Si un puerto del 8950 al 8957 o del 9950 al 9954 está ocupado, apaga la otra estación que lo usa. python mundo/nodo.py parar y docker compose stop liberan tu Mac; crear.py lo regresa todo.
python mundo/crear.py · Se puede correr otra vez: deja el mundo como al principio, salvo tus archivos.
SalidaSalida real · python mundo/crear.py
== Docker, el venv y git
✓ la carpeta del kit es un repositorio de git (main)
== compose: S3, Prometheus, los dos nodos del gateway y su Fluent Bit (la primera vez construye la imagen del nodo, ≈ 1 min)
✓ s3 :9950 · prometheus :9952 · fluent-bit-a :9953 · fluent-bit-b :9954 · imagen dojo-c01-nodo:11
== El log de ayer, ya subido
✓ log de ayer (2026-11-18) en s3://ml-datos/logs/crudo/2026/11/18/: 11,849 requests en 578 archivos (2 subidos dos veces); los de las 23:55 en adelante, en logs/crudo/2026/11/19/00/
== Los procesos: Triton, los pods del gateway, el ALB y el vigía
✓ triton listo en 0.4 s
✓ gateway-6f7b9c4d58-xa7k2 (nodo-a) listo en 0.6 s
✓ gateway-6f7b9c4d58-qm4t8 (nodo-b) listo en 0.6 s
✓ alb listo en 0.4 s
✓ vigia listo en 0.4 s
✓ trafico listo en 1.6 s
✓ el mundo está arriba en 14 s. La entrada es el ALB: http://localhost:8950
Sigue con: python verificar.py mundo
SalidaSalida real · python verificar.py mundo
✓ mundo S3, Prometheus, 2 nodos con su pod y su Fluent Bit, Triton, ALB y vigía arriba · una foto por el ALB: 200 (resnet50-2026-11-01)
1/1 en verde
python mundo/nodo.py estado · Cada pod escribe su stdout en el disco de su nodo: esa ruta de /var/log/pods/… es la que va a leer Fluent Bit.
Cada ronda se trabaja en una sesión de Claude Code abierta en la carpeta del kit. Copia el prompt de la ronda y pégalo; el enlace de cada tarjeta te lleva a su sección en esta página. El CLAUDE.md del kit pone las reglas de fondo.
ConstruirRomperCon ayuda
1 · Construir con ayudaCon el Guiado de abajo: construyen juntos los pasos 1 a 9. Empieza aquí.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 11 de C01, «La request en vivo», ronda **Construir con ayuda**.
Lee primero `CLAUDE.md` y `GUION.md` de esta carpeta. Vamos a darle rastro a la release 15 siguiendo los pasos 0 a 9 de `GUION.md`: el `request_id` y la línea de log (`gateway/app/rastro.py`); los tres relojes; las métricas del contrato; que Prometheus lea cada pod una sola vez (`observabilidad/prometheus.yml`, con la trampa de leer por los Services); PromQL, las recording rules y las alertas (`observabilidad/reglas.yml`); los exemplars; el camino del log a S3 con Fluent Bit (`observabilidad/fluent-bit.conf`, con el simulacro de S3 caído); el job diario a Parquet (`diario/a_parquet.py`); y lo que el gateway no ve, con Triton caído.
Entre el paso 0 y el 1, `GUION.md` trae los «Precálculos»: las cuentas de servilleta de la estación (volumen y costo del log, los tres relojes, las series por pod, las muestras de Prometheus, la tasa con un reinicio, los exemplars al 1 %, el aguante del buffer, los repetidos y lo que el ALB contesta solo). Pídeme que haga cada cuenta yo primero, corrígeme y después dime qué comando o qué paso la confirma.
En cada paso:
1. Dime el objetivo en una línea y explícame los conceptos que usa desde cero, rápido, con una analogía y con el término en inglés. Doy por sabido Python, PyTorch, HTTP y lo de las estaciones 6 a 10 (el gateway, pods, Services, el canary), no Prometheus, PromQL, Fluent Bit ni Parquet.
2. Escribe conmigo el archivo del paso, por bloques y con el porqué de cada línea. No me pegues el archivo entero de golpe. El contrato de arriba de cada archivo manda.
3. Dime qué comando correr y espera a que te pegue la salida. Los que cambian algo (`mundo/recargar.py`, `mundo/nodo.py reiniciar|matar|parar|arrancar`, `docker compose stop|start`, `mundo/carga.py`, `diario/a_parquet.py`, `git commit`) no los corras tú sin decírmelo antes. Cuando haga falta tráfico, recuérdame la carga en otra terminal, y que Prometheus necesita ≈ 1 min de datos para que un `rate(…[1m])` tenga sentido.
4. Corre `python verificar.py <checks del paso>` y explícame el resultado. Mira conmigo, en este orden: http://localhost:9952/targets y /alerts, `curl -s localhost:8951/metrics | grep classifier_`, `python mundo/nodo.py logs a`, `python mundo/buscar.py <request_id>`, `docker compose logs fluent-bit-a`, `curl -s localhost:9953/api/v2/metrics/prometheus`, `curl -s localhost:8957/metrics` y `logs/alb.log`.
5. Cuando algo del dojo sea distinto de C01 (los nodos como contenedores de Docker, `file_sd_configs` en lugar del PodMonitor, RustFS en lugar de S3, el ALB del dojo en lugar de CloudWatch, las lecturas cada 5 s y las ventanas de 1 min, los exemplars sin trazas completas, los nombres `code` y `classifier_request_seconds`), dímelo en una línea.
6. Anota el paso en la bitácora (sección «Bitácora» de `CLAUDE.md`) con lo que hice, lo que medí y lo que sigue.
Después de cada cambio, recárgalo (`python mundo/recargar.py gateway|prometheus|fluent-bit`): un archivo bien escrito que no se recargó no cuenta. Si algo falla, no lo arregles en silencio: muéstrame el error, dime tu hipótesis y arreglémoslo juntos. Al final, corre `python verificar.py` completo y cierra la ronda en `taller/progreso.json`.
3 · Romper con ayudaUna falla real; Claude te guía con preguntas.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 11 de C01, «La request en vivo», ronda **Romper con ayuda**.
Lee `CLAUDE.md`. Todo pasa `python verificar.py` (la release 15 con su rastro completo). Ahora:
1. Corre `python romper.py --mostrar` (o `--mostrar --falla <id>` si te digo cuál). El script mete la falla en el mundo, la configuración o la infraestructura, nunca en mis archivos, y te dice cuál fue. **A mí no me la digas.** Solo cuéntame la «historia»: qué notó alguien en el equipo. Algunas fallas tardan ≈ 1 min en verse en Prometheus (la ventana de las tasas).
2. Corre `python verificar.py` y pregúntame qué veo.
3. Guíame con preguntas en este orden: síntoma → hipótesis (pídeme al menos dos) → el comando que confirma o descarta cada una (http://localhost:9952/targets y /alerts, `curl -s localhost:8951/metrics`, `nodo/descubrimiento/pods.json`, `docker compose ps` y `docker compose logs fluent-bit-a`, `curl -s localhost:9953/api/v2/metrics/prometheus`, `curl -s localhost:8957/metrics` y `logs/alb.log`, `python mundo/nodo.py estado`, `git log -p mundo/plataforma.yaml gateway/app/main.py`) → el arreglo. Si me atoro más de dos veces en el mismo punto, dame una pista concreta y anótala.
4. Cuando lo arregle, corre `python romper.py --verificar`. Ahí sí explícame qué era, el concepto detrás y cómo se vería en C01 de verdad (kube-prometheus-stack con su PodMonitor, el DaemonSet de Fluent Bit, Amazon S3, el ALB de AWS con sus métricas en CloudWatch, la persona de guardia).
5. Anota en la bitácora la falla, cuánto tardé, cuántas pistas usé y qué aprendí.
Repetimos con otra falla hasta que te diga que paremos. Para volver al estado sano entre fallas: `python romper.py --restaurar`. Antes de cambiar de ronda, haz commit de `taller/progreso.json` y `BITACORA.md`.
2 · Construir soloRehaces todo desde el esqueleto, solo con los objetivos de Solo.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 11 de C01, «La request en vivo», ronda **Construir solo**.
Lee `CLAUDE.md`. **No leas `GUION.md`** ni `kits/…-solucion`, y no me des código: esta ronda la escribo yo desde el esqueleto, con `OBJETIVOS.md` y los contratos de arriba de cada archivo mío (`gateway/app/rastro.py`, `observabilidad/prometheus.yml`, `observabilidad/reglas.yml`, `observabilidad/fluent-bit.conf`, `diario/a_parquet.py`) como única guía.
Tu papel:
- Primero confirma que estoy en una carpeta con el kit recién descomprimido, con su venv activo, y que el mundo está arriba: `python mundo/crear.py` y `python verificar.py mundo`. El mundo es uno solo (los mismos puertos y el mismo proyecto de compose): si el de Construir con ayuda sigue prendido en otra carpeta, dime que lo apague allá (`python mundo/nodo.py parar` y `docker compose down -v`).
- Cuando te lo pida, corre `python verificar.py` (o un check suelto) y dime qué objetivo pasa y cuál no, con el mensaje exacto. También puedes correr lo que solo lee (`python mundo/nodo.py estado|logs`, `python mundo/buscar.py`, `python mundo/relojes.py`, `curl` a `/metrics` o a la API de Prometheus, `docker compose logs|ps`, `git log`) y pegarme la salida tal cual.
- Si te pregunto algo, contéstame con una pregunta que me acerque o con el concepto, nunca con el código, la configuración ni el arreglo. Si te digo «me rindo en este objetivo», ahí sí explícamelo, y anótalo en la bitácora como pista usada.
- Anota en la bitácora cada objetivo cuando pase: cuánto tardé y qué me costó.
Al final, con `python verificar.py` en verde, cierra la ronda en `taller/progreso.json`.
4 · Romper soloUna falla escondida; nadie te da pistas.Ver el prompt ↓
prompt
Estoy en el Dojo de entrenamiento ML engineer's, en la estación 11 de C01, «La request en vivo», ronda **Romper solo**.
Lee `CLAUDE.md`. Todo pasa `python verificar.py`.
1. Corre `python romper.py` **sin** `--mostrar`. El script elige una falla al azar y la esconde; tú tampoco sabes cuál es, así que no intentes averiguarla leyendo `romper.py`, `.taller/`, `git log` ni lo que corre.
2. Dime solo la «historia» que imprime y la hora de inicio. Desde ahí trabajo yo solo: no me des pistas ni hipótesis. Si te pido correr un comando, córrelo y pégame la salida tal cual, sin interpretarla.
3. Cuando te diga «listo», corre `python romper.py --verificar`. Dime si quedó arreglado, cuál era la falla y cuánto tardé. Si no quedó, dime solo que no y sigo.
4. Si te digo «me rindo», corre `python romper.py --revelar` y explícame la falla completa.
5. Anota en la bitácora la falla, el tiempo, si me rendí y qué haría distinto.
El código que ves es el de la solución de referencia, y cada salida es la que salió al correr el kit en una carpeta limpia.
Precálculos. Antes de escribir, las cuentas de servilleta: cuánto pesa el log y cuánto cuesta, cuánto mide la misma request en cada reloj, cuántas series deja el gateway (y cuántas con un id por request), cuántas muestras guarda Prometheus, qué tasa sale con un reinicio, cuántas lentas tienen exemplar, cuánto aguanta el buffer si S3 se cae, cuántas filas sobran sin quitar repetidos y qué pasa cuando contesta el ALB. Cada cuenta va en las dos escalas: C01 y el dojo. Cada uno está dentro del paso donde se usa.
1El request_id y la línea de logCada request con un nombre (su request_id) que vuelve en la respuesta, y una sola línea de JSON compacto en stdout, sin hora, que el runtime guarda en el disco del nodo.
Escribe en gateway/app/rastro.py la función del principio y la línea del final. request_id() respeta el X-Request-ID del caller si es sano (de 8 a 64 caracteres de letras, números, «-», «_», «.» o «:») y, si no, inventa un UUID versión 4: así el backend y el gateway llaman igual a la misma request, y un id con espacios o de 80 caracteres no se cuela al log. anotar() pone el status y ms.total en el evento y lo escribe como una línea de JSON compacto (separators=(',', ':')) en stdout. No lleva hora: la pone el runtime del nodo al recibirla. main.py llama a anotar() en un finally, así que también los 4xx dejan su línea. Las métricas todavía no: llegan en el paso 3. Recarga los pods con mundo/recargar.py gateway y sigue una request por los tres lugares donde dejó rastro.
Terminal
python mundo/carga.py --una
Una foto contada con detalle. El gateway todavía no escribe su línea: falta el tercer reloj.
Salida
→ POST http://localhost:8950/v1/classify (1,534 B, caller backend-publicaciones, X-Request-ID c8976a09-a540-425f-9a07-6b26ea3676b9)
← 200 · X-Request-ID: 5750388e-263e-4057-93e8-3247c8f429d0 · X-Amzn-Trace-Id: Root=1-6afe8e31-c5072fa18bf08e92957f7485
{"model_version":"resnet50-2026-11-01","predictions":[{"label":"abrigos","score":0.7138},{"label":"playeras","score":0.1201},{"label":"tenis","score":0.0555},{"label":"sandalias","score":0.0531},{"lab
los tres relojes de la misma request:
backend (lo que esperó, timeout 300 ms) ......... 5.7 ms
ALB, TargetResponseTime (logs/alb.log) .......... 5.0 ms
gateway: no encontré su línea en el disco de ningún nodo (¿tu rastro.py ya escribe la línea?)
Terminal
python mundo/nodo.py logs a 4
Lo único que hay en el disco del nodo: lo que el proceso escribió en stderr al arrancar.
Salida
/var/log/pods/classifier_gateway-6f7b9c4d58-xa7k2_3f1c9a2e-7b44-4d0e-9a61-5c2b8e0d7a11/gateway/0.log
2026-11-19T05:50:36.798974716Z stderr F INFO: Waiting for application startup.
2026-11-19T05:50:36.802786633Z stderr F gateway listo · gateway-6f7b9c4d58-xa7k2 en nodo-a · resnet50-2026-11-01 · Triton host.docker.internal:8955
2026-11-19T05:50:36.802824758Z stderr F INFO: Application startup complete.
2026-11-19T05:50:36.802934633Z stderr F INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
Terminal
python verificar.py
Al empezar, 2 de 12 en verde: el mundo y las series acotadas (todavía no hay series). Lo demás es tu trabajo.
Salida
✓ mundo S3, Prometheus, 2 nodos con su pod y su Fluent Bit, Triton, ALB y vigía arriba · una foto por el ALB: 200 (resnet50-2026-11-01)
✗ request-id mandé X-Request-ID 633eb4e8-c12d-4496-a30d-18741c598883 y volvió f24162ef-19cd-4d27-9614-c754c36be0ad: el id sano del caller se respeta
✗ linea-log la request 1a93237f-1060-4e8a-b642-bbe6a0e5337d dejó 0 líneas en los nodos: tiene que ser exactamente una
✗ metricas falta classifier_requests_total en /metrics (los nombres no se cambian: las alertas y el canary los buscan así)
✗ reglas-de-conteo 10 requests con 415 sumaron 0 al contador con code="415"
✗ prometheus-lee Prometheus no tiene ningún objetivo con job="gateway": falta el job en observabilidad/prometheus.yml (y curl -X POST localhost:9952/-/reload)
✗ consultas faltan recording rules en observabilidad/reglas.yml: classifier:errores_servidor:ratio_rate1m, classifier:latencia:p99_1m, classifier:requests:rate1m
✗ alertas faltan alertas en observabilidad/reglas.yml: ALB5xx, ClassifierHigh5xxRate, ClassifierP99Alto, GatewaySinLectura, LogsStale
✓ series-acotadas ≤ 1 series classifier_* por pod (tope 400) · ninguna etiqueta con un valor por request
✗ log-en-s3 el nodo a no ha subido nada en la última hora (¿tu fluent-bit.conf lee y sube? docker compose logs fluent-bit-a)
✗ parquet no hay Parquet en s3://ml-datos/logs/predicciones/dt=2026-11-18/: python diario/a_parquet.py
✗ de-punta-a-punta la respuesta trae model_version y el X-Request-ID
2/12 en verde · falta: request-id, linea-log, metricas, reglas-de-conteo, prometheus-lee, consultas, alertas, log-en-s3, parquet, de-punta-a-punta
Pythongateway/app/rastro.py
"""Lo que deja escrito cada request: su nombre, su línea de log y sus sumas en las métricas (solución de referencia).
Contrato (lo usa gateway/app/main.py, que viene dado):
- request_id(header) → str. Si el caller mandó X-Request-ID y es un id sano (8 a 64 caracteres de letras, números,
«-», «_», «.» o «:»), ese; si no (falta, vacío, muy largo, con espacios o saltos de línea), un UUID versión 4 nuevo
(str(uuid.uuid4()), 36 caracteres).
- fuente(header, fuentes) → str. La etiqueta source: el header en minúsculas y sin espacios si está en `fuentes`
(gateway.yaml: rastro.fuentes); si no, «other». Así la etiqueta tiene 4 valores, venga lo que venga.
- se_traza(request_id, fraccion) → bool. Los primeros 8 caracteres hex del sha256 del id, como número, < fraccion × 2³².
La misma request siempre cae del mismo lado.
- Rastro(registro, reglas, modelo): crea, en ese registro, las métricas con estos nombres, etiquetas y bordes (las
alertas y el análisis del canary de la estación 10 los buscan por nombre: no se cambian):
classifier_requests_total{code, source, model_version} contador
classifier_request_seconds{source, model_version} histograma (sin los 4xx), bordes MS
classifier_preprocess_seconds{model_version} histograma, bordes MS
classifier_inference_seconds{model_version} histograma, bordes MS
classifier_top1_score{model_version} histograma, bordes SCORE (uno en 0.3)
classifier_image_bytes{source} histograma, bordes BYTES
classifier_top1_label_total{label} contador, cada categoría desde el arranque
classifier_requests_in_flight gauge (rastro.en_vuelo)
y los métodos bytes(n, fuente), pre(s), inferencia(s), top1(score, label) y anotar(ev, status, fuente, t0).
- anotar: pone status y ms.total en ev, escribe ev como UNA línea de JSON compacto en stdout (sin la hora: la pone el
runtime del nodo) y suma: el contador siempre; la latencia solo si no es 4xx, con el request_id como exemplar
(trace_id) si se_traza. Nunca frena la request: escribir en stdout no espera a la red.
"""from __future__ import annotations
import hashlib
import json
import re
import sys
import time
import uuid
from prometheus_client import CollectorRegistry, Counter, Gauge, Histogram
MS = (0.005, 0.01, 0.02, 0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.5, 1.0) # bordes alrededor del SLO de 200 ms
SCORE = (0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.95, 0.99) # 0.3 = el umbral de baja confianza
BYTES = (1e3, 1e4, 1e5, 3e5, 1e6, 3e6, 1e7)
ID_SANO = re.compile(r"[A-Za-z0-9._:-]{8,64}")
defrequest_id(header: str | None) -> str:
if header and ID_SANO.fullmatch(header):
return header
returnstr(uuid.uuid4())
deffuente(header: str | None, fuentes: list[str]) -> str:
return"other"# paso 3defse_traza(rid: str, fraccion: float) -> bool:
returnFalse# paso 6classRastro:
def__init__(self, registro: CollectorRegistry, reglas: dict, modelo: dict):
self.version = modelo["model_version"]
self.fraccion = reglas["rastro"]["traza"]
self.en_vuelo = Gauge("classifier_requests_in_flight", "Requests adentro ahora", registry=registro)
defbytes(self, n: int, fuente_: str) -> None:
passdefpre(self, s: float) -> None:
passdefinferencia(self, s: float) -> None:
passdeftop1(self, score: float, label: str) -> None:
passdefanotar(self, ev: dict, status: int, fuente_: str, t0: float) -> None:
s = time.monotonic() - t0
ev["status"] = status
ev.setdefault("ms", {})["total"] = round(s * 1000, 1)
sys.stdout.write(json.dumps(ev, ensure_ascii=False, separators=(",", ":")) + "\n")
sys.stdout.flush()
# paso 3: las sumas
Así queda en este paso: fuente() devuelve «other» y se_traza() False hasta los pasos 3 y 6, y la clase todavía no crea las métricas. El flush() de cada línea: si el proceso muere, lo escrito ya está en manos del runtime.
Terminal
python mundo/recargar.py gateway
Un pod tras otro, como un rollout: el ALB drena cada uno antes de reiniciarlo.
Salida
✓ gateway-6f7b9c4d58-xa7k2 (nodo-a) listo en 0.6 s
✓ gateway-6f7b9c4d58-qm4t8 (nodo-b) listo en 0.6 s
Terminal
python mundo/carga.py --una
Ahora sí: el tercer reloj sale de la línea, y el mismo X-Request-ID volvió en la respuesta.
Salida
→ POST http://localhost:8950/v1/classify (1,534 B, caller backend-publicaciones, X-Request-ID c64fc68d-08a5-4b06-8637-35464e8723be)
← 200 · X-Request-ID: c64fc68d-08a5-4b06-8637-35464e8723be · X-Amzn-Trace-Id: Root=1-6afe8e45-c2123a59e46c43ec0dc954bb
{"model_version":"resnet50-2026-11-01","predictions":[{"label":"abrigos","score":0.7138},{"label":"playeras","score":0.1201},{"label":"tenis","score":0.0555},{"label":"sandalias","score":0.0531},{"lab
los tres relojes de la misma request:
backend (lo que esperó, timeout 300 ms) ......... 8.6 ms
ALB, TargetResponseTime (logs/alb.log) .......... 7.9 ms
gateway, ms.total (su línea de log) ............. 5.9 ms pre 0.9 · triton 4.6 · post 0.1
la línea del gateway, en nodo-a:/var/log/pods/classifier_gateway-6f7b9c4d58-xa7k2_3f1c9a2e-7b44-4d0e-9a61-5c2b8e0d7a11/gateway/0.log (la hora la puso el runtime del nodo):
{"hora": "2026-11-19T05:51:01.822575797Z", "flujo": "stdout", "request_id": "c64fc68d-08a5-4b06-8637-35464e8723be", "caller": "backend-publicaciones", "source": "mobile", "model_version": "resnet50-2026-11-01", "ms": {"pre": 0.9, "triton": 4.6, "post": 0.1, "total": 5.9}, "bytes": 1534, "sha256": "68e8dc23540b", "top5": [[4, 0.7138], [0, 0.1201], [7, 0.0555], [5, 0.0531], [2, 0.0488]], "status": 200}
Terminal
python mundo/nodo.py logs b 3
Así queda en el disco del nodo, en formato CRI: la hora del runtime, el flujo, F (línea completa) y tu texto. El 405 también deja su línea.
Salida
/var/log/pods/classifier_gateway-6f7b9c4d58-qm4t8_9d0e4b17-2c85-4f3a-b6d2-81a7e5c3f902/gateway/0.log
2026-11-19T05:51:01.813882589Z stdout F {"request_id":"8b8af464-3f7d-4832-bda8-912716bd258d","caller":"backend-publicaciones","source":"mobile","model_version":"resnet50-2026-11-01","ms":{"pre":0.8,"triton":4.3,"post":0.1,"total":5.9},"bytes":1534,"sha256":"68e8dc23540b","top5":[[4,0.7138],[0,0.1201],[7,0.0555],[5,0.0531],[2,0.0488]],"status":200}
2026-11-19T05:51:02.015494589Z stdout F {"request_id":"9cab9ffc-be6f-4e7a-91b3-0c0e582ed112","caller":"backend-publicaciones","source":"mobile","model_version":"resnet50-2026-11-01","ms":{"pre":1.0,"triton":5.1,"post":0.2,"total":6.9},"bytes":1504,"sha256":"6c50dde9f5f6","top5":[[9,0.4347],[5,0.2461],[8,0.1442],[0,0.075],[7,0.0504]],"status":200}
2026-11-19T05:51:02.160162339Z stdout F {"request_id":"f5df97de-5085-4c98-a39a-9d5a41deb462","caller":"busqueda","source":"web","model_version":"resnet50-2026-11-01","ms":{"pre":0.9,"triton":4.4,"post":0.1,"total":5.7},"bytes":1520,"sha256":"8b6f91949809","top5":[[9,0.297],[5,0.2723],[2,0.1293],[7,0.0972],[4,0.0731]],"status":200}
curl-s-i-X POST localhost:8951/v1/classify -H'Content-Type: text/plain'-H'X-Request-ID: con espacios'--data'hola'|grep-iE'^HTTP|x-request-id'
Directo al pod: un id con espacios no es sano y el gateway lo reemplaza, también en un 415.
Salida
HTTP/1.1 415 Unsupported Media Type
x-request-id: 78c8be95-13eb-4ef3-9d0f-46ff8a3e37d3
Terminal
python verificar.py request-id linea-log
Salida
✓ request-id respeta el id del caller (también en el 415), inventa un UUID v4 si falta y reemplaza los que no son sanos; el id está en el log
✓ linea-log una línea de JSON compacto en stdout (310 B), con request_id, ms y status, sin hora ni foto · nodo-a:/var/log/pods/classifier_gateway-6f7b9c4d58-xa7k2_3f1c9a2e-7b44-4d0e-9a61-5c2b8e0d7a11/gateway/0.log
2/2 en verde
Listo cuando: python verificar.py request-id linea-log: el id del caller se respeta (también en el 415), uno malo se reemplaza y cada request deja una sola línea de 310 B, sin hora ni foto.
Ojo: Con print(json.dumps(ev)) salen espacios después de cada «,» y «:»: ≈ 10 % más bytes, pagados 10 millones de veces al día en C01; verificar.py pide JSON compacto. No pongas la hora en la línea: el runtime ya la pone, y dos horas en el mismo registro (la del proceso y la del nodo) confunden a quien lo lea. Y si una request dejara dos líneas (una en el handler y otra en el finally), el join del mes contaría la foto dos veces.
Conceptos de este paso ↓
request_id de punta a puntarequest ID / correlation ID / X-Request-ID / UUID v4El nombre único de cada request: el X-Request-ID del caller si es sano, o un UUID versión 4 nuevo. Vuelve en la respuesta y va en el log y en el exemplar: es la llave para unir lo que dejó en cada lugar.Analogía, por qué importa y la trampa ↓
AnalogíaEl número de guía de un paquete: el remitente, la bodega y el repartidor anotan cosas distintas en sus propias libretas, pero con el mismo número cualquiera junta la historia completa sin saber en qué camión viajó.
Por qué importaSin él, unir el log del backend, el access log del ALB y la línea del gateway sería adivinar por la hora, y con 116 fotos por segundo eso falla. Respetar el id del caller hace que backend y gateway llamen igual a la misma request. Un UUID v4 son 122 bits al azar: dos pods inventan ids al mismo tiempo sin chocar y sin preguntarle a nadie.
TrampaCopiar cualquier X-Request-ID que llegue: uno de 80 caracteres o con un salto de línea ensucia el log (o lo parte en dos). Y ponerlo como etiqueta de una métrica: una serie nueva por request.
La línea de log: JSON Lines en stdoutstructured logging / JSON Lines / stdout / CRI log formatUna línea de JSON compacto por request, escrita en la salida estándar (stdout) y sin hora. El runtime del nodo la guarda en un archivo con su hora, en formato CRI, y rota el archivo cuando crece.Analogía, por qué importa y la trampa ↓
AnalogíaDictarle a una secretaria: dices una frase por caso y sigues con lo tuyo; ella la anota en el cuaderno con la hora del reloj de la pared y, cuando el cuaderno se llena, empieza otro y tira el más viejo.
Por qué importaEl gateway no abre archivos, no conoce S3 y no espera a nadie: escribir en stdout termina en microsegundos, así que el log nunca frena la request. Una línea por request, con request_id, caller, source, model_version, top5, ms, bytes, sha256 y status: ≈ 300 B, lo que lee el job del día siguiente. La hora la pone uno solo, el runtime, en UTC con nanosegundos: en el disco del nodo queda «<hora> stdout F <tu línea>», en 5 archivos de 10 MiB por contenedor.
TrampaPoner la hora en la línea (dos relojes en el mismo registro), escribir con espacios (≈ 10 % más bytes, pagados 10 millones de veces al día) o escribir directo a S3 desde la request: una lentitud de S3 se vuelve lentitud para el usuario.
Observabilidad: los tres rastrosobservability / metrics, logs, tracesPoder entender qué pasa adentro de un servicio mirando lo que deja escrito: métricas (sumas: ¿cuánto?), logs (una línea por request: ¿qué pasó con esta?) y trazas o exemplars (¿dónde se fue el tiempo?).Analogía, por qué importa y la trampa ↓
AnalogíaEl tablero, la bitácora y la cámara de un auto. El tablero (métricas) avisa que el motor se calienta; la bitácora (log) dice en qué viajes pasó; el video de un viaje (traza) muestra en qué subida. Video solo se graba de unos cuantos viajes: son caros.
Por qué importaCada rastro contesta una pregunta distinta y se usan en orden: la métrica avisa («el p99 subió a las 14:05»), el exemplar lleva a una request de ejemplo y el log dice cuántas se parecen y qué tienen en común. Los une el request_id. Para un modelo hay algo más: un 200 con una sugerencia mala no se ve en ninguna métrica de servicio, solo en el log, uniendo cada predicción con lo que eligió la persona. Por eso C01 guarda el log del 100 % de las requests.
TrampaCreer que con métricas basta. Las métricas no recuerdan ninguna request: con ellas sabes que algo va mal, no a quién le pasó ni qué contestó el modelo.
Precálculo ↓
1
¿Cuánto pesa el log de un día, cuánto cuesta guardarlo y en cuántos archivos llega?
bytes al día = requests al día × bytes por línea · guardado = bytes al día × días · costo = guardado × precio por GB al mes · archivos al día por nodo = segundos del día ÷ segundos entre subidas
En C0110,000,000 × 300 B = 3 GB al día; 90 días: 3 × 90 = 270 GB; a US$0.023 por GB al mes, 270 × 0.023 ≈ US$6 (sin contar la compresión de gzip, que lo baja). Con una subida cada 5 min: 86,400 ÷ 300 = 288 archivos al día por nodo≈ 3 GB al día · ≈ US$6 al mes · 288 archivos por nodo
En el dojo5 fotos/s × 86,400 s = 432,000 requests al día × 310 B ≈ 134 MB al día; con una subida por minuto, 86,400 ÷ 60 = 1,440 archivos al día por nodo. El log de ayer que dejó el mundo: 11,849 requests en 578 archivos≈ 134 MB al día · 1,440 archivos por nodo
Qué decides con esto. Que guardar el 100 % del log es barato (≈ US$6 al mes contra ≈ US$1.8k de toda la infraestructura del clasificador) y por eso no se muestrea: la falla callada de un modelo, un 200 con una sugerencia mala, solo se ve uniendo cada línea con lo que eligió la persona. Lo que no se guarda es la foto: a ≈ 200 KB serían 2 TB al día. Y como cada byte de la línea se paga 10 millones de veces al día, va en JSON compacto, sin hora y sin espacios.
Terminalterminal · compruébalo en el kit
python verificar.py request-id linea-log
verificar.py mide una línea real del disco del nodo: sus bytes, con el salto de línea.
Salida
✓ request-id respeta el id del caller (también en el 415), inventa un UUID v4 si falta y reemplaza los que no son sanos; el id está en el log
✓ linea-log una línea de JSON compacto en stdout (310 B), con request_id, ms y status, sin hora ni foto · nodo-a:/var/log/pods/classifier_gateway-6f7b9c4d58-xa7k2_3f1c9a2e-7b44-4d0e-9a61-5c2b8e0d7a11/gateway/0.log
2/2 en verde
Lo confirmas en el paso 8: el job leyó el día de ayer, 11,887 registros en 578 objetos.
2Tres relojesMedir las mismas requests con tres relojes (backend, ALB y gateway) y ver dónde se va la diferencia.
Cada reloj empieza y termina en un lugar distinto. El gateway mide desde que su código recibe la request hasta que contesta: ms.total de su línea. El ALB mide TargetResponseTime: desde que la request sale del ALB hacia el pod hasta que el pod empieza a mandar los headers de su respuesta (en su access log, target_processing_time). El backend mide todo lo que esperó, contra su timeout de 300 ms. mundo/relojes.py une los tres por request_id: sin un nombre común serían tres montones de números imposibles de casar. En este paso no escribes nada: miras con lo que dejó el paso 1.
1170 requests en 30 s (39.0/s) · códigos: 200: 1170
el backend midió (solo 200): p50 11.8 ms · p99 75.1 ms
Terminal
python mundo/relojes.py 1000
De las últimas 1000 que mandó el backend con 200, las que tienen su línea en algún nodo: el p50 y el p99 de cada reloj y de cada salto.
Salida
814 requests con los tres relojes (de las últimas 1000 del backend con 200)
reloj p50 p99
backend 11.9 86.0 ms
ALB (TargetResponseTime) 9.4 54.3 ms
gateway (ms.total) 6.0 21.7 ms
backend − ALB (red y ALB) 2.3 47.1 ms
ALB − gateway (red al pod y lo que el gateway no ve) 3.4 36.6 ms
Listo cuando: Ves que, en p50, el gateway mide 6 ms, el ALB 9.4 y el backend 11.9: cada reloj contiene al anterior.
Ojo: En el dojo cada salto pesa varios milisegundos (la red de Docker Desktop entre tu Mac y los contenedores, y un ALB escrito en Python); en C01, 1 o 2. Lo que no cambia es la regla: no compares un número de un reloj con el de otro. El SLO de C01 (p99 ≤ 200 ms) es del reloj del gateway, y ninguno de los tres incluye la subida desde el celular de quien vende hasta AWS.
Concepto de este paso ↓
Tres relojesserver-side latency / TargetResponseTime / client-side latencyLa misma request mide distinto según quién mida: el gateway (desde que su código la recibe hasta que contesta), el ALB (TargetResponseTime) y el backend (todo lo que esperó). Cada reloj contiene al anterior.Analogía, por qué importa y la trampa ↓
AnalogíaUna pizza a domicilio: la cocina cuenta desde que entra la orden hasta que sale la caja; el repartidor, desde que la recoge hasta que toca el timbre; tú, desde que colgaste el teléfono. Los tres tienen razón y ninguno es «el tiempo de la pizza».
Por qué importaEl SLO de C01 (p99 ≤ 200 ms) se mide del lado del servidor, con el reloj del gateway; el backend vive con su timeout de 300 ms. TargetResponseTime va desde que la request sale del ALB hasta que el pod empieza a mandar los headers de la respuesta. Si el backend se queja de 280 ms y el gateway dice 20, el tiempo se fue fuera del gateway: en el ALB, en la red o en el backend.
TrampaComparar un número de un reloj con el de otro como si fueran lo mismo, o unir los relojes por la hora en lugar de por request_id.
Precálculo ↓
2
¿Cuánto mide la misma request en cada reloj, y dónde se va la diferencia?
reloj del ALB = reloj del gateway + red entre el ALB y el pod · reloj del backend = reloj del ALB + lo que tarda el ALB en sus cuentas + la red entre el backend y el ALB
En C01la foto de Ana: 20 ms en el gateway; con ≈ 1 ms de red al pod, 20 + 1 ≈ 21 en el ALB; con ≈ 2 ms de entrada (TLS, revisar el token y la red del backend), 21 + 2 ≈ 23 en el backend20 · ≈ 21 · ≈ 23 ms
En el dojo814 requests con los tres relojes, en p50: gateway 6 ms, ALB 9.4 ms, backend 11.9 ms. ALB − gateway ≈ 3.4 ms (la red al pod y lo que el gateway no ve) y backend − ALB ≈ 2.3 ms6 · 9.4 · 11.9 ms (p50)
Qué decides con esto. A qué reloj se le promete qué: el SLO de C01 (p99 ≤ 200 ms) es del lado del servidor, con el reloj del gateway; el backend vive con su timeout de 300 ms; el ALB ve lo que pasa antes del gateway. En el dojo cada salto pesa ≈ 4 ms (la red de Docker Desktop y un ALB escrito en Python); en C01, 1 o 2. Ningún reloj miente: si el backend se queja y el gateway dice que va rápido, el tiempo se fue fuera del gateway.
Terminalterminal · compruébalo en el kit
python mundo/relojes.py 1000
Los tres relojes de las mismas requests, unidos por request_id.
Salida
814 requests con los tres relojes (de las últimas 1000 del backend con 200)
reloj p50 p99
backend 11.9 86.0 ms
ALB (TargetResponseTime) 9.4 54.3 ms
gateway (ms.total) 6.0 21.7 ms
backend − ALB (red y ALB) 2.3 47.1 ms
ALB − gateway (red al pod y lo que el gateway no ve) 3.4 36.6 ms
Lo confirmas en el paso 1: mundo/carga.py --una muestra los tres relojes de una sola request.
3Lo que suma cada requestLas 8 métricas del contrato, con sus nombres, etiquetas y bordes fijos: cada request suma al contador y, si no es 4xx, a la latencia.
Completa la clase Rastro. En su __init__ crea, en el registro que te pasan, el contador classifier_requests_total{code, source, model_version}, el gauge de requests en vuelo y seis histogramas con bordes fijos: los de la latencia alrededor del SLO de 200 ms, los del score con uno en 0.3 (el umbral de baja confianza). Los nombres y las etiquetas son los de las estaciones 6 y 10: las alertas y el análisis del canary los buscan así. fuente() reduce el header X-Client-Source a 4 valores (mobile, web, internal y, para todo lo demás, other), para que la etiqueta no crezca con cada texto nuevo; el log guarda el header tal como llegó. En anotar(), el contador suma siempre y la latencia solo si el status no es 4xx: un 415 tarda microsegundos y bajaría el p99 sin que nadie contestara más rápido. Las 10 categorías de classifier_top1_label_total se crean al arrancar, aunque valgan 0, para que el PSI del canary no vea huecos.
Pythongateway/app/rastro.py (lo que cambia: fuente() y la clase)
deffuente(header: str | None, fuentes: list[str]) -> str:
f = (header or"").strip().lower()
return f if f in fuentes else"other"defse_traza(rid: str, fraccion: float) -> bool:
returnFalse# paso 6classRastro:
def__init__(self, registro: CollectorRegistry, reglas: dict, modelo: dict):
self.version = modelo["model_version"]
self.fraccion = reglas["rastro"]["traza"]
v = self.version
self.requests = Counter("classifier_requests_total", "Requests por código, fuente y versión del modelo",
["code", "source", "model_version"], registry=registro)
self.latencia = Histogram("classifier_request_seconds", "Latencia total en el gateway (sin los 4xx)",
["source", "model_version"], buckets=MS, registry=registro)
self._pre = Histogram("classifier_preprocess_seconds", "Decode y preprocess", ["model_version"],
buckets=MS, registry=registro).labels(v)
self._inf = Histogram("classifier_inference_seconds", "La llamada a Triton, también si no contestó",
["model_version"], buckets=MS, registry=registro).labels(v)
self._top1 = Histogram("classifier_top1_score", "El score de la primera sugerencia", ["model_version"],
buckets=SCORE, registry=registro).labels(v)
self._bytes = Histogram("classifier_image_bytes", "Tamaño de la foto", ["source"], buckets=BYTES,
registry=registro)
self._label = Counter("classifier_top1_label_total", "Fotos por categoría que va primero (para el PSI)",
["label"], registry=registro)
for lb in modelo["labels"]: # cada categoría existe desde el arranque, aunque valga 0
self._label.labels(lb)
self.en_vuelo = Gauge("classifier_requests_in_flight", "Requests adentro ahora", registry=registro)
defbytes(self, n: int, fuente_: str) -> None:
self._bytes.labels(fuente_).observe(n)
defpre(self, s: float) -> None:
self._pre.observe(s)
definferencia(self, s: float) -> None:
self._inf.observe(s)
deftop1(self, score: float, label: str) -> None:
self._top1.observe(score)
self._label.labels(label).inc()
defanotar(self, ev: dict, status: int, fuente_: str, t0: float) -> None:
s = time.monotonic() - t0
ev["status"] = status
ev.setdefault("ms", {})["total"] = round(s * 1000, 1)
sys.stdout.write(json.dumps(ev, ensure_ascii=False, separators=(",", ":")) + "\n")
sys.stdout.flush()
self.requests.labels(str(status), fuente_, self.version).inc()
ifnot400 <= status < 500: # un 415 tarda microsegundos: no baja el p99 de nadie
ej = {"trace_id": ev["request_id"]} ifse_traza(ev["request_id"], self.fraccion) elseNone
self.latencia.labels(fuente_, self.version).observe(s, exemplar=ej)
Cada histograma de prometheus_client deja, por combinación de etiquetas, un bucket por borde, el +Inf, _count, _sum y _created: bordes + 4 series. se_traza() sigue en False hasta el paso 6.
Terminal
python mundo/recargar.py gateway
Salida
✓ gateway-6f7b9c4d58-xa7k2 (nodo-a) listo en 0.6 s
✓ gateway-6f7b9c4d58-qm4t8 (nodo-b) listo en 0.9 s
Terminal
python mundo/carga.py --tasa 20 --segundos 10
Con un poco de basura: algunos 415 y algún 405.
Salida
174 requests en 10 s (17.4/s) · códigos: 200: 165, 405: 1, 415: 8
el backend midió (solo 200): p50 11.7 ms · p99 81.2 ms
✓ metricas las 8 métricas del contrato, con sus tipos, etiquetas y bordes
✓ series-acotadas ≤ 187 series classifier_* por pod (tope 400) · ninguna etiqueta con un valor por request
2/2 en verde
Listo cuando: python verificar.py metricas series-acotadas: las 8 métricas con sus tipos, etiquetas y bordes, y ninguna etiqueta con un valor por request.
Ojo: Crea las métricas en el registro que te pasan, no en el global de prometheus_client: las pruebas de verificar.py crean varias apps en el mismo proceso y, en el global, el segundo registro del mismo nombre truena («Duplicated timeseries»). Y no renombres una métrica, aunque sea para «mejorarla»: las alertas y el análisis del canary la buscan por nombre, y se apagan sin que nadie se entere.
Conceptos de este paso ↓
Contador y gaugecounter / gaugeUn contador empieza en 0 y solo sube (las requests con 200): lo útil es cuánto subió en un rato. Un gauge sube y baja, y su valor sí dice algo en cada momento (las requests en vuelo ahora).Analogía, por qué importa y la trampa ↓
AnalogíaEl odómetro y el velocímetro de un auto: el odómetro solo sube y lo útil es cuántos km hiciste hoy (una resta); el velocímetro sube y baja y lo que importa es lo que marca ahora.
Por qué importaclassifier_requests_total{code, source, model_version} es el contador del que salen las requests por segundo y la fracción de errores; classifier_requests_in_flight es el gauge (de 0 a 16, el tope del gateway). Si el proceso se reinicia, el contador vuelve a 0: no es un error, es la regla, y quien lo lee entiende que un contador que baja se reinició. Las métricas viven en la memoria del pod; el gateway las expone en GET /metrics y alguien las lee.
TrampaLeer el valor de un contador como si dijera algo («lleva 957,980»): solo dice cuánto contó desde que arrancó. O usar un gauge para «las requests del último minuto»: no se suma bien entre pods y no sobrevive a un reinicio.
Histograma y bucketshistogram / buckets / le / histogram_quantileUn grupo de contadores, uno por bucket: cada observación suma 1 a los buckets cuyo borde (le, «menor o igual») es mayor o igual a su valor, más _count y _sum. De ahí sale el p99 sin guardar cada número.Analogía, por qué importa y la trampa ↓
AnalogíaUna fila de cubetas con letreros «hasta 5 ms», «hasta 10 ms», «hasta 20 ms»…: cada request echa una canica en cada cubeta cuyo letrero le queda grande. Contando canicas sabes debajo de qué tiempo cayó el 99 %.
Por qué importaLos bordes se eligen alrededor de lo que importa: los de la latencia alrededor del SLO (0.15, 0.2 y 0.25 s), los del score con uno en 0.3, el umbral de baja confianza. Como son contadores, los de varios pods se suman antes de estimar el percentil con histogram_quantile. Cada combinación de etiquetas cuesta bordes + 4 series: +Inf, _count, _sum y _created.
TrampaUn promedio o un percentil calculado en cada pod: el p99 de todo el gateway no es el promedio de los p99 de cada pod (y el Summary de prometheus_client ni siquiera calcula cuantiles). Y meter los 4xx a la latencia: un 415 tarda microsegundos y baja el p99 sin que nadie conteste más rápido.
Cardinalidadcardinality / label values / high-cardinality labelsCuántas series deja una métrica: una por cada combinación distinta de valores de sus etiquetas. Cada serie le cuesta a Prometheus memoria, un lugar en su índice y una muestra en cada lectura.Analogía, por qué importa y la trampa ↓
AnalogíaLos cajones de un archivero, uno por combinación de etiquetas: con «tipo de documento» y «año» son unos cuantos; si agregas «número de folio», necesitas un cajón por hoja y el archivero ya no cabe en el cuarto.
Por qué importaSolo pueden ser etiquetas los datos con una lista corta y conocida de valores: code, source reducida a 4, model_version. Lo que identifica a una request (su id, el sha256 de la foto) va al log. En C01, el request_id en la latencia serían 15 series nuevas por request: 150 millones al día, y Prometheus se queda sin memoria en horas.
TrampaCopiar un header a una etiqueta tal como llega (un caller con un bug manda un texto distinto en cada request), o creer que no pasa nada porque todo contesta 200: el costo aparece en Prometheus, horas después.
Precálculo ↓
3
¿Cuántas series deja el gateway en Prometheus, y cuántas si el request_id fuera etiqueta?
series de un histograma = (bordes + 4) × combinaciones de etiquetas · de un contador = 2 × combinaciones · con un id por request: series nuevas = (bordes + 4) × requests
En C01239 por pod si aparecen todas las combinaciones (88 del contador con 11 códigos × 4 fuentes, 60 de la latencia, 52 de los bytes…); con 3 pods ≈ 720, con 12 ≈ 2,900. Con el request_id en la latencia: 15 × 10,000,000 = 150 millones de series nuevas al día239 por pod · 150 M nuevas al día con el request_id
En el dojoel contrato del dojo por pod: contador 2 × 11 códigos × 4 fuentes = 88; latencia (11 + 4) × 4 = 60; preproceso e inferencia 15 cada uno; score (10 + 4) = 14; bytes (7 + 4) × 4 = 44; categorías 2 × 10 = 20; en vuelo, 1: 257 si aparecieran los 11 códigos. Al final del Guiado, el pod con más tenía 195. Con el request_id: 15 × 5 fotos/s = 75 series nuevas por segundo, ≈ 6.5 millones al día≈ 257 por pod (tope de verificar.py: 400) · 75 nuevas por segundo con el request_id
Qué decides con esto. Qué puede ser etiqueta: solo lo que tiene una lista corta y conocida de valores. source se reduce a 4 aunque el header traiga cualquier texto; el request_id va al log y al exemplar, nunca a una etiqueta. verificar.py pone el tope en 400 por pod: si algo crece sin techo, lo ve.
Después de 10 s de un caller con un X-Client-Source distinto en cada request: de 155 a 187 series, por la fuente other que apareció, y ya no crece.
Salida
187
Lo confirmas en la falla «Encontrar las lentas» de Romper: un histograma con la etiqueta request_id dejó 4,470 buckets en un pod con 20 s de carga.
4Prometheus lee los podsPrometheus lee cada pod del gateway una sola vez, descubriéndolos como lo haría con la API de Kubernetes, con las etiquetas pod, nodo y hash.
Prometheus trabaja jalando: cada 5 s le pide /metrics a cada objetivo que conoce (en C01, cada 15 s) y por cada uno guarda también up, 1 si la lectura salió bien. Ya lee lo de la plataforma (Triton, el ALB, Fluent Bit y el vigía); te falta el job gateway. Los pods no se escriben a mano: mundo/nodo.py publica en nodo/descubrimiento/pods.json lo que la API de Kubernetes le contestaría a kubernetes_sd_configs con role: pod, con las mismas etiquetas __meta_kubernetes_*, y Prometheus lo lee con file_sd_configs. Tus relabel_configs se quedan con los pods del namespace classifier, de la app gateway y del puerto http, y copian el nombre del pod, el nodo y el hash de la release a etiquetas que sí se guardan. Primero, la trampa: leer por los Services. Fuera de un canary, gateway-stable y gateway-canary eligen los mismos pods; leerlos por los dos, como haría un ServiceMonitor, pone cada pod dos veces y cada suma sale al doble. Por eso C01 usa un PodMonitor. En esta página, q '…' es una función de tu terminal que le pregunta a la API de Prometheus.
Terminalterminal (la función q: pégala una vez en cada terminal, con el venv activo)
q() { curl -s localhost:9952/api/v1/query --data-urlencode"query=$1"|python-c"
import json,sys
d=json.load(sys.stdin)
if d['status']!='success': print(d); sys.exit()
for r in d['data']['result'] or [{'metric': {}, 'value': [0, '(vacío)']}]:
m={k: v for k, v in r['metric'].items() if k not in ('instance',)}
print(('{' + ', '.join(f'{k}=\"{v}\"' for k, v in m.items()) + '}') if m else '{}', r['value'][1])"; }
Una línea por serie: sus etiquetas (sin instance) y su valor. «(vacío)» si la consulta no da nada.
observabilidad/prometheus.yml (la trampa: lo que cambia para leer por los Services)
servicios.json trae los endpoints de los dos Services; la etiqueta service es la que pone un ServiceMonitor.
YAMLobservabilidad/prometheus.yml
# Qué lee Prometheus y cada cuánto (solución de referencia). En C01: el PodMonitor del gateway en kube-prometheus-stack.global:
scrape_interval: 5s # C01: 15 s. En el dojo, más seguido para no esperar evaluation_interval: 5s
scrape_config_files: [/etc/prometheus-plataforma/*.yml] # Triton, el ALB, Fluent Bit y el vigía (de la plataforma)rule_files: [reglas.yml]
scrape_configs:
- job_name: gateway
# Los pods, no los Services: gateway-stable y gateway-canary eligen los mismos pods fuera de un canary, y leerlos# por los dos contaría cada request dos veces. Esto es lo que hace un PodMonitor. file_sd_configs: [{files: [/etc/prometheus-descubrimiento/pods.json]}]
metrics_path: /metrics
relabel_configs:
- {source_labels: [__meta_kubernetes_namespace], regex: classifier, action: keep}
- {source_labels: [__meta_kubernetes_pod_label_app_kubernetes_io_name], regex: gateway, action: keep}
- {source_labels: [__meta_kubernetes_pod_container_port_name], regex: http, action: keep}
- {source_labels: [__meta_kubernetes_pod_name], target_label: pod}
- {source_labels: [__meta_kubernetes_pod_node_name], target_label: nodo}
- {source_labels: [__meta_kubernetes_pod_label_rollouts_pod_template_hash], target_label: hash}
Los tres keep eligen; los otros tres copian. Lo que empieza con __ se tira después del relabel.
Terminal
curl-s localhost:9952/api/v1/targets |python-c"import json,sys;[print(t['labels']['job'], t['scrapeUrl'], t['health']) for t in json.load(sys.stdin)['data']['activeTargets']]"
Hoy Prometheus lee lo de la plataforma; del gateway, nada.
Salida
alb http://host.docker.internal:8957/metrics up
fluent-bit http://fluent-bit-a:2020/api/v2/metrics/prometheus up
fluent-bit http://fluent-bit-b:2020/api/v2/metrics/prometheus up
prometheus http://localhost:9090/metrics up
triton http://host.docker.internal:8955/metrics up
vigia-s3 http://host.docker.internal:8956/metrics up
Con 40 s de carga a 20 fotos/s más las 5 de siempre: la suma del gateway…
Salida
{} 49.35704835689457
Terminal
q'sum(rate(alb_request_count_total[30s]))'
…y la del ALB, que no cuenta doble: la mitad.
Salida
{} 24.87900483980641
Terminal
python mundo/recargar.py prometheus
Ahora con tu prometheus.yml: los pods, una vez cada uno.
Salida
Checking /etc/prometheus/prometheus.yml
SUCCESS: 1 rule files found
SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax
Checking /etc/prometheus/reglas.yml
SUCCESS: 0 rules found
✓ Prometheus recargado · 0 reglas en 0 grupos · objetivos: alb, fluent-bit, gateway, prometheus, triton, vigia-s3
Terminal
curl-s localhost:9952/api/v1/targets |python-c"import json,sys;[print(t['labels'].get('pod'), t['labels'].get('nodo'), t['labels'].get('hash'), t['scrapeUrl'], t['health']) for t in json.load(sys.stdin)['data']['activeTargets'] if t['labels']['job']=='gateway']"
Salida
gateway-6f7b9c4d58-xa7k2 nodo-a 6f7b9c4d58 http://nodo-a:8080/metrics up
gateway-6f7b9c4d58-qm4t8 nodo-b 6f7b9c4d58 http://nodo-b:8080/metrics up
✓ prometheus-lee los 2 pods del gateway, una vez cada uno, con pod, nodo y hash · up = 1
1/1 en verde
Listo cuando: python verificar.py prometheus-lee: los 2 pods, una vez cada uno, con pod, nodo y hash, y up = 1. La suma del gateway (5.40 req/s) es la del ALB (5.24); con la trampa, 49.4 contra 24.9.
Ojo: Si lees servicios.json sin la etiqueta service, no ves el doble: Prometheus descarta los objetivos repetidos que quedan con el mismo conjunto de etiquetas (lo hace su código; la documentación no lo dice). El ServiceMonitor sí pone service, y ahí aparece la cuenta doble. Y recarga con python mundo/recargar.py prometheus, no con un curl -X POST localhost:9952/-/reload a secas justo después de guardar: en la construcción del dojo, Docker Desktop le dio a Prometheus un prometheus.yml cortado (guarda unos segundos lo que el contenedor ya leyó de una carpeta compartida); recargar.py espera a que el contenedor vea el archivo completo.
Conceptos de este paso ↓
Scrape: Prometheus jalascrape / pull model / upPrometheus le pide /metrics a cada objetivo cada cierto tiempo (5 s en el dojo, 15 s en C01) y guarda cada número con la hora. Por cada objetivo guarda también up: 1 si la lectura salió bien, 0 si no.Analogía, por qué importa y la trampa ↓
AnalogíaEl que lee los medidores de luz: pasa por cada casa y anota lo que marca; si una casa no le abre, lo anota. Si las casas mandaran su lectura por correo, una casa sin luz simplemente no mandaría nada, y su silencio se parecería a «todo bien».
Por qué importaJalar en vez de recibir hace que un pod muerto se note: su up baja a 0. Cada serie junta una muestra por lectura: 86,400 ÷ 15 = 5,760 al día en C01. Lo primero que se revisa después de un cambio de monitoreo es que up exista y valga 1 para cada pod.
TrampaPensar que si Prometheus no se queja, está leyendo todo: si un pod no está en su lista, no hay ningún up de ese pod que baje. Nada truena; simplemente no lo lee.
Descubrimiento y relabel: pods, no Servicesservice discovery / relabel_configs / PodMonitor vs. ServiceMonitorPrometheus no lleva una lista fija de pods: los descubre (en C01, de la API de Kubernetes; en el dojo, de pods.json) y con relabel_configs se queda con los que quiere y les pone etiquetas.Analogía, por qué importa y la trampa ↓
AnalogíaUn cartero con el padrón del edificio: no se aprende los nombres, lee el padrón cada día y reparte según lo que dice. Si repartiera por el buzón de cada empresa y dos empresas comparten oficina, esa oficina recibiría todo dos veces.
Por qué importaEn C01 lo arma kube-prometheus-stack con un PodMonitor, que elige pods por sus etiquetas. Fuera de un canary, gateway-stable y gateway-canary eligen los mismos pods: un ServiceMonitor los leería por los dos Services, con la etiqueta service, y cada suma saldría al doble. Las etiquetas que empiezan con __ se tiran después del relabel: lo que quieras guardar (pod, nodo, hash) lo copias antes.
TrampaLeer por los Services, o creer que no pasa porque al probar sin la etiqueta service salía bien: Prometheus descarta objetivos repetidos con las mismas etiquetas, y la cuenta doble aparece con service. Y un keep sobre una etiqueta que otro equipo puede renombrar sin avisar.
Precálculo ↓
4
¿Cuántas muestras guarda Prometheus al día por el gateway?
muestras por serie al día = 86,400 ÷ segundos entre lecturas · muestras al día = series × muestras por serie
En C0186,400 ÷ 15 = 5,760 por serie; 717 series (3 pods) × 5,760 ≈ 4.1 millones al día; en 15 días de retención, ≈ 62 millones5,760 por serie · ≈ 4.1 M al día
En el dojo86,400 ÷ 5 = 17,280 por serie; las 376 series classifier_* que Prometheus guardaba de los 2 pods en el paso 4 × 17,280 ≈ 6.5 millones al día17,280 por serie · ≈ 6.5 M al día
Qué decides con esto. Cada cuánto leer: más seguido da más resolución y cuesta más memoria y disco. C01 lee cada 15 s; el dojo cada 5 s para no esperar (una ventana de 1 min junta 12 lecturas). Y por qué se vigilan las series: el costo es series × lecturas, y las series son lo que puede crecer sin techo.
Terminalterminal · compruébalo en el kit
q'count by (__name__) ({job="gateway", __name__=~"classifier_.*"})'
Las series del gateway en Prometheus, por nombre: cada histograma con sus _bucket, _count, _sum y _created.
5PromQL y las recording rulesLas preguntas de todos los días como recording rules (requests por segundo, fracción de errores del servidor y p99 por versión) y las dos alertas del servicio; y ver qué pasa con la tasa cuando un pod se reinicia.
PromQL tiene dos piezas para casi todo: rate(contador[1m]), cuánto subió por segundo en el último minuto, contando bien los reinicios, y sum by (…), que suma series y deja separadas las etiquetas que nombras. Una recording rule hace una consulta cada 5 s y guarda el resultado como una serie nueva con nombre: así el tablero y las alertas no recalculan lo mismo. Escribe en observabilidad/reglas.yml tres: requests por segundo por código; la fracción de 5xx sobre las requests que no son 4xx (los 4xx son culpa de quien llama: con ellos en el denominador, un caller que manda basura bajaría tu tasa), y el p99 por versión, sumando los buckets de los dos pods antes del histogram_quantile. Y las dos alertas del servicio: más de 1 % de 5xx durante 1 min, y el p99 arriba de 200 ms durante 2 min. Una alerta cuya condición se cumple queda pending y, si dura su for, firing. Después, la prueba del reinicio: matas el contenedor del pod a y comparas sum(rate(…)) con rate(sum(…)).
observabilidad/reglas.yml (las consultas y las dos alertas del servicio)
# Las preguntas de todos los días, ya calculadas (recording rules), y las alertas (solución de referencia).
# Ventanas de 1 min y esperas cortas: en el dojo se lee cada 5 s y nadie espera una hora. En C01: 5 min.
groups:
- name: classifier-consultas
rules:
- record: classifier:requests:rate1m # requests por segundo por código: primero rate, luego sum
expr: sum by (code) (rate(classifier_requests_total[1m]))
- record: classifier:errores_servidor:ratio_rate1m # 5xx sobre las que no son 4xx (sin 5xx: 0, no vacío)
expr: |
(sum(rate(classifier_requests_total{code=~"5.."}[1m])) or vector(0))
/
sum(rate(classifier_requests_total{code!~"4.."}[1m]))
- record: classifier:latencia:p99_1m # el p99 de todo el gateway, sumando los buckets de los pods
expr: histogram_quantile(0.99, sum by (le, model_version) (rate(classifier_request_seconds_bucket[1m])))
- name: classifier-alertas
rules:
- alert: ClassifierHigh5xxRate
expr: classifier:errores_servidor:ratio_rate1m > 0.01
for: 1m
labels: {severity: page}
annotations: {summary: "Más del 1 % de 5xx en el gateway"}
- alert: ClassifierP99Alto
expr: classifier:latencia:p99_1m > 0.2
for: 2m
labels: {severity: page}
annotations: {summary: "El p99 del gateway pasó de 200 ms"}
or vector(0): sin ningún 5xx, la serie de 5xx no existe y la división daría vacío, no 0. GatewaySinLectura y ALB5xx llegan en el paso 9; LogsStale, en el 7.
Terminal
python mundo/recargar.py prometheus
Salida
Checking /etc/prometheus/prometheus.yml
SUCCESS: 1 rule files found
SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax
Checking /etc/prometheus/reglas.yml
SUCCESS: 5 rules found
✓ Prometheus recargado · 5 reglas en 2 grupos · objetivos: alb, fluent-bit, gateway, prometheus, triton, vigia-s3
Terminal
q'classifier:requests:rate1m'
Después de 65 s de carga con 5 % de basura: requests por segundo por código.
Su runtime lo vuelve a arrancar: el mismo pod, con el contador en 0.
Salida
contenedor de gateway-6f7b9c4d58-xa7k2 (PID 8 en nodo-a) muerto con SIGKILL; su runtime lo vuelve a arrancar
✓ gateway-6f7b9c4d58-xa7k2 (nodo-a) listo en 0.0 s
reinicios: 1
Terminal
q'sum by (pod) (classifier_requests_total{code="200"})'
✓ consultas 3 recording rules sanas · errores 0.00% · p99 10.0 ms (resnet50-2026-11-01)
1/1 en verde
Listo cuando: python verificar.py consultas: las 3 recording rules sanas, la fracción de errores en 0 (no vacía) y el p99 por versión. Con el reinicio, sum(rate(…)) dio 21.9 req/s y rate(sum(…)), 49.9.
Ojo: rate(sum(…)) es el error clásico: en un tablero se ve como un pico que nadie explica cada vez que un pod se reinicia. La ventana de rate() necesita al menos dos lecturas: con lecturas cada 5 s, una de 1 min junta 12 (C01 lee cada 15 s y usa 5 min). Y después de cargar reglas nuevas, Prometheus necesita ≈ 1 min de datos para que una tasa de 1 min tenga sentido: antes, una regla puede dar vacío sin estar mal escrita.
Conceptos de este paso ↓
PromQL: rate, y luego sumPromQL / rate() / sum by / counter resetsrate(contador[1m]) da cuánto subió por segundo en el último minuto, leyendo cualquier bajada como un reinicio; sum by (…) suma series y deja separadas las etiquetas que nombras. Siempre sum(rate(…)).Analogía, por qué importa y la trampa ↓
AnalogíaMedir el ritmo de un grupo de corredores con podómetros que a veces se reinician: sacas los pasos por minuto de cada uno (si su podómetro marca menos, se reinició) y luego sumas. Si primero sumas los podómetros y uno se reinicia, el total baja y parece que todos se reiniciaron a la vez.
Por qué importaEs la base de todas las tasas: requests por segundo, la fracción de errores del servidor (5xx sobre lo que no es 4xx) y el p99 (histogram_quantile sobre sum by (le) de las tasas de los buckets). Con lecturas cada 5 s, una ventana de 1 min junta 12 muestras; con 15 s, C01 usa 5 min.
Tramparate(sum(…)): cuando un pod se reinicia, la suma baja, rate() la lee como un reinicio de todo y cuenta la suma entera otra vez: un pico falso. Y dividir los 5xx entre todas las requests: un caller que manda basura (4xx) baja tu tasa de errores.
Recording rulerecording rule / level:metric:operationsUna consulta que Prometheus hace solo cada pocos segundos y guarda como una serie nueva con nombre (nivel:métrica:operación). El tablero y las alertas leen ese nombre en lugar de repetir la cuenta.Analogía, por qué importa y la trampa ↓
AnalogíaEl corte de caja de una tienda cada hora: en lugar de que cada gerente sume los tickets cuando quiere saber cuánto se vendió, alguien hace la suma a la hora y la anota en una hoja con nombre.
Por qué importaLas preguntas de todos los días (requests por segundo por código, fracción de errores del servidor, p99 por versión) quedan calculadas igual para todos, y las alertas se escriben sobre ellas. En el dojo se evalúan cada 5 s, con ventanas de 1 min.
TrampaUna división sin numerador da vacío, no 0: sin ningún 5xx, la serie de 5xx no existe y la fracción desaparece del tablero. Por eso el or vector(0). Y un rate(sum(…)) dentro de una regla esconde el error detrás de un nombre bonito.
Alertas: for, pending y absentalerting rule / for / pending / firing / absent()Una regla que avisa si su condición se cumple durante un tiempo (for): mientras no lo cumple está pending; después, firing. absent() da una serie cuando no hay ninguna: así también suena lo que se calla.Analogía, por qué importa y la trampa ↓
AnalogíaUna alarma de humo con espera: un cerillo no la dispara; el humo que sigue 30 segundos, sí. Y otra alarma que suena si la de humo se quedó sin pila: la más peligrosa es la que no suena porque no tiene nada que medir.
Por qué importaLas 5 de la estación: ClassifierHigh5xxRate (más de 1 % por 1 min), ClassifierP99Alto (más de 200 ms por 2 min), GatewaySinLectura (Prometheus no lee los 2 pods, con absent), LogsStale (un nodo lleva 3 min sin subir a S3; C01: 30 min) y ALB5xx (los 5xx que pone el ALB). El for evita despertar a alguien por un pico de un instante.
TrampaAlertas que dependen de series que pueden desaparecer: si tu job pierde los pods, la de 5xx evalúa sobre nada y no suena, justo cuando no ves nada. Por eso GatewaySinLectura mira up con absent.
Precálculo ↓
5
Si un pod se reinicia, ¿qué tasa da sacar la tasa primero y qué tasa da sumar primero?
tasa = suma de los aumentos de cada serie ÷ ventana; un contador que baja se lee como reinicio y cuenta su valor nuevo
En C01un pod leído cada 15 s: 1,000,000 · 1,000,540 · 1,001,080 · 120 · 660; aumentos 540 + 540 + 120 + 540 = 1,740 en 60 s = 29 por segundo. La resta ingenua, (660 − 1,000,000) ÷ 60, da ≈ −16,65629 por segundo, no −16,656
En el dojoel paso 5 mata el contenedor del pod del nodo a: su contador de 200 pasa de 1,565 a 248. sum(rate(…[1m])) = 21.9 req/s; rate(sum(…)[1m:5s]) = 49.9: la suma bajó, rate() lo leyó como un reinicio de todo y volvió a contar la suma entera21.9 contra 49.9 req/s
Qué decides con esto. El orden dentro de cada recording rule: siempre sum(rate(…)), primero la tasa de cada serie y luego la suma. verificar.py consultas lo revisa en el texto de tu regla.
Primero la suma y luego la tasa, después del reinicio: un pico falso.
Salida
{} 49.945454545454545
Lo confirmas en el paso 5: resets() ve el reinicio en las series del pod a y no en las del b.
6Del p99 a una request: exemplarsQue ≈ 1 % de las requests deje su request_id como exemplar en el histograma de latencia, para pasar de la curva a una request concreta y a su línea.
Un exemplar es un id pegado a una observación del histograma: «una de las que cayeron en este bucket es la request tal». se_traza() decide con el hash del request_id (los primeros 8 caracteres hex del sha256, como número, menor que 0.01 × 2³²): la misma request siempre cae del mismo lado, en cualquier pod. En anotar(), si se traza, la latencia se observa con exemplar={'trace_id': request_id}. Para verlos hay dos condiciones: prometheus_client solo los escribe cuando quien lee pide el formato OpenMetrics (Prometheus 3 lo pide), y Prometheus solo los guarda con --enable-feature=exemplar-storage, que viene apagado (el compose del dojo lo prende). En C01 el exemplar lleva a una traza completa (OpenTelemetry y Tempo); en el dojo no hay trazas: lleva al request_id, y de ahí mundo/buscar.py encuentra la línea.
Pythongateway/app/rastro.py (lo que cambia: se_traza y el exemplar en anotar)
defse_traza(rid: str, fraccion: float) -> bool:
returnint(hashlib.sha256(rid.encode()).hexdigest()[:8], 16) < fraccion * 2**32# …defanotar(self, ev: dict, status: int, fuente_: str, t0: float) -> None:
s = time.monotonic() - t0
ev["status"] = status
ev.setdefault("ms", {})["total"] = round(s * 1000, 1)
sys.stdout.write(json.dumps(ev, ensure_ascii=False, separators=(",", ":")) + "\n")
sys.stdout.flush()
self.requests.labels(str(status), fuente_, self.version).inc()
ifnot400 <= status < 500: # un 415 tarda microsegundos: no baja el p99 de nadie
ej = {"trace_id": ev["request_id"]} ifse_traza(ev["request_id"], self.fraccion) elseNone
self.latencia.labels(fuente_, self.version).observe(s, exemplar=ej)
ej es None para el 99 %: la observación es la misma, sin exemplar.
Terminal
python mundo/recargar.py gateway
Salida
✓ gateway-6f7b9c4d58-xa7k2 (nodo-a) listo en 0.6 s
✓ gateway-6f7b9c4d58-qm4t8 (nodo-b) listo en 0.6 s
Terminal
python mundo/carga.py --tasa 30 --segundos 30
30 fotos por segundo durante 30 s.
Salida
872 requests en 30 s (29.1/s) · códigos: 200: 846, 405: 5, 415: 21
el backend midió (solo 200): p50 16.0 ms · p99 21.8 ms
La API de exemplars de Prometheus (experimental): los de los últimos 2 min, a un archivo.
No imprime nada.
Terminal
python-c"import json,sys;d=json.load(sys.stdin)['data'];ex=[(float(e['value']),e['labels']['trace_id'],s['seriesLabels']['le']) for s in d for e in s['exemplars']];ex.sort(reverse=True);print(len(ex),'exemplars en 2 min');[print(f'{v*1000:6.1f} ms le={le:<6} trace_id={t}') for v,t,le in ex[:5]]"< logs/exemplars.json
Ordenados del más lento al más rápido.
Salida
11 exemplars en 2 min
8.6 ms le=0.01 trace_id=e05fd2aa-78b0-48df-a941-e526d54e5d1e
7.8 ms le=0.01 trace_id=755f9807-188b-4db5-8629-0e3b8a50099b
7.7 ms le=0.01 trace_id=f00a1e32-cd18-43c8-baa9-b2a93bd9c551
7.4 ms le=0.01 trace_id=f38dc684-db66-4300-ab35-9bf610137204
7.0 ms le=0.01 trace_id=0113dff8-332b-4980-92e4-a2a6be85f316
✓ reglas-de-conteo los 4xx cuentan pero no entran a la latencia · source reducido a 4 valores · se_traza ≈ 1 % y determinista
1/1 en verde
Listo cuando: python verificar.py reglas-de-conteo: los 4xx cuentan pero no entran a la latencia, source tiene 4 valores y se_traza elige ≈ 1 %, siempre igual. El exemplar más lento (8.6 ms) te llevó a su línea.
Ojo: Con un muestreo que decide al principio, el exemplar casi nunca es de las lentas: aquí los 11 cayeron en los buckets le=0.01, los de las requests normales. Y el texto de /metrics lleva a lo más un exemplar por bucket (el último): entre dos lecturas, los demás se pisan. Si no ves ninguno, revisa en orden: que se_traza elija algo, que pidas OpenMetrics y que Prometheus tenga exemplar-storage. Con random() en lugar del hash la muestra sale bien de tamaño, pero nadie puede repetir la decisión después, y dos pods podrían decidir distinto para la misma request reintentada.
Concepto de este paso ↓
Exemplarexemplar / trace_id / OpenMetrics / head samplingUn id pegado a una observación de un histograma: «una de las que cayeron en este bucket es la request tal». En el dojo, el request_id de ≈ 1 % de las requests, elegidas por el hash del id.Analogía, por qué importa y la trampa ↓
AnalogíaUn post-it en una caja de la bodega: la etiqueta dice «150 paquetes de 10 a 20 kg»; el post-it dice «uno de ellos es el folio 5a1e07c3», para que puedas abrir uno y ver cómo viene.
Por qué importaUne la métrica con una request concreta: ves el p99 subir, tocas un punto y llegas al id (en C01, a su traza; en el dojo, con mundo/buscar.py, a su línea). Dos condiciones: prometheus_client solo los escribe en el formato OpenMetrics, que Prometheus 3 pide al leer, y Prometheus solo los guarda con --enable-feature=exemplar-storage, que viene apagado.
TrampaEsperar que el exemplar sea una de las lentas: el muestreo decide al principio (head sampling), sin saber cuánto va a tardar, y cada bucket lleva a lo más uno (el último) entre dos lecturas. Para guardar todas las lentas hay que decidir al final (tail sampling).
Precálculo ↓
6
¿Cuántas requests dejan exemplar con el 1 %, y cuántas de las lentas?
requests con exemplar = requests × fracción · lentas con exemplar = requests × fracción de lentas × fracción con exemplar
En C01hora pico: 350 × 3,600 = 1,260,000 requests; 0.5 % lentas (más de 200 ms) = 6,300; al 1 %, 6,300 × 0.01 = 63 con traza≈ 63 lentas con traza por hora pico
En el dojoel paso 6: 872 requests de la carga más ≈ 600 del tráfico de siempre en la ventana de 2 min; al 1 %, ≈ 15 con exemplar. Prometheus devolvió 11: el texto de /metrics lleva a lo más un exemplar por bucket (el último), y entre dos lecturas los demás se pisan≈ 15 esperados · 11 en Prometheus
Qué decides con esto. Que el exemplar sirve para pasar de la curva a una request de ejemplo, no para encontrar todas las lentas: con un muestreo que decide al principio (head sampling), casi ninguna lenta queda elegida. Para guardarlas todas hay que decidir al final (tail sampling), que pide juntar la request completa antes de decidir; C01 empieza con el simple.
Terminalterminal · compruébalo en el kit
python-c"import json,sys;d=json.load(sys.stdin)['data'];ex=[(float(e['value']),e['labels']['trace_id'],s['seriesLabels']['le']) for s in d for e in s['exemplars']];ex.sort(reverse=True);print(len(ex),'exemplars en 2 min');[print(f'{v*1000:6.1f} ms le={le:<6} trace_id={t}') for v,t,le in ex[:5]]"< logs/exemplars.json
Los exemplars de los últimos 2 min, del más lento al más rápido.
Salida
11 exemplars en 2 min
8.6 ms le=0.01 trace_id=e05fd2aa-78b0-48df-a941-e526d54e5d1e
7.8 ms le=0.01 trace_id=755f9807-188b-4db5-8629-0e3b8a50099b
7.7 ms le=0.01 trace_id=f00a1e32-cd18-43c8-baa9-b2a93bd9c551
7.4 ms le=0.01 trace_id=f38dc684-db66-4300-ab35-9bf610137204
7.0 ms le=0.01 trace_id=0113dff8-332b-4980-92e4-a2a6be85f316
Lo confirmas en el paso 6: el exemplar más lento (8.6 ms) lleva a su línea con mundo/buscar.py.
7El camino del log a S3Las líneas del disco de cada nodo llegan a S3 cada minuto, comprimidas y con el nombre del nodo; si S3 se cae, la request no se entera, nada se pierde y LogsStale avisa.
En cada nodo corre un Fluent Bit (en C01, un pod de un DaemonSet: uno por nodo, y uno más en cada nodo nuevo). Escribe observabilidad/fluent-bit.conf. La entrada tail sigue los archivos /var/log/containers/gateway-* con el parser cri (separa la hora del runtime, el flujo y tu texto) y anota en su DB hasta dónde leyó cada archivo. El filtro record_modifier le agrega el nodo a cada registro. La salida s3 junta lo de cada minuto (upload_timeout 1m; en C01, 5 min) y lo sube con gzip a /logs/crudo/AAAA/MM/DD/HH/<nodo>-<uuid>.gz; la carpeta de la hora sale de la hora del primer registro del archivo, y $UUID es una cadena al azar (de 8 caracteres en el dojo) para que dos archivos no choquen. Lo que no pudo subir lo guarda en disco (store_dir) y lo reintenta. Y una alerta más en reglas.yml: LogsStale, si un nodo lleva 3 min sin subir nada (C01: 30 min), con la hora que publica el vigía de S3. Después, el simulacro: apagas S3 con tráfico.
observabilidad/fluent-bit.conf
# El Fluent Bit de cada nodo (solución de referencia): lee los logs del gateway y los sube a S3 cada minuto.
# La misma configuración en los dos nodos; ${NODO} lo pone cada contenedor (en C01: el nombre del nodo).
[SERVICE]
Flush 1
Log_Level info
HTTP_Server On
HTTP_Listen 0.0.0.0
HTTP_Port 2020
[INPUT]
Name tail
Path /var/log/containers/gateway-*_classifier_gateway-*.log
multiline.parser cri
Tag gateway.*
DB /var/fluent-bit/tail.db
Refresh_Interval 5
Rotate_Wait 30
Mem_Buf_Limit 16MB
[FILTER]
Name record_modifier
Match gateway.*
Record nodo ${NODO}
[OUTPUT]
Name s3
Match gateway.*
bucket ml-datos
region us-east-1
endpoint http://s3:9000
s3_key_format /logs/crudo/%Y/%m/%d/%H/${NODO}-$UUID.gz
compression gzip
use_put_object On
upload_timeout 1m
store_dir /var/fluent-bit/s3
store_dir_limit_size 256M
retry_limit 60 # por omisión se rinde a los ≈ 6 intentos (≈ 30 s de S3 caído) y manda el pedazo a cuarentena
use_put_object On: cada archivo en una sola subida (en C01, así el rol de Fluent Bit escribe sin poder descifrar). Por omisión, upload_timeout es 10m y total_file_size 100M (hasta 1G con use_put_object): aquí sube cada minuto mucho antes de llenarse. store_dir_limit_size por omisión es 0, sin tope; con tope, al llenarse descarta.
observabilidad/reglas.yml (la alerta que se agrega)
- alert: LogsStale # 3 veces el upload_timeout de Fluent Bit (C01: 30 min)
expr: time() - max by (nodo) (dojo_s3_ultimo_objeto_timestamp_seconds) > 180
labels: {severity: ticket}
annotations: {summary: "El nodo {{ $labels.nodo }} lleva 3 min sin subir logs a S3"}
Sin for: el umbral de 180 s ya es la espera.
Terminal
python mundo/recargar.py prometheus
Salida
Checking /etc/prometheus/prometheus.yml
SUCCESS: 1 rule files found
SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax
Checking /etc/prometheus/reglas.yml
SUCCESS: 6 rules found
✓ Prometheus recargado · 6 reglas en 2 grupos · objetivos: alb, fluent-bit, gateway, prometheus, triton, vigia-s3
Terminal
python mundo/recargar.py fluent-bit
Como un rollout del DaemonSet: los dos con tu configuración.
Salida
✓ fluent-bit-a reiniciado con tu fluent-bit.conf
✓ fluent-bit-b reiniciado con tu fluent-bit.conf
python-c"
import sys; sys.path.insert(0, '.')
from datetime import datetime, timezone
from mundo.comun import objetos
h = datetime.now(timezone.utc)
for o in objetos(f'logs/crudo/{h:%Y/%m/%d/%H}/')[-4:]: print(o['Key'], o['Size'], 'B')"
Los objetos de esta hora en S3: uno por nodo y por minuto.
Salida
logs/crudo/2026/11/19/05/a-NUj3q405.gz 50004 B
logs/crudo/2026/11/19/05/b-UMO9oydU.gz 52679 B
✗ log-en-s3 S3 no contesta en :9950 (EndpointConnectionError): el log se está quedando en el buffer de cada nodo
0/1 en verde · falta: log-en-s3
Terminal
curl-s localhost:9952/api/v1/alerts |python-c"import json,sys;[print(a['labels']['alertname'], a['labels'].get('nodo',''), a['state']) for a in json.load(sys.stdin)['data']['alerts']]"
Más de 3 min sin archivos nuevos: LogsStale, nodo por nodo.
Salida
LogsStale a firing
LogsStale b firing
Terminal
docker compose start s3
Salida
Container taller-c01-request-s3-1 Starting
Container taller-c01-request-s3-1 Started
✓ log-en-s3 los dos nodos suben a S3 (lo último, hace 24 s y menos) · logs/crudo/2026/11/19/05/b-qR7btmvg.gz
1/1 en verde
Listo cuando: python verificar.py log-en-s3: los dos nodos suben a S3, con el nombre de archivo y los campos time, stream, log y nodo, sin pedazos en cuarentena. Con S3 apagado, las 1,725 requests de la carga contestaron (200: 1672, 405: 8, 415: 45) y LogsStale sonó.
Ojo: Con el retry_limit por omisión, el plugin s3 de Fluent Bit 5.1.5 reintenta un pedazo cada ≈ 5 s y a los 6 intentos se rinde («Chunk file failed to send 6 times, will not retry» y el pedazo va a cuarentena): aguanta ≈ 30 s de S3 caído. En una prueba de la construcción, 3 min de caída mandaron dos pedazos (≈ 2 min de líneas) a cuarentena y no llegaron nunca a S3, con fluentbit_output_retries_failed_total en 0. retry_limit no_limits lo recorta a 5. Con retry_limit 60 reintenta cada ≈ 18 s y, al volver S3, subió todo: nunca bloquear la request, pero tampoco perder en silencio. Y por qué los nodos son contenedores con su propio volumen: en esta Mac, con los logs en una carpeta compartida, Fluent Bit no se enteraba de lo que un proceso del Mac agregaba al archivo (Docker Desktop no le avisaba al contenedor por inotify). Es lo que pasó al construir el dojo, no algo documentado. Al arrancar, Fluent Bit lee su DB y sube lo atrasado.
Conceptos de este paso ↓
Fluent Bit en cada nodoFluent Bit / tail input / DaemonSetUn programa chico que corre en cada nodo, sigue los archivos de log mientras crecen (tail, con el parser cri), anota hasta dónde leyó (su DB) y sube lo que junta a S3. En C01, un DaemonSet: un pod por nodo.Analogía, por qué importa y la trampa ↓
AnalogíaEl mensajero de cada piso de un edificio: pasa por las bandejas de su piso, se lleva lo nuevo, anota en su libreta hasta qué hoja recogió y lo manda al archivo central. Con un mensajero por piso, ningún piso se queda sin recoger, ni siquiera uno nuevo.
Por qué importaEl gateway no conoce S3: Fluent Bit hace el camino. Con un Deployment de 3 réplicas, dos nodos podrían quedarse sin quien lea sus logs; el DaemonSet pone uno en cada nodo, también en los que lleguen. Si se cae, las líneas esperan en el disco del nodo y, al volver, sigue donde se quedó gracias a su DB, mientras el kubelet no haya rotado esos archivos.
TrampaPensar que si Fluent Bit se cae no pasa nada porque el gateway sigue contestando: el log de ese nodo se atrasa y, si tarda más que la rotación (5 archivos de 10 MiB), esas líneas se pierden. Lo avisa LogsStale, por nodo.
Buffer en disco y reintentosstore_dir / retry_limit / quarantine / never block the requestLo que Fluent Bit no pudo subir lo guarda en el disco del nodo (store_dir, con su tope) y lo reintenta. Nunca frena la request: si S3 se cae, se atrasa el monitoreo, no el servicio.Analogía, por qué importa y la trampa ↓
AnalogíaLa bandeja de salida de una oficina cuando el correo no pasa: las cartas se juntan ahí y se mandan cuando vuelve el cartero. Si la bandeja se llena, o si alguien se cansa de esperar y tira las cartas viejas, esas se pierden.
Por qué importaEn C01, 1 GB por nodo aguanta ≈ 16 h de S3 caído. El otro tope son los reintentos: con el retry_limit por omisión, el plugin s3 de Fluent Bit 5.1.5 se rinde a los 6 intentos (≈ 30 s) y manda el pedazo a cuarentena: esas líneas no llegan nunca. Por eso la solución usa retry_limit 60 y verificar.py reprueba si hubo cuarentena.
TrampaFiarse de las métricas de reintentos del motor: en la construcción del dojo, fluentbit_output_retries_failed_total siguió en 0 mientras se perdían pedazos. Y un log que espera a que S3 confirme: cualquier lentitud de S3 se vuelve lentitud para todos.
Precálculo ↓
7
Si S3 se cae, ¿cuánto aguanta un nodo antes de perder líneas?
aguante en horas = buffer del nodo ÷ lo que escribe un nodo en una hora; y nunca más que lo que Fluent Bit reintenta antes de rendirse
En C011 GB × 2 nodos × 24 h ÷ 3 GB al día = 16 h con el tráfico parejo; si todo fuera hora pico (1/8 del día), 1 ÷ (3 ÷ 8 ÷ 2) ≈ 5.3 h. LogsStale avisa a los 30 min≈ 16 h (≈ 5 h en pico)
En el dojoun nodo recibe la mitad de las 5 fotos/s: 2.5 × 310 B × 3,600 ≈ 2.8 MB por hora; 256 MB ÷ 2.8 ≈ 92 h de disco. Pero con el retry_limit por omisión, el plugin s3 reintenta cada ≈ 5 s y a los 6 intentos se rinde: ≈ 30 s de S3 caído y el pedazo se va a cuarentena≈ 92 h de disco · ≈ 30 s con el retry_limit por omisión
Qué decides con esto. Que el tope real no siempre es el disco: es cuántas veces reintenta Fluent Bit. Con el valor por omisión, en una prueba de la construcción del dojo, 3 min de S3 caído mandaron dos pedazos (≈ 2 min de líneas) a cuarentena y nunca llegaron a S3, con fluentbit_output_retries_failed_total en 0; retry_limit no_limits lo recorta a 5. Por eso la solución usa retry_limit 60 (reintenta cada ≈ 18 s) y verificar.py log-en-s3 reprueba si hubo cuarentena. LogsStale avisa mucho antes de que el disco se llene.
Lo confirmas en el paso 7: con S3 apagado, las 1,725 requests de la carga contestaron y, al volver, el Fluent Bit del nodo a subió 3 pedazos atrasados de un jalón.
8El job diario: del crudo a ParquetEl job diario lee el crudo de ayer, quita los repetidos, se queda con las líneas del gateway y escribe un Parquet por versión del modelo; correrlo dos veces da lo mismo.
Escribe diario/a_parquet.py, la primera parte del job monitoreo-diario que en C01 corre a la 01:00 UTC. Lee los archivos de logs/crudo/ del día, en UTC, y los de la hora 00 del siguiente (un archivo subido a las 00:00:40 trae líneas de las 23:59). Se queda con los registros de stdout cuyo texto es un JSON con request_id y quita los repetidos: Fluent Bit entrega al menos una vez, y si una subida se reintenta después de que S3 sí la guardó, el mismo archivo llega dos veces. La llave es (request_id, time): el mismo id con otra hora es otra request de verdad. Escribe Parquet, una tabla por columnas, en logs/predicciones/dt=AAAA-MM-DD/model_version=…/: una consulta de un día y una versión solo lee esa carpeta. Antes de escribir borra lo que hubiera de ese día: correrlo dos veces da lo mismo (idempotente). El log de ayer trae el rollout de la 14 a la 15 a las 16:00 UTC: salen dos carpetas.
Pythondiario/a_parquet.py
"""El job monitoreo-diario, primera parte: del log crudo de un día a Parquet (solución de referencia).
python diario/a_parquet.py # ayer (UTC), como el job de la 01:00
python diario/a_parquet.py --dia 2026-11-18
Contrato:
- Lee todos los objetos de s3://ml-datos/logs/crudo/AAAA/MM/DD/ (las 24 carpetas de hora) del día, en UTC, y los de
la hora 00 del día siguiente (un archivo subido a las 00:00:40 trae líneas de las 23:59). Cada uno es un .gz con una línea JSON por registro de Fluent Bit: time (la hora del runtime), stream, _p, log (el texto que
escribió el gateway) y nodo.
- Se queda con las de stdout cuyo log es un JSON con request_id; las demás (stderr, texto suelto) son «ignoradas».
- Fluent Bit entrega al menos una vez: si sube un archivo dos veces, hay registros repetidos. Se quitan los repetidos
por (request_id, time).
- Una fila por request, con hora (timestamp UTC), nodo, request_id, caller, source, model_version, status, top1 y score
(la primera sugerencia, o nulos), ms_pre, ms_triton, ms_post, ms_total, bytes, sha256 y error. Solo las de ese día.
- Escribe s3://ml-datos/logs/predicciones/dt=AAAA-MM-DD/model_version=<v>/parte-0.parquet, una carpeta por versión,
después de borrar lo que hubiera en dt=AAAA-MM-DD/: correrlo dos veces da lo mismo (idempotente).
- Imprime cuántos objetos y registros leyó, cuántos repetidos e ignorados quitó y cuántas filas quedaron por versión.
"""from __future__ import annotations
import argparse
import gzip
import json
import sys
import tempfile
from datetime import date, datetime, timedelta, timezone
from pathlib import Path
import duckdb
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
from mundo.comun import BUCKET, CRUDO, PREDICCIONES, objetos, s3 # noqa: E402
COLUMNAS = {"hora": "TIMESTAMP", "nodo": "VARCHAR", "request_id": "VARCHAR", "caller": "VARCHAR", "source": "VARCHAR",
"model_version": "VARCHAR", "status": "INTEGER", "top1": "INTEGER", "score": "DOUBLE", "ms_pre": "DOUBLE",
"ms_triton": "DOUBLE", "ms_post": "DOUBLE", "ms_total": "DOUBLE", "bytes": "BIGINT", "sha256": "VARCHAR",
"error": "VARCHAR"}
deffila(reg: dict) -> dict | None:
if reg.get("stream") != "stdout":
returnNonetry:
ev = json.loads(reg.get("log", ""))
except (json.JSONDecodeError, TypeError):
returnNoneifnotisinstance(ev, dict) or"request_id"notin ev:
returnNone
ms, top5 = ev.get("ms") or {}, ev.get("top5") or []
return {"hora": reg["time"], "nodo": reg.get("nodo"), "request_id": ev["request_id"], "caller": ev.get("caller"),
"source": ev.get("source"), "model_version": ev.get("model_version"), "status": ev.get("status"),
"top1": top5[0][0] if top5 elseNone, "score": top5[0][1] if top5 elseNone,
"ms_pre": ms.get("pre"), "ms_triton": ms.get("triton"), "ms_post": ms.get("post"), "ms_total": ms.get("total"),
"bytes": ev.get("bytes"), "sha256": ev.get("sha256"), "error": ev.get("error")}
defmain() -> None:
ap = argparse.ArgumentParser()
ap.add_argument("--dia", type=date.fromisoformat,
default=(datetime.now(timezone.utc) - timedelta(days=1)).date())
dia = ap.parse_args().dia
c = s3()
# un archivo subido a las 00:00:40 trae líneas de las 23:59: también se lee la primera hora del día siguiente
objs = objetos(f"{CRUDO}{dia:%Y/%m/%d}/") + objetos(f"{CRUDO}{dia + timedelta(days=1):%Y/%m/%d}/00/")
vistos, filas, leidos, repetidos, ignorados = set(), [], 0, 0, 0for o in objs:
texto = gzip.decompress(c.get_object(Bucket=BUCKET, Key=o["Key"])["Body"].read()).decode("utf-8", "replace")
for linea in texto.splitlines():
leidos += 1try:
f = fila(json.loads(linea))
except json.JSONDecodeError:
f = Noneif f isNoneornot f["hora"].startswith(dia.isoformat()):
ignorados += 1continue
llave = (f["request_id"], f["hora"])
if llave in vistos:
repetidos += 1continue
vistos.add(llave)
filas.append(f)
prefijo = f"{PREDICCIONES}dt={dia.isoformat()}/"for o inobjetos(prefijo):
c.delete_object(Bucket=BUCKET, Key=o["Key"])
por_version: dict[str, int] = {}
with tempfile.TemporaryDirectory() as tmp:
ndjson = Path(tmp) / "filas.json"
ndjson.write_text("".join(json.dumps(f) + "\n"for f in filas))
con = duckdb.connect()
cols = ", ".join(f"'{k}': '{v}'"for k, v in COLUMNAS.items())
con.execute(f"CREATE TABLE t AS SELECT * FROM read_json('{ndjson}', format='newline_delimited', columns={{{cols}}})"if filas else"CREATE TABLE t AS SELECT 1 WHERE false")
for (v,) in con.execute("SELECT DISTINCT model_version FROM t ORDER BY 1").fetchall() if filas else []:
destino = Path(tmp) / f"{v}.parquet"
con.execute(f"COPY (SELECT * FROM t WHERE model_version = ? ORDER BY hora) TO '{destino}' (FORMAT parquet)", [v])
c.upload_file(str(destino), BUCKET, f"{prefijo}model_version={v}/parte-0.parquet")
por_version[v] = con.execute("SELECT count(*) FROM t WHERE model_version = ?", [v]).fetchone()[0]
print(f"{dia}: {len(objs)} objetos · {leidos:,} registros · {repetidos:,} repetidos · {ignorados:,} ignorados")
for v, n in por_version.items():
print(f" {prefijo}model_version={v}/parte-0.parquet {n:,} filas")
print(f"total: {sum(por_version.values()):,} filas")
if __name__ == "__main__":
main()
DuckDB escribe el Parquet con los tipos de COLUMNAS: la hora como TIMESTAMP, no como texto.
python-c"
import sys, duckdb; sys.path.insert(0, '.')
from datetime import datetime, timedelta, timezone
from mundo.comun import BUCKET, PREDICCIONES, objetos, s3
dia = (datetime.now(timezone.utc) - timedelta(days=1)).date()
c = s3()
for o in objetos(f'{PREDICCIONES}dt={dia}/'):
c.download_file(BUCKET, o['Key'], f'logs/{o[\"Key\"].split(\"=\")[2].split(\"/\")[0]}.parquet')
con = duckdb.connect()
print(con.sql(\"SELECT model_version, count(*) AS filas, round(quantile_cont(ms_total, 0.99), 1) AS p99_ms, round(avg(CASE WHEN status >= 500 THEN 1 ELSE 0 END) * 100, 2) AS pct_5xx, round(avg(score), 3) AS score_medio FROM 'logs/resnet50-*.parquet' GROUP BY 1 ORDER BY 1\"))
print(con.sql(\"SELECT hour(hora) AS hora_utc, model_version, count(*) AS filas FROM 'logs/resnet50-*.parquet' WHERE hour(hora) BETWEEN 15 AND 16 GROUP BY 1, 2 ORDER BY 1, 2\"))
print(con.sql(\"DESCRIBE SELECT * FROM 'logs/resnet50-2026-11-01.parquet'\").fetchall()[:6])"
DuckDB lee los Parquet: filas, p99 y 5xx por versión, y el cambio de versión a las 16:00 UTC.
✓ parquet dt=2026-11-18 · resnet50-2026-10-01: 7,830 filas · resnet50-2026-11-01: 4,019 filas · cuadra con el crudo
1/1 en verde
Listo cuando: python verificar.py parquet: resnet50-2026-10-01, 7,830 filas y resnet50-2026-11-01, 4,019 filas, sin repetidos, y cuadra con una cuenta independiente del crudo.
Ojo: El día se cuenta en UTC, igual que la carpeta de S3 y la hora del runtime: si filtras con la hora local de tu Mac, pierdes o duplicas las filas de la frontera. Sin quitar repetidos, los 2 archivos subidos dos veces meten 37 filas de más, y el join del mes contaría esas fotos dos veces. Y si el job agrega en lugar de reemplazar, un reintento duplica el día entero.
Conceptos de este paso ↓
Entrega al menos una vezat-least-once delivery / deduplicationFluent Bit garantiza que cada línea llegue, no que llegue una sola vez: si una subida falla después de que S3 sí la guardó, la reintenta y el mismo archivo llega dos veces. Quien lee quita los repetidos.Analogía, por qué importa y la trampa ↓
AnalogíaMandar una carta importante y, como no llegó el acuse, mandarla otra vez: la otra persona puede recibir dos, y por eso numeras tus cartas, para que tire la repetida.
Por qué importaEl log de ayer del dojo trae dos archivos subidos dos veces. Sin quitarlos, el join del mes contaría esas fotos dos veces. La llave es (request_id, time): el mismo id con otra hora es otra request de verdad (un caller que reintenta con el mismo X-Request-ID), y esa se queda.
TrampaQuitar repetidos solo por request_id: borra los reintentos legítimos del caller. O creer que «exactamente una vez» viene gratis: casi ningún camino de logs lo promete.
Parquet por fecha y versiónParquet / partitioning / dt= / idempotent jobParquet guarda una tabla por columnas, comprimida y con el tipo de cada columna. Partida en carpetas (dt=AAAA-MM-DD/model_version=…/), una consulta de un día y una versión solo lee esa carpeta.Analogía, por qué importa y la trampa ↓
AnalogíaUn archivero con un cajón por día y una carpeta por versión adentro: para ver cómo le fue a la versión 15 el martes, abres un cajón y una carpeta, no el archivero entero.
Por qué importaEl crudo de C01 son ≈ 3 GB de JSON al día; en Parquet, ≈ 0.5 GB en 4 archivos. De ahí leen el PSI diario, la aceptación y las fotos para etiquetar de la estación 12. El job es idempotente: borra lo de ese día y lo vuelve a escribir, así que correrlo dos veces (un reintento del orquestador) da lo mismo.
TrampaUn job que agrega en lugar de reemplazar: el reintento duplica el día. Y filtrar el día con la hora local: el crudo y la carpeta están en UTC, y en las fronteras del día se pierden o se duplican filas.
Precálculo ↓
8
¿Cuántas filas sobrarían sin quitar los repetidos?
filas repetidas = archivos subidos dos veces × líneas por archivo · líneas por archivo = requests al día ÷ (archivos al día por nodo × nodos)
En C0110,000,000 ÷ (288 × 2) ≈ 17,400 líneas por archivo: cada archivo que se sube dos veces mete ≈ 17,400 filas de más≈ 17,400 filas de más por archivo repetido
En el dojoel día de ayer: 11,887 registros leídos de 578 objetos; 37 repetidos (los 2 archivos subidos dos veces) y 1 ignorados (stderr o texto suelto): 11,887 − 37 − 1 = 11,849 filas37 filas de más sin quitar repetidos
Qué decides con esto. Que el job diario quita repetidos siempre, con la llave (request_id, time): Fluent Bit entrega al menos una vez. Sin eso, el join del mes contaría esas fotos dos veces y las etiquetas de entrenamiento saldrían chuecas.
Terminalterminal · compruébalo en el kit
python diario/a_parquet.py
Lo que leyó, lo que quitó y lo que quedó por versión.
9Lo que el gateway no veLas dos alertas que faltan, GatewaySinLectura y ALB5xx, y la prueba de lo que el gateway no ve: con Triton caído, el ALB contesta 503 él mismo y solo sus métricas lo cuentan.
Dos alertas para los puntos ciegos. GatewaySinLectura suena si Prometheus no lee los 2 pods; con absent(up{job="gateway"} == 1) suena también cuando no hay ninguna serie: si un cambio de etiquetas deja a tu job sin pods, las alertas que miran classifier_* evalúan sobre nada y no suenan, y esta sí. ALB5xx mira la fracción de 5xx que pone el propio ALB. ¿Por qué hace falta? Cuando Triton se cae, los pods del gateway contestan 503 en /readyz y el ALB los da de baja de su target group (en C01: salen de los Endpoints y el AWS Load Balancer Controller los da de baja); sin destinos registrados, el ALB contesta 503 él mismo y las requests nunca llegan a un pod. classifier_requests_total no sube y la fracción de 5xx del gateway se queda sin requests: el peor momento del servicio se ve tranquilo. Lo cuentan las métricas del ALB (en C01, CloudWatch: HTTPCode_ELB_5XX_Count). Como RequestCount solo cuenta las requests para las que el ALB pudo elegir un destino, el denominador suma las dos.
observabilidad/reglas.yml (las dos alertas que se agregan)
- alert: GatewaySinLectura # el monitoreo que falla en silencio: no hay qué leer
expr: absent(up{job="gateway"} == 1) or count(up{job="gateway"} == 1) < 2
for: 30s
labels: {severity: ticket}
annotations: {summary: "Prometheus no está leyendo los 2 pods del gateway"}
- alert: ALB5xx # lo que el gateway no ve: el ALB contestando 5xx él mismo
expr: |
(sum(rate(alb_httpcode_elb_total{code=~"5.."}[1m])) or vector(0))
/
(sum(rate(alb_request_count_total[1m])) + sum(rate(alb_httpcode_elb_total{code=~"5.."}[1m]))) > 0.005
for: 30s
labels: {severity: page}
annotations: {summary: "El ALB contesta 5xx él mismo (sin destinos sanos)"}
En el ALB de AWS, el 503 propio sale cuando no queda ningún destino registrado. Si los destinos siguen registrados pero todos fallan el health check, el ALB «abre el paso» (fail open) y les manda tráfico igual; el ALB del dojo solo imita el primer caso.
Terminal
python mundo/recargar.py prometheus
Salida
Checking /etc/prometheus/prometheus.yml
SUCCESS: 1 rule files found
SUCCESS: /etc/prometheus/prometheus.yml is valid prometheus config file syntax
Checking /etc/prometheus/reglas.yml
SUCCESS: 8 rules found
✓ Prometheus recargado · 8 reglas en 2 grupos · objetivos: alb, fluent-bit, gateway, prometheus, triton, vigia-s3
Terminal
python verificar.py alertas
Salida
✓ alertas las 5 alertas cargadas, sanas y sin sonar
1/1 en verde
Terminal
python mundo/nodo.py parar triton
Triton se cae. En ≈ 4 s, el ALB da de baja a los dos pods.
Salida
triton parado
Terminal
python mundo/carga.py --tasa 20 --segundos 50
Todas 503.
Salida
975 requests en 50 s (19.5/s) · códigos: 503: 975
Terminal
tail -1 logs/alb.log
El access log del ALB: elb_status_code 503, sin target, con su error_reason.
Salida
{"time":"2026-11-19T06:02:05.182445Z","request":"POST /v1/classify","x_request_id":"8adf8952-4bf0-4645-b34d-d4722de40f4c","trace_id":"Root=1-6afe90dd-3e9db7e6b92aa392e7a6c496","elb_status_code":503,"target":"-","target_status_code":"-","target_processing_time":-1,"request_processing_time":0.0001,"error_reason":"el target group no tiene destinos registrados"}
La regla del gateway: 9.1 %. Son las pocas requests que llegaron al gateway en los segundos antes de que el ALB lo diera de baja (2 revisiones fallidas, cada 2 s).
curl-s localhost:9952/api/v1/alerts |python-c"import json,sys;[print(a['labels']['alertname'], a['state']) for a in json.load(sys.stdin)['data']['alerts']]"
ALB5xx sonando; ClassifierHigh5xxRate, en pending por esas pocas. Cuando su ventana de 1 min las deja atrás, la fracción del gateway se queda sin requests y se apaga, aunque la caída siga.
Salida
ClassifierHigh5xxRate pending
ALB5xx firing
Terminal
python verificar.py de-punta-a-punta
El check sí lo ve: manda una foto por el ALB, como un caller.
Salida
✗ de-punta-a-punta una foto por el ALB da 503 ({"error":"el target group no tiene destinos registrados"}): mira las métricas del ALB (curl localhost:8957/metrics) y su access log (logs/alb.log); el gateway puede no haberla visto nunca
0/1 en verde · falta: de-punta-a-punta
Terminal
python mundo/nodo.py arrancar triton
Salida
✓ triton listo en 0.5 s
Terminal
curl-s localhost:9952/api/v1/alerts |python-c"import json,sys;[print(a['labels']['alertname'], a['state']) for a in json.load(sys.stdin)['data']['alerts']]"
Un minuto después: sin alertas. La ventana de 1 min ya no ve los 503.
No imprime nada.
Terminal
python verificar.py
Al final de la estación: los 12 checks.
Salida
✓ mundo S3, Prometheus, 2 nodos con su pod y su Fluent Bit, Triton, ALB y vigía arriba · una foto por el ALB: 200 (resnet50-2026-11-01)
✓ request-id respeta el id del caller (también en el 415), inventa un UUID v4 si falta y reemplaza los que no son sanos; el id está en el log
✓ linea-log una línea de JSON compacto en stdout (310 B), con request_id, ms y status, sin hora ni foto · nodo-a:/var/log/pods/classifier_gateway-6f7b9c4d58-xa7k2_3f1c9a2e-7b44-4d0e-9a61-5c2b8e0d7a11/gateway/0.log
✓ metricas las 8 métricas del contrato, con sus tipos, etiquetas y bordes
✓ reglas-de-conteo los 4xx cuentan pero no entran a la latencia · source reducido a 4 valores · se_traza ≈ 1 % y determinista
✓ prometheus-lee los 2 pods del gateway, una vez cada uno, con pod, nodo y hash · up = 1
✓ consultas 3 recording rules sanas · errores 0.00% · p99 10.0 ms (resnet50-2026-11-01)
✓ alertas las 5 alertas cargadas, sanas y sin sonar
✓ series-acotadas ≤ 195 series classifier_* por pod (tope 400) · ninguna etiqueta con un valor por request
✓ log-en-s3 los dos nodos suben a S3 (lo último, hace 12 s y menos) · logs/crudo/2026/11/19/06/b-irU3nLvy.gz
✓ parquet dt=2026-11-18 · resnet50-2026-10-01: 7,830 filas · resnet50-2026-11-01: 4,019 filas · cuadra con el crudo
✓ de-punta-a-punta 200 con model_version y X-Request-ID · ALB 5.4 req/s ≈ gateway 5.3 req/s · el ALB no contesta por su cuenta
12/12 en verde
Listo cuando: Con Triton caído, las 975 requests de la carga recibieron 503 del ALB mientras el gateway contaba 0.05 req/s, y ALB5xx sonó. Con Triton de vuelta, python verificar.py: 12 de 12 en verde.
Ojo: Un 4xx también puede ser del ALB: si la llave con que verifica los tokens cambia, contesta 401 a todos sin tocar un pod, y el gateway se ve tranquilo otra vez (la falla «La rotación de llaves»). Antes de confiar en una alerta, pregunta qué requests no cuenta. Y espera ≈ 1 min después de arreglar algo antes de correr verificar.py alertas: las ventanas de 1 min todavía ven el problema.
Concepto de este paso ↓
Lo que el gateway no veblind spot / HTTPCode_ELB_5XX_Count / RequestCount / fail openLas requests que el ALB contesta él mismo (401 por el token, 503 sin destinos registrados) nunca llegan al gateway: sus métricas no las cuentan. Solo las ven las métricas del ALB (en C01, CloudWatch).Analogía, por qué importa y la trampa ↓
AnalogíaEl portero de un restaurante que cierra la puerta cuando la cocina se incendia: el libro de órdenes de la cocina dice «tarde tranquila, cero quejas»; a los que se fueron sin comer solo los contó el portero.
Por qué importaCon Triton caído, los pods fallan su readiness y salen del target group (en C01: salen de los Endpoints y el AWS Load Balancer Controller los da de baja); sin destinos registrados, el ALB contesta 503 y la fracción de 5xx del gateway se queda sin requests. ALB5xx lo ve; como RequestCount solo cuenta las requests para las que el ALB eligió destino, el total suma las dos. Si los destinos siguen registrados pero todos fallan el health check, el ALB de AWS abre el paso (fail open) y les manda tráfico igual.
TrampaConfiar en una tasa de errores calculada en el gateway como si viera todo: ve todo menos el caso en que no llega nada. Antes de confiar en una alerta, pregunta qué requests no cuenta.
Precálculo ↓
9
Si Triton se cae 4 minutos, ¿cuántas requests contesta el ALB con 503, y qué ve el gateway?
requests con 503 del ALB = tasa × segundos caído · fracción del presupuesto = esas requests ÷ las que el mes deja fallar
En C01116 × 240 = 27,840 con 503 del ALB; el presupuesto de errores del mes (99.9 % de ≈ 300 M) deja fallar 300,000: 27,840 ÷ 300,000 ≈ 9.3 % en 4 minutos. El gateway cuenta 027,840 · ≈ 9.3 % del presupuesto del mes
En el dojoel paso 9: 975 requests en 50 s, códigos 503: 975. Prometheus: el ALB contestaba ≈ 20.7 req/s con 503 él mismo mientras el gateway contaba 0.05 req/s≈ 20.7 req/s del ALB contra 0.05 del gateway
Qué decides con esto. Que una alerta sobre las métricas del gateway no basta: hace falta la que mira lo que contesta el propio ALB (ALB5xx; en C01, en CloudWatch). Y que el presupuesto de errores se va rápido: 4 minutos de Triton caído son casi la décima parte del mes.
Empieza con el kit recién descomprimido en una carpeta nueva y python mundo/crear.py. El mundo es uno solo (los mismos puertos y el mismo proyecto de compose): si el de Construir con ayuda sigue prendido en otra carpeta, apágalo allá antes (python mundo/nodo.py parar y docker compose down -v).
Sin GUION.md: solo estos objetivos y el contrato arriba de cada archivo tuyo (gateway/app/rastro.py, observabilidad/prometheus.yml, observabilidad/reglas.yml, observabilidad/fluent-bit.conf y diario/a_parquet.py).
Cada objetivo tiene su check; corre python verificar.py <check> cuando creas que quedó.
Un archivo bien escrito que no se recargó no cuenta: python mundo/recargar.py gateway|prometheus|fluent-bit. Para ver algo con tráfico, python mundo/carga.py --tasa 30 --segundos 60 en otra terminal; Prometheus necesita ≈ 1 min de datos para una tasa de 1 min.
Las reglas de otros equipos no se tocan: mundo/, gateway.yaml, gateway/app/main.py y los nombres de las métricas.
01El S3, Prometheus, los dos nodos con su pod y su Fluent Bit, Triton, el ALB y el vigía arriba, y una foto por el ALB contestada.python verificar.py mundo
02Cada request con un nombre: el X-Request-ID del caller si es sano (también en un 415), uno nuevo si falta o no es sano, en la respuesta y en el log.python verificar.py request-idPista: ¿Qué pasa en el log si un caller manda un id con un salto de línea?
03Una sola línea por request en stdout, en JSON compacto, con request_id, ms y status, sin hora ni foto, y con el X-Client-Source tal como llegó.python verificar.py linea-logPista: ¿Quién pone la hora de cada línea en el disco del nodo?
04Las 8 métricas del contrato en /metrics, con sus nombres, tipos, etiquetas y bordes, y cada categoría desde el arranque.python verificar.py metricas
05Los 4xx cuentan pero no entran a la latencia, la fuente tiene 4 valores venga lo que venga, y ≈ 1 % de las requests deja exemplar, siempre las mismas.python verificar.py reglas-de-conteoPista: ¿Qué le hace al p99 un 415 que tarda microsegundos?
06Prometheus lee los 2 pods del gateway, una vez cada uno, con las etiquetas pod, nodo y hash.python verificar.py prometheus-leePista: ¿Qué pasa si lees a cada pod por los dos Services que lo eligen?
07Las 3 recording rules (requests por segundo, fracción de errores del servidor que da 0 y no vacío, p99 por versión), con la tasa antes de la suma.python verificar.py consultasPista: ¿Qué da una división cuando la serie de arriba no existe?
08Las 5 alertas cargadas y sanas, sin sonar con el mundo sano; una de ellas suena también cuando no hay nada que leer.python verificar.py alertasPista: ¿Cómo suena una alerta sobre una serie que desapareció?
09Las series de cada pod acotadas: ninguna etiqueta con un valor por request.python verificar.py series-acotadas
10Los dos nodos suben su log a S3 cada minuto, con el nombre del nodo en el archivo y en cada registro, sin perder pedazos si S3 se cae un rato.python verificar.py log-en-s3Pista: ¿Cuántas veces reintenta Fluent Bit antes de rendirse, si no le dices nada?
11El día de ayer en Parquet, una carpeta por versión, sin repetidos ni líneas que no son del gateway, y correrlo dos veces da lo mismo.python verificar.py parquetPista: ¿Qué dos registros son de verdad la misma línea?
12Una foto por el ALB contesta 200 con model_version y su X-Request-ID, y lo que el ALB manda a los pods es lo que el gateway cuenta.python verificar.py de-punta-a-punta
Romper
6 fallas
Con todo en verde, romper.py mete una falla en el mundo, la configuración o la infraestructura (nunca en lo que escribiste) y, si hace falta, deja corriendo lo que «pasó anoche». Tú empiezas por verificar.py.
Terminalromper.py
python romper.py --mostrar# con ayuda: Claude sabe cuál espython romper.py # solo: escondida, ni Claude la sabepython romper.py --verificar# ¿ya quedó?python romper.py --revelar# me rindopython romper.py --restaurar# deshacer
Catálogo de fallas (spoilers)El catálogo de abajo trae las respuestas. Ábrelo después de romper, para repasar.Abrir el catálogo
config
Encontrar las lentas
Beto, del equipo de classifier, cerró el BUG-2291: «ya podemos ver en Grafana cuáles requests son las lentas del p99». Hizo merge en la tarde y los pods se reiniciaron con su cambio. Todo contesta 200.
Síntoma. verificar.py: ✗ series-acotadas gateway-6f7b9c4d58-xa7k2: classifier_request_debug_seconds_bucket tiene la etiqueta request_id: un valor por request es una serie por request. Lo que identifica a una request va al log
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Una métrica nueva tiene una etiqueta con un valor por request.
Volvió el caller de la fuente loca y la etiqueta source creció.
Las series vienen de otro lado (Triton, el ALB) y el gateway no tiene nada que ver.
q '…' le pregunta a la API de Prometheus, como la función del paso 4 (aquí imprime las etiquetas a la manera de Python).
Salida
4470
classifier_request_debug_seconds_count{request_id="036be1ac-0d13-4806-9a6c-b2130566687b"} 1.0
classifier_request_debug_seconds_count{request_id="60ab368a-51ec-4354-9b8a-d43bcf540718"} 1.0
{} 8136
{'__name__': 'prometheus_tsdb_head_series', 'job': 'prometheus'} 10636
c404912 Beto (equipo de classifier): gateway: histograma por request para encontrar las lentas del p99 (BUG-2291)
+ from prometheus_client import Histogram # BUG-2291: encontrar las requests lentas del p99 (temporal)
+ depurar = Histogram("classifier_request_debug_seconds", "Latencia por request, para depurar",
+ ["request_id"], registry=registro)
+ depurar.labels(rid).observe(time.monotonic() - t0)
El arreglo. El commit de Beto en gateway/app/main.py agregó un histograma classifier_request_debug_seconds con la etiqueta request_id: cada request crea su propia combinación, 15 series nuevas (11 buckets, +Inf, _sum, _count y _created). Con 20 s de carga, un pod ya exponía 4,470 buckets y Prometheus guardaba 8,136 series de ese histograma. A 5 fotos/s son ≈ 75 series nuevas por segundo; en C01, 150 millones al día: Prometheus se queda sin memoria en horas. Todo contesta 200 y la métrica «funciona»: esa es la trampa. Lo que Beto buscaba ya existe: el exemplar de la latencia (paso 6) y la línea de log. Arreglo: git revert del commit y python mundo/nodo.py reiniciar gateway. Las series viejas se quedan en Prometheus hasta que dejan de recibir muestras; las nuevas ya no nacen.
Plataforma cerró el PLAT-4610: «todas las apps con el prefijo de su servicio, para ordenar el catálogo». Producción contesta normal y nadie reportó nada. Es viernes en la tarde.
Síntoma. verificar.py: ✗ prometheus-lee Prometheus no tiene ningún objetivo con job="gateway": falta el job en observabilidad/prometheus.yml (y curl -X POST localhost:9952/-/reload)
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
Prometheus no puede conectarse a los pods (la red, el puerto).
Cambiaron las etiquetas de los pods y el keep de tu job ya no elige ninguno.
El gateway dejó de exponer /metrics.
Terminalcómo confirmar
python-c"import json;[print(t['targets'], t['labels'].get('__meta_kubernetes_pod_label_app_kubernetes_io_name')) for t in json.load(open('nodo/descubrimiento/pods.json'))]"q'up{job="gateway"}'q'classifier:errores_servidor:ratio_rate1m'curl-s localhost:9952/api/v1/alerts |python-c"import json,sys;a=json.load(sys.stdin)['data']['alerts'];[print(x['labels']['alertname'], x['labels'].get('nodo',''), x['state']) for x in a] or print('(ninguna)')"git log -1 -p--format='%h %an: %s' -- mundo/plataforma.yaml | grep -E '^[0-9a-f]{7}|^[-+][^-+]'
q '…' le pregunta a la API de Prometheus, como la función del paso 4 (aquí imprime las etiquetas a la manera de Python).
Salida
['nodo-a:8080'] classifier-gateway
['nodo-b:8080'] classifier-gateway
['host.docker.internal:8955'] triton
(vacío)
{'__name__': 'classifier:errores_servidor:ratio_rate1m'} 0
GatewaySinLectura pending
e53e7bd Equipo de plataforma: plataforma: nombres de app con el prefijo del servicio (PLAT-4610)
- app.kubernetes.io/name: gateway
+ app.kubernetes.io/name: classifier-gateway
- app.kubernetes.io/name: gateway
+ app.kubernetes.io/name: classifier-gateway
El arreglo. El commit de plataforma en mundo/plataforma.yaml cambió la etiqueta de los pods del gateway de app.kubernetes.io/name: gateway a classifier-gateway. Tu job elige los pods con un keep sobre esa etiqueta: ya no elige ninguno. Nada truena: el gateway contesta, Prometheus no se queja (no hay objetivo que falle), y las alertas que dependen de classifier_* evalúan sobre nada y no suenan. Solo GatewaySinLectura lo ve, porque mira up con absent. Arreglo: git revert del commit y python mundo/nodo.py publicar. Aceptar el nombre nuevo en tu prometheus.yml también arregla, pero el arreglo de fondo es acordar el cambio antes: esa etiqueta era un contrato entre dos equipos.
El arreglo. El S3 del mundo (RustFS) está apagado. El gateway no se entera: escribe en stdout y sigue; el runtime guarda en el disco del nodo, y cada Fluent Bit junta lo que no puede subir en su buffer en disco (store_dir) y lo reintenta. Se degrada el monitoreo, no el servicio: ninguna request falló, y de-punta-a-punta sigue en verde. Arreglo: docker compose start s3; en segundos los Fluent Bit suben lo atrasado. No se pierde ninguna línea mientras el buffer aguante y mientras Fluent Bit no se rinda: con el retry_limit por omisión, a los 6 intentos (≈ 30 s) el pedazo se va a cuarentena y esas líneas no llegan a S3. Por eso tu fluent-bit.conf lleva retry_limit 60.
LogsStale avisa, pero solo para un nodo. El otro sube normal. Producción contesta bien.
Síntoma. verificar.py: ✗ log-en-s3 el Fluent Bit del nodo b no contesta (docker compose ps)
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
S3 se cayó.
El Fluent Bit del nodo b no corre.
El pod del nodo b dejó de escribir su log.
Terminalcómo confirmar
docker compose ps --all--format'{{.Service}} {{.State}}'curl-s localhost:9952/api/v1/alerts |python-c"import json,sys;a=json.load(sys.stdin)['data']['alerts'];[print(x['labels']['alertname'], x['labels'].get('nodo',''), x['state']) for x in a] or print('(ninguna)')"q'time() - dojo_s3_ultimo_objeto_timestamp_seconds'
q '…' le pregunta a la API de Prometheus, como la función del paso 4 (aquí imprime las etiquetas a la manera de Python).
El arreglo. El Fluent Bit del nodo b está apagado (en C01: el pod del DaemonSet de ese nodo no corre por un taint, un OOMKilled o un nodo nuevo donde no cupo). El otro nodo sube normal: por eso LogsStale va por nodo. Las líneas del pod del nodo b se quedan en el disco del nodo y, mientras el kubelet no las rote (5 archivos de 10 MiB), no se pierden. Arreglo: docker compose start fluent-bit-b; al volver, Fluent Bit sigue donde se quedó (su DB) y en ≈ 1 min sube lo atrasado.
Soporte escribe: «los vendedores dicen que no salen las sugerencias». Abres el tablero del gateway: la tasa de 5xx está en cero y el p99 se ve bien. ¿Qué pasa?
Síntoma. verificar.py: ✗ mundo Triton no está listo: python mundo/nodo.py estado
✗ de-punta-a-punta una foto por el ALB da 503 ({"error":"el target group no tiene destinos registrados"}): mira las métricas del ALB (curl localhost:8957/metrics) y su access log (logs/alb.log); el gateway puede no haberla visto nunca
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
El gateway está bien y el problema es del backend.
Los pods no están listos y el ALB contesta él mismo.
El token de los callers dejó de servir.
Terminalcómo confirmar
q'sum(rate(classifier_requests_total[1m]))'q'classifier:errores_servidor:ratio_rate1m'curl-s localhost:8957/metrics |grep-E'^alb_(httpcode_elb_total\{code="503"\}|healthy_host_count)'tail -1 logs/alb.log
curl-s localhost:9952/api/v1/alerts |python-c"import json,sys;a=json.load(sys.stdin)['data']['alerts'];[print(x['labels']['alertname'], x['labels'].get('nodo',''), x['state']) for x in a] or print('(ninguna)')"python mundo/nodo.py estado
q '…' le pregunta a la API de Prometheus, como la función del paso 4 (aquí imprime las etiquetas a la manera de Python).
El arreglo. Triton está apagado. Los dos pods del gateway contestan 503 en /readyz, salen del target group (en C01: salen de los Endpoints y el AWS Load Balancer Controller los da de baja) y el ALB, sin destinos registrados, contesta 503 él mismo: las requests nunca llegan a un pod. classifier_requests_total casi no sube, la fracción de 5xx del gateway no tiene requests (o queda en 0) y ClassifierHigh5xxRate no suena. Solo lo ven las métricas del ALB (alb_httpcode_elb_total{code="503"} y alb_healthy_host_count en 0) y la alerta ALB5xx. Arreglo: python mundo/nodo.py arrancar triton; en ≈ 1 min la ventana de las tasas ya no ve los 503 y ALB5xx se apaga.
Seguridad cerró el SEC-118: «rotamos la llave con que el ALB verifica los tokens, como cada trimestre». Diez minutos después, el backend de publicaciones dice que el clasificador «está caído».
Síntoma. verificar.py: ✗ mundo una foto por el ALB da 401: {"error":"token ausente o inválido (firma, emisor, audiencia o caducidad)"}
✗ de-punta-a-punta una foto por el ALB da 401 ({"error":"token ausente o inválido (firma, emisor, audiencia o caducidad)"}): mira las métricas del ALB (curl localhost:8957/metrics) y su access log (logs/alb.log); el gateway puede no haberla visto nunca
Hipótesis, cómo confirmar y el arreglo ↓
Hipótesis para descartar
El gateway truena con las requests del backend.
El ALB rechaza los tokens y contesta 401 él mismo.
alb_httpcode_elb_total{code="401"} 97.0
{"time":"2026-11-19T06:14:36.670323Z","request":"POST /v1/classify","x_request_id":"b8a0310e-9dd8-4a9c-aea8-731a59e8b8f7","trace_id":"Root=1-6afe93cc-1a8445061c43c27aee9243cf","elb_status_code":401,"target":"-","target_status_code":"-","target_processing_time":-1,"request_processing_time":0.0,"error_reason":"token ausente o inválido (firma, emisor, audiencia o caducidad)"}
ce95daa Equipo de plataforma: plataforma: rota la llave con que el ALB verifica los tokens (SEC-118)
- llave: acbb9f8b6aaf6329216ce3e455202bf5
+ llave: d282aa9c9bc026cc627414055decf816
El arreglo. El commit de plataforma cambió alb.jwt.llave en mundo/plataforma.yaml, pero el proveedor de identidad sigue firmando con la anterior (mundo/callers.json): toda firma falla y el ALB contesta 401 él mismo. Los pods están sanos, el gateway no recibe nada y sus métricas se ven tranquilas; los 401 solo están en el ALB. Un 4xx no es culpa de Alba… salvo cuando lo pone su propia puerta. Arreglo: git revert del commit y python mundo/nodo.py reiniciar alb; en ≈ 1 min la ventana de las tasas ya no ve los 401. En C01, la rotación se hace publicando la llave nueva junto a la vieja (JWKS) antes de firmar con ella.
Nombrar, escribir, sumar, leer, llevar y mirar lo que no se ve.Cada request recibe un nombre (el request_id del caller si es sano, o un UUID v4) que viaja en la respuesta, en la línea y en el exemplar. Escribe una línea de JSON compacto en stdout, sin hora: el runtime la guarda con la suya. Suma en contadores e histogramas con nombres fijos y etiquetas de pocos valores. Prometheus lee cada pod una sola vez, guarda las preguntas de todos los días como recording rules con sum(rate(…)) y evalúa alertas con su for. Fluent Bit lleva el log a S3 cada minuto, con un buffer que aguanta si S3 se cae, y al día siguiente queda en Parquet, sin repetidos y por versión. Y alguien mira lo que el gateway no ve: el ALB contestando él mismo.Trampa: Un id como etiqueta de una métrica (una serie por request); rate(sum(…)) en lugar de sum(rate(…)); un log que espera a la red; o creer que una tasa de errores calculada en el gateway ve las requests que nunca le llegaron.Listo cuando
Cada request lleva su request_id de punta a punta: el del caller si es sano, uno nuevo si no; en la respuesta, en la línea y, en ≈ 1 %, como exemplar.
Cada request deja una sola línea de JSON compacto en stdout, sin hora, que el runtime guarda en el disco de su nodo.
Las 8 métricas del contrato suman lo que deben: los 4xx cuentan pero no entran a la latencia, y ninguna etiqueta tiene un valor por request.
Prometheus lee cada pod una sola vez, con pod, nodo y hash, y tiene 3 recording rules y 5 alertas sanas.
Fluent Bit sube el log de cada nodo a S3 cada minuto; con S3 caído, la request no se enteró y nada se fue a cuarentena.
El crudo de ayer está en Parquet por versión, sin repetidos, y correr el job dos veces da lo mismo.
Viste lo que el gateway no ve: con Triton caído, solo el ALB y ALB5xx contaron los 503.
Así te lo pueden preguntar en una entrevista
¿Qué dejas escrito de cada request de un modelo en producción, y dónde?
Tres rastros unidos por el mismo request_id. Una línea de log estructurada por request (id, caller, versión del modelo, top-k con scores, tiempos por tramo, status), en stdout, que un agente por nodo sube a un almacén de objetos y un job diario pasa a Parquet: de ahí salen el drift, la aceptación y las etiquetas del mes. Métricas: contadores e histogramas con etiquetas de pocos valores, leídas por Prometheus, para las alertas. Y trazas o exemplars en ≈ 1 %, para pasar de una curva a una request concreta. Ninguno puede frenar la respuesta.
¿Por qué no pones el request_id o el user_id como etiqueta de una métrica?
Porque cada combinación de etiquetas es una serie, y un valor por request es una serie por request: en un histograma de 11 bordes son 15 series nuevas por request, 150 millones al día con 10 M requests, y Prometheus se queda sin memoria. Las etiquetas solo llevan listas cortas y cerradas (código, versión, una fuente reducida a 4 valores); lo que identifica a una request va al log, y del agregado se llega a una request con exemplars.
Se cae tu almacén de logs (S3, Elasticsearch). ¿Qué le pasa al usuario?
Nada: el servicio escribe en stdout y sigue, el runtime guarda en el disco del nodo y el agente (Fluent Bit) junta en un buffer en disco y reintenta. Se degrada el monitoreo, no el servicio. Lo que cuidas es no perder en silencio: un buffer con tamaño calculado (en C01, ≈ 16 h), reintentos suficientes (con los de por omisión, el plugin s3 de Fluent Bit se rinde en ≈ 30 s) y una alerta de frescura por nodo (LogsStale).
¿Cómo calculas la tasa de errores y el p99 de un servicio con varios pods en Prometheus?
Errores: sum(rate(requests{code=~"5.."}[5m])) dividido entre sum(rate(requests{code!~"4.."}[5m])), con or vector(0) arriba para que sin errores dé 0 y no vacío; los 4xx fuera porque son culpa del caller. p99: histogram_quantile(0.99, sum by (le) (rate(latency_bucket[5m]))), sumando los buckets de todos los pods. Siempre la tasa antes de la suma: rate(sum(…)) convierte el reinicio de un pod en un pico falso. Y las dos como recording rules.
La tasa de 5xx del servicio está en cero y soporte dice que no funciona. ¿Qué revisas?
Qué requests no cuenta esa tasa. Primero, si Prometheus está leyendo los pods (up, una alerta con absent): una etiqueta cambiada deja al job sin objetivos y todo se ve en cero. Después, el balanceador: si los pods salieron del target group (por ejemplo, porque su dependencia cayó y fallan la readiness), el ALB contesta 503 él mismo y el servicio no ve nada; o un 401 por una llave rotada. Eso solo está en las métricas del ALB (HTTPCode_ELB_5XX_Count en CloudWatch) y en su access log.
El p99 subió a las 14:05. ¿Cómo llegas de esa curva a una request concreta?
Con exemplars: el histograma de latencia guarda, junto a algunos buckets, el id de una request trazada que cayó ahí; Grafana los dibuja sobre la curva y abres su traza o, con el request_id, su línea de log. Ojo: el muestreo decide al principio (≈ 1 % por el hash del id), así que pocas lentas tienen exemplar; para estudiar todas las lentas, el log del día (filtrar por ms.total y buscar qué tienen en común) o tail sampling.
Versión del contenido: 18 de noviembre de 2026.
Contexto opcional
para consultar
Dónde estás en el pipeline
La estación 10 dejó la release 15 al 100 %, pero así como viene el gateway contesta y olvida. Aquí cada request recibe un nombre (su request_id, de punta a punta), deja una línea de log de ≈ 300 B en stdout y suma en las métricas: contadores, un gauge e histogramas con nombres que no cambian. Prometheus lee cada pod una sola vez, guarda las consultas de todos los días y evalúa las alertas; Fluent Bit lleva el log del disco de cada nodo a S3 cada minuto, y un job diario lo pasa a Parquet. Al final miras lo que el gateway no ve: el ALB contestando él mismo.
Entra
la release 15 (resnet50-2026-11-01) al 100 %: dos pods del gateway, uno en cada nodo, y su Triton, detrás del ALB
un gateway que contesta bien pero no deja rastro: gateway/app/rastro.py no guarda el id, no escribe ninguna línea y no suma nada
Prometheus, Fluent Bit y el S3 corriendo, todavía sin configurar para el gateway, y el log de ayer ya subido
las reglas de otros equipos: los nombres de las métricas (estaciones 6 y 10), las etiquetas de los pods y el ALB
→11→
Sale
cada request con su request_id en la respuesta, en su línea de log y, en ≈ 1 %, como exemplar en la latencia
una línea de JSON compacto por request en el disco del nodo, en S3 cada minuto y en Parquet al día siguiente, partido por versión
las 8 métricas del contrato, leídas por Prometheus una vez por pod, con 3 recording rules y 5 alertas
la prueba de que el monitoreo tiene puntos ciegos: con Triton caído, el gateway no ve nada y solo el ALB lo cuenta
El escenario del proyecto
Con kit · 4 rondas
El kit trae la release 15 de C01 corriendo en chico, de verdad: dos nodos del gateway (contenedores de Docker con un pod cada uno y su runtime, que escribe el stdout del pod en el disco del nodo), un Fluent Bit 5.1.5 por nodo, RustFS como S3, Prometheus v3.15.1 con exemplars, el Triton del dojo, el ALB del dojo (token, target group y sus métricas «de CloudWatch»), el vigía de S3, el tráfico de siempre y el log de ayer ya subido. Lo tuyo: el rastro de cada request, lo que lee Prometheus, sus reglas y alertas, el camino del log a S3 y el job diario a Parquet.
mundo/crear.py levanta compose.yaml (RustFS como S3, Prometheus y los contenedores nodo-a y nodo-b, cada uno con su Fluent Bit), deja en S3 el log de ayer para tu job diario y arranca con mundo/nodo.py lo que corre en tu Mac: Triton, los dos pods del gateway (uno dentro de cada nodo), el ALB del dojo, el vigía de S3 y el tráfico de siempre, 5 fotos por segundo de tres callers. También vuelve la carpeta un repositorio de git: los cambios de otros equipos llegan como commits.
Glosario: los 18 conceptos
Una línea para entenderlo; abre la tarjeta para la analogía, por qué importa y la trampa.
Observabilidad: los tres rastrosobservability / metrics, logs, tracesPoder entender qué pasa adentro de un servicio mirando lo que deja escrito: métricas (sumas: ¿cuánto?), logs (una línea por request: ¿qué pasó con esta?) y trazas o exemplars (¿dónde se fue el tiempo?).Analogía, por qué importa y la trampa ↓
AnalogíaEl tablero, la bitácora y la cámara de un auto. El tablero (métricas) avisa que el motor se calienta; la bitácora (log) dice en qué viajes pasó; el video de un viaje (traza) muestra en qué subida. Video solo se graba de unos cuantos viajes: son caros.
Por qué importaCada rastro contesta una pregunta distinta y se usan en orden: la métrica avisa («el p99 subió a las 14:05»), el exemplar lleva a una request de ejemplo y el log dice cuántas se parecen y qué tienen en común. Los une el request_id. Para un modelo hay algo más: un 200 con una sugerencia mala no se ve en ninguna métrica de servicio, solo en el log, uniendo cada predicción con lo que eligió la persona. Por eso C01 guarda el log del 100 % de las requests.
TrampaCreer que con métricas basta. Las métricas no recuerdan ninguna request: con ellas sabes que algo va mal, no a quién le pasó ni qué contestó el modelo.
request_id de punta a puntarequest ID / correlation ID / X-Request-ID / UUID v4El nombre único de cada request: el X-Request-ID del caller si es sano, o un UUID versión 4 nuevo. Vuelve en la respuesta y va en el log y en el exemplar: es la llave para unir lo que dejó en cada lugar.Analogía, por qué importa y la trampa ↓
AnalogíaEl número de guía de un paquete: el remitente, la bodega y el repartidor anotan cosas distintas en sus propias libretas, pero con el mismo número cualquiera junta la historia completa sin saber en qué camión viajó.
Por qué importaSin él, unir el log del backend, el access log del ALB y la línea del gateway sería adivinar por la hora, y con 116 fotos por segundo eso falla. Respetar el id del caller hace que backend y gateway llamen igual a la misma request. Un UUID v4 son 122 bits al azar: dos pods inventan ids al mismo tiempo sin chocar y sin preguntarle a nadie.
TrampaCopiar cualquier X-Request-ID que llegue: uno de 80 caracteres o con un salto de línea ensucia el log (o lo parte en dos). Y ponerlo como etiqueta de una métrica: una serie nueva por request.
La línea de log: JSON Lines en stdoutstructured logging / JSON Lines / stdout / CRI log formatUna línea de JSON compacto por request, escrita en la salida estándar (stdout) y sin hora. El runtime del nodo la guarda en un archivo con su hora, en formato CRI, y rota el archivo cuando crece.Analogía, por qué importa y la trampa ↓
AnalogíaDictarle a una secretaria: dices una frase por caso y sigues con lo tuyo; ella la anota en el cuaderno con la hora del reloj de la pared y, cuando el cuaderno se llena, empieza otro y tira el más viejo.
Por qué importaEl gateway no abre archivos, no conoce S3 y no espera a nadie: escribir en stdout termina en microsegundos, así que el log nunca frena la request. Una línea por request, con request_id, caller, source, model_version, top5, ms, bytes, sha256 y status: ≈ 300 B, lo que lee el job del día siguiente. La hora la pone uno solo, el runtime, en UTC con nanosegundos: en el disco del nodo queda «<hora> stdout F <tu línea>», en 5 archivos de 10 MiB por contenedor.
TrampaPoner la hora en la línea (dos relojes en el mismo registro), escribir con espacios (≈ 10 % más bytes, pagados 10 millones de veces al día) o escribir directo a S3 desde la request: una lentitud de S3 se vuelve lentitud para el usuario.
Tres relojesserver-side latency / TargetResponseTime / client-side latencyLa misma request mide distinto según quién mida: el gateway (desde que su código la recibe hasta que contesta), el ALB (TargetResponseTime) y el backend (todo lo que esperó). Cada reloj contiene al anterior.Analogía, por qué importa y la trampa ↓
AnalogíaUna pizza a domicilio: la cocina cuenta desde que entra la orden hasta que sale la caja; el repartidor, desde que la recoge hasta que toca el timbre; tú, desde que colgaste el teléfono. Los tres tienen razón y ninguno es «el tiempo de la pizza».
Por qué importaEl SLO de C01 (p99 ≤ 200 ms) se mide del lado del servidor, con el reloj del gateway; el backend vive con su timeout de 300 ms. TargetResponseTime va desde que la request sale del ALB hasta que el pod empieza a mandar los headers de la respuesta. Si el backend se queja de 280 ms y el gateway dice 20, el tiempo se fue fuera del gateway: en el ALB, en la red o en el backend.
TrampaComparar un número de un reloj con el de otro como si fueran lo mismo, o unir los relojes por la hora en lugar de por request_id.
Contador y gaugecounter / gaugeUn contador empieza en 0 y solo sube (las requests con 200): lo útil es cuánto subió en un rato. Un gauge sube y baja, y su valor sí dice algo en cada momento (las requests en vuelo ahora).Analogía, por qué importa y la trampa ↓
AnalogíaEl odómetro y el velocímetro de un auto: el odómetro solo sube y lo útil es cuántos km hiciste hoy (una resta); el velocímetro sube y baja y lo que importa es lo que marca ahora.
Por qué importaclassifier_requests_total{code, source, model_version} es el contador del que salen las requests por segundo y la fracción de errores; classifier_requests_in_flight es el gauge (de 0 a 16, el tope del gateway). Si el proceso se reinicia, el contador vuelve a 0: no es un error, es la regla, y quien lo lee entiende que un contador que baja se reinició. Las métricas viven en la memoria del pod; el gateway las expone en GET /metrics y alguien las lee.
TrampaLeer el valor de un contador como si dijera algo («lleva 957,980»): solo dice cuánto contó desde que arrancó. O usar un gauge para «las requests del último minuto»: no se suma bien entre pods y no sobrevive a un reinicio.
Histograma y bucketshistogram / buckets / le / histogram_quantileUn grupo de contadores, uno por bucket: cada observación suma 1 a los buckets cuyo borde (le, «menor o igual») es mayor o igual a su valor, más _count y _sum. De ahí sale el p99 sin guardar cada número.Analogía, por qué importa y la trampa ↓
AnalogíaUna fila de cubetas con letreros «hasta 5 ms», «hasta 10 ms», «hasta 20 ms»…: cada request echa una canica en cada cubeta cuyo letrero le queda grande. Contando canicas sabes debajo de qué tiempo cayó el 99 %.
Por qué importaLos bordes se eligen alrededor de lo que importa: los de la latencia alrededor del SLO (0.15, 0.2 y 0.25 s), los del score con uno en 0.3, el umbral de baja confianza. Como son contadores, los de varios pods se suman antes de estimar el percentil con histogram_quantile. Cada combinación de etiquetas cuesta bordes + 4 series: +Inf, _count, _sum y _created.
TrampaUn promedio o un percentil calculado en cada pod: el p99 de todo el gateway no es el promedio de los p99 de cada pod (y el Summary de prometheus_client ni siquiera calcula cuantiles). Y meter los 4xx a la latencia: un 415 tarda microsegundos y baja el p99 sin que nadie conteste más rápido.
Cardinalidadcardinality / label values / high-cardinality labelsCuántas series deja una métrica: una por cada combinación distinta de valores de sus etiquetas. Cada serie le cuesta a Prometheus memoria, un lugar en su índice y una muestra en cada lectura.Analogía, por qué importa y la trampa ↓
AnalogíaLos cajones de un archivero, uno por combinación de etiquetas: con «tipo de documento» y «año» son unos cuantos; si agregas «número de folio», necesitas un cajón por hoja y el archivero ya no cabe en el cuarto.
Por qué importaSolo pueden ser etiquetas los datos con una lista corta y conocida de valores: code, source reducida a 4, model_version. Lo que identifica a una request (su id, el sha256 de la foto) va al log. En C01, el request_id en la latencia serían 15 series nuevas por request: 150 millones al día, y Prometheus se queda sin memoria en horas.
TrampaCopiar un header a una etiqueta tal como llega (un caller con un bug manda un texto distinto en cada request), o creer que no pasa nada porque todo contesta 200: el costo aparece en Prometheus, horas después.
Scrape: Prometheus jalascrape / pull model / upPrometheus le pide /metrics a cada objetivo cada cierto tiempo (5 s en el dojo, 15 s en C01) y guarda cada número con la hora. Por cada objetivo guarda también up: 1 si la lectura salió bien, 0 si no.Analogía, por qué importa y la trampa ↓
AnalogíaEl que lee los medidores de luz: pasa por cada casa y anota lo que marca; si una casa no le abre, lo anota. Si las casas mandaran su lectura por correo, una casa sin luz simplemente no mandaría nada, y su silencio se parecería a «todo bien».
Por qué importaJalar en vez de recibir hace que un pod muerto se note: su up baja a 0. Cada serie junta una muestra por lectura: 86,400 ÷ 15 = 5,760 al día en C01. Lo primero que se revisa después de un cambio de monitoreo es que up exista y valga 1 para cada pod.
TrampaPensar que si Prometheus no se queja, está leyendo todo: si un pod no está en su lista, no hay ningún up de ese pod que baje. Nada truena; simplemente no lo lee.
Descubrimiento y relabel: pods, no Servicesservice discovery / relabel_configs / PodMonitor vs. ServiceMonitorPrometheus no lleva una lista fija de pods: los descubre (en C01, de la API de Kubernetes; en el dojo, de pods.json) y con relabel_configs se queda con los que quiere y les pone etiquetas.Analogía, por qué importa y la trampa ↓
AnalogíaUn cartero con el padrón del edificio: no se aprende los nombres, lee el padrón cada día y reparte según lo que dice. Si repartiera por el buzón de cada empresa y dos empresas comparten oficina, esa oficina recibiría todo dos veces.
Por qué importaEn C01 lo arma kube-prometheus-stack con un PodMonitor, que elige pods por sus etiquetas. Fuera de un canary, gateway-stable y gateway-canary eligen los mismos pods: un ServiceMonitor los leería por los dos Services, con la etiqueta service, y cada suma saldría al doble. Las etiquetas que empiezan con __ se tiran después del relabel: lo que quieras guardar (pod, nodo, hash) lo copias antes.
TrampaLeer por los Services, o creer que no pasa porque al probar sin la etiqueta service salía bien: Prometheus descarta objetivos repetidos con las mismas etiquetas, y la cuenta doble aparece con service. Y un keep sobre una etiqueta que otro equipo puede renombrar sin avisar.
PromQL: rate, y luego sumPromQL / rate() / sum by / counter resetsrate(contador[1m]) da cuánto subió por segundo en el último minuto, leyendo cualquier bajada como un reinicio; sum by (…) suma series y deja separadas las etiquetas que nombras. Siempre sum(rate(…)).Analogía, por qué importa y la trampa ↓
AnalogíaMedir el ritmo de un grupo de corredores con podómetros que a veces se reinician: sacas los pasos por minuto de cada uno (si su podómetro marca menos, se reinició) y luego sumas. Si primero sumas los podómetros y uno se reinicia, el total baja y parece que todos se reiniciaron a la vez.
Por qué importaEs la base de todas las tasas: requests por segundo, la fracción de errores del servidor (5xx sobre lo que no es 4xx) y el p99 (histogram_quantile sobre sum by (le) de las tasas de los buckets). Con lecturas cada 5 s, una ventana de 1 min junta 12 muestras; con 15 s, C01 usa 5 min.
Tramparate(sum(…)): cuando un pod se reinicia, la suma baja, rate() la lee como un reinicio de todo y cuenta la suma entera otra vez: un pico falso. Y dividir los 5xx entre todas las requests: un caller que manda basura (4xx) baja tu tasa de errores.
Recording rulerecording rule / level:metric:operationsUna consulta que Prometheus hace solo cada pocos segundos y guarda como una serie nueva con nombre (nivel:métrica:operación). El tablero y las alertas leen ese nombre en lugar de repetir la cuenta.Analogía, por qué importa y la trampa ↓
AnalogíaEl corte de caja de una tienda cada hora: en lugar de que cada gerente sume los tickets cuando quiere saber cuánto se vendió, alguien hace la suma a la hora y la anota en una hoja con nombre.
Por qué importaLas preguntas de todos los días (requests por segundo por código, fracción de errores del servidor, p99 por versión) quedan calculadas igual para todos, y las alertas se escriben sobre ellas. En el dojo se evalúan cada 5 s, con ventanas de 1 min.
TrampaUna división sin numerador da vacío, no 0: sin ningún 5xx, la serie de 5xx no existe y la fracción desaparece del tablero. Por eso el or vector(0). Y un rate(sum(…)) dentro de una regla esconde el error detrás de un nombre bonito.
Alertas: for, pending y absentalerting rule / for / pending / firing / absent()Una regla que avisa si su condición se cumple durante un tiempo (for): mientras no lo cumple está pending; después, firing. absent() da una serie cuando no hay ninguna: así también suena lo que se calla.Analogía, por qué importa y la trampa ↓
AnalogíaUna alarma de humo con espera: un cerillo no la dispara; el humo que sigue 30 segundos, sí. Y otra alarma que suena si la de humo se quedó sin pila: la más peligrosa es la que no suena porque no tiene nada que medir.
Por qué importaLas 5 de la estación: ClassifierHigh5xxRate (más de 1 % por 1 min), ClassifierP99Alto (más de 200 ms por 2 min), GatewaySinLectura (Prometheus no lee los 2 pods, con absent), LogsStale (un nodo lleva 3 min sin subir a S3; C01: 30 min) y ALB5xx (los 5xx que pone el ALB). El for evita despertar a alguien por un pico de un instante.
TrampaAlertas que dependen de series que pueden desaparecer: si tu job pierde los pods, la de 5xx evalúa sobre nada y no suena, justo cuando no ves nada. Por eso GatewaySinLectura mira up con absent.
Exemplarexemplar / trace_id / OpenMetrics / head samplingUn id pegado a una observación de un histograma: «una de las que cayeron en este bucket es la request tal». En el dojo, el request_id de ≈ 1 % de las requests, elegidas por el hash del id.Analogía, por qué importa y la trampa ↓
AnalogíaUn post-it en una caja de la bodega: la etiqueta dice «150 paquetes de 10 a 20 kg»; el post-it dice «uno de ellos es el folio 5a1e07c3», para que puedas abrir uno y ver cómo viene.
Por qué importaUne la métrica con una request concreta: ves el p99 subir, tocas un punto y llegas al id (en C01, a su traza; en el dojo, con mundo/buscar.py, a su línea). Dos condiciones: prometheus_client solo los escribe en el formato OpenMetrics, que Prometheus 3 pide al leer, y Prometheus solo los guarda con --enable-feature=exemplar-storage, que viene apagado.
TrampaEsperar que el exemplar sea una de las lentas: el muestreo decide al principio (head sampling), sin saber cuánto va a tardar, y cada bucket lleva a lo más uno (el último) entre dos lecturas. Para guardar todas las lentas hay que decidir al final (tail sampling).
Fluent Bit en cada nodoFluent Bit / tail input / DaemonSetUn programa chico que corre en cada nodo, sigue los archivos de log mientras crecen (tail, con el parser cri), anota hasta dónde leyó (su DB) y sube lo que junta a S3. En C01, un DaemonSet: un pod por nodo.Analogía, por qué importa y la trampa ↓
AnalogíaEl mensajero de cada piso de un edificio: pasa por las bandejas de su piso, se lleva lo nuevo, anota en su libreta hasta qué hoja recogió y lo manda al archivo central. Con un mensajero por piso, ningún piso se queda sin recoger, ni siquiera uno nuevo.
Por qué importaEl gateway no conoce S3: Fluent Bit hace el camino. Con un Deployment de 3 réplicas, dos nodos podrían quedarse sin quien lea sus logs; el DaemonSet pone uno en cada nodo, también en los que lleguen. Si se cae, las líneas esperan en el disco del nodo y, al volver, sigue donde se quedó gracias a su DB, mientras el kubelet no haya rotado esos archivos.
TrampaPensar que si Fluent Bit se cae no pasa nada porque el gateway sigue contestando: el log de ese nodo se atrasa y, si tarda más que la rotación (5 archivos de 10 MiB), esas líneas se pierden. Lo avisa LogsStale, por nodo.
Buffer en disco y reintentosstore_dir / retry_limit / quarantine / never block the requestLo que Fluent Bit no pudo subir lo guarda en el disco del nodo (store_dir, con su tope) y lo reintenta. Nunca frena la request: si S3 se cae, se atrasa el monitoreo, no el servicio.Analogía, por qué importa y la trampa ↓
AnalogíaLa bandeja de salida de una oficina cuando el correo no pasa: las cartas se juntan ahí y se mandan cuando vuelve el cartero. Si la bandeja se llena, o si alguien se cansa de esperar y tira las cartas viejas, esas se pierden.
Por qué importaEn C01, 1 GB por nodo aguanta ≈ 16 h de S3 caído. El otro tope son los reintentos: con el retry_limit por omisión, el plugin s3 de Fluent Bit 5.1.5 se rinde a los 6 intentos (≈ 30 s) y manda el pedazo a cuarentena: esas líneas no llegan nunca. Por eso la solución usa retry_limit 60 y verificar.py reprueba si hubo cuarentena.
TrampaFiarse de las métricas de reintentos del motor: en la construcción del dojo, fluentbit_output_retries_failed_total siguió en 0 mientras se perdían pedazos. Y un log que espera a que S3 confirme: cualquier lentitud de S3 se vuelve lentitud para todos.
Entrega al menos una vezat-least-once delivery / deduplicationFluent Bit garantiza que cada línea llegue, no que llegue una sola vez: si una subida falla después de que S3 sí la guardó, la reintenta y el mismo archivo llega dos veces. Quien lee quita los repetidos.Analogía, por qué importa y la trampa ↓
AnalogíaMandar una carta importante y, como no llegó el acuse, mandarla otra vez: la otra persona puede recibir dos, y por eso numeras tus cartas, para que tire la repetida.
Por qué importaEl log de ayer del dojo trae dos archivos subidos dos veces. Sin quitarlos, el join del mes contaría esas fotos dos veces. La llave es (request_id, time): el mismo id con otra hora es otra request de verdad (un caller que reintenta con el mismo X-Request-ID), y esa se queda.
TrampaQuitar repetidos solo por request_id: borra los reintentos legítimos del caller. O creer que «exactamente una vez» viene gratis: casi ningún camino de logs lo promete.
Parquet por fecha y versiónParquet / partitioning / dt= / idempotent jobParquet guarda una tabla por columnas, comprimida y con el tipo de cada columna. Partida en carpetas (dt=AAAA-MM-DD/model_version=…/), una consulta de un día y una versión solo lee esa carpeta.Analogía, por qué importa y la trampa ↓
AnalogíaUn archivero con un cajón por día y una carpeta por versión adentro: para ver cómo le fue a la versión 15 el martes, abres un cajón y una carpeta, no el archivero entero.
Por qué importaEl crudo de C01 son ≈ 3 GB de JSON al día; en Parquet, ≈ 0.5 GB en 4 archivos. De ahí leen el PSI diario, la aceptación y las fotos para etiquetar de la estación 12. El job es idempotente: borra lo de ese día y lo vuelve a escribir, así que correrlo dos veces (un reintento del orquestador) da lo mismo.
TrampaUn job que agrega en lugar de reemplazar: el reintento duplica el día. Y filtrar el día con la hora local: el crudo y la carpeta están en UTC, y en las fronteras del día se pierden o se duplican filas.
Lo que el gateway no veblind spot / HTTPCode_ELB_5XX_Count / RequestCount / fail openLas requests que el ALB contesta él mismo (401 por el token, 503 sin destinos registrados) nunca llegan al gateway: sus métricas no las cuentan. Solo las ven las métricas del ALB (en C01, CloudWatch).Analogía, por qué importa y la trampa ↓
AnalogíaEl portero de un restaurante que cierra la puerta cuando la cocina se incendia: el libro de órdenes de la cocina dice «tarde tranquila, cero quejas»; a los que se fueron sin comer solo los contó el portero.
Por qué importaCon Triton caído, los pods fallan su readiness y salen del target group (en C01: salen de los Endpoints y el AWS Load Balancer Controller los da de baja); sin destinos registrados, el ALB contesta 503 y la fracción de 5xx del gateway se queda sin requests. ALB5xx lo ve; como RequestCount solo cuenta las requests para las que el ALB eligió destino, el total suma las dos. Si los destinos siguen registrados pero todos fallan el health check, el ALB de AWS abre el paso (fail open) y les manda tráfico igual.
TrampaConfiar en una tasa de errores calculada en el gateway como si viera todo: ve todo menos el caso en que no llega nada. Antes de confiar en una alerta, pregunta qué requests no cuenta.
Nube real vs. local
En C01
En el dojo
El tráfico
≈ 10 M requests al día: ≈ 116 por segundo en promedio, ≈ 350 en el pico
5 fotos por segundo de siempre (los tres callers) y la carga que mandes con mundo/carga.py
Pods y nodos
de 3 a 12 pods del gateway en nodos de EKS, en dos zonas
2 pods, uno en cada nodo: dos contenedores de Docker (nodo-a, nodo-b) con su runtime
El log
≈ 300 B por request: ≈ 3 GB al día, 90 días en S3 (≈ 270 GB, ≈ US$6 al mes)
310 B por request; el log de ayer: 11,849 requests en 578 archivos
Quién lo sube
Fluent Bit como DaemonSet: sube cada 5 min, con 1 GB de buffer por nodo
un Fluent Bit 5.1.5 por nodo: sube cada minuto, con 256 MB de buffer y retry_limit 60
Prometheus
kube-prometheus-stack: lee cada 15 s con un PodMonitor; ventanas de 5 min
Prometheus v3.15.1 en localhost:9952: lee cada 5 s con file_sd_configs sobre pods.json; ventanas de 1 min
Las alertas
5xx, p99, LogsStale a los 30 min y ALB5xx en CloudWatch
las mismas 5 en tu reglas.yml: LogsStale a los 3 min, ALB5xx con las métricas del ALB del dojo
Trazas
≈ 1 % con OpenTelemetry y Grafana Tempo; los exemplars llevan a la traza
≈ 1 % como exemplar (el request_id como trace_id), sin trazas completas: del exemplar a la línea con mundo/buscar.py
El almacén
Amazon S3, bucket ml-datos, con KMS y un rol que solo escribe en logs/
RustFS 1.0.4 en localhost:9950: el mismo bucket y las mismas rutas
En la nube
En el dojo
Qué cambia
Nodos de EKS con 3 a 12 pods del gateway
dos contenedores de Docker (<code>nodo-a</code>, <code>nodo-b</code>) con un pod cada uno
Cada nodo tiene su propio disco de logs (un volumen): solo lo ven su runtime y su Fluent Bit, como en un nodo de verdad.
containerd y el kubelet
<code>mundo/runtime.py</code> y <code>mundo/nodo.py</code>
El mismo formato CRI, la misma rotación (5 archivos de 10 MiB) y el reinicio con espera creciente.
Un PodMonitor de kube-prometheus-stack (<code>kubernetes_sd_configs</code>)
<code>file_sd_configs</code> sobre <code>nodo/descubrimiento/pods.json</code>
Las mismas etiquetas __meta_kubernetes_*: tu relabel_configs es el que escribirías en C01. Lo que haría un ServiceMonitor sale de servicios.json.
Fluent Bit como DaemonSet
un contenedor de Fluent Bit 5.1.5 por nodo
La misma configuración en los dos; ${NODO} lo pone cada contenedor.
Amazon S3, con KMS y un rol que solo escribe en <code>logs/</code>
RustFS 1.0.4 en <code>localhost:9950</code>
La misma API, el mismo bucket y las mismas rutas; sin cifrado ni roles.
CloudWatch con las métricas del ALB (AWS/ApplicationELB) y la alarma ALB5xx
el ALB del dojo publica en <code>localhost:8957</code> con nombres de CloudWatch y Prometheus los lee
ALB5xx vive en tu reglas.yml, junto a las demás.
Lecturas cada 15 s, ventanas de 5 min, subidas cada 5 min y LogsStale a los 30 min
cada 5 s, ventanas de 1 min, cada minuto y a los 3 min
Todo más corto para no esperar; las reglas y las consultas son las mismas.
Trazas completas con OpenTelemetry y Grafana Tempo; los exemplars llevan a la traza
el exemplar lleva el request_id como trace_id; de ahí, <code>mundo/buscar.py</code> encuentra la línea
No hay spans: no ves por dentro de Triton, solo los tramos de la línea (pre, triton, post).
≈ 116 requests por segundo en promedio
5 fotos/s de siempre y la carga que mandes
Los volúmenes son chicos; las cuentas por request (bytes, series) son las mismas.
La lección de Sensei nombra la etiqueta <code>status</code> y el histograma <code>classifier_request_latency_seconds</code>
<code>code</code> y <code>classifier_request_seconds</code>
El dojo sigue los nombres de sus estaciones 6 y 10, los que ya busca el análisis del canary. Lo demás es igual.
La lección de Sensei sigue a la release 14 (<code>resnet50-2026-10-01</code>)
la release 15 (<code>resnet50-2026-11-01</code>)
El dojo sigue su propio tronco: la estación 10 subió la 15.
El 405 lo contesta FastAPI antes de que corra el código: sin línea ni cuenta en el gateway
el gateway del dojo también anota el 405 (su línea y su cuenta)
main.py lo atrapa en su manejador de errores; el ALB lo cuenta igual.
Qué trae el kit y qué escribes tú
Lo que trae no lo escribes
mundo/crear.py y compose.yaml. Levanta todo en ≈ 14 s (la primera vez ≈ 2 min, porque baja las imágenes y construye la del nodo): RustFS 1.0.4 como S3 (localhost:9950, consola en 9951), Prometheus v3.15.1 con exemplar-storage (localhost:9952), los nodos nodo-a y nodo-b y un Fluent Bit por nodo. Deja en S3 el log de ayer (11,849 requests, con el rollout de la 14 a la 15 a las 16:00 UTC y 2 archivos subidos dos veces) y vuelve la carpeta un repositorio de git.
mundo/runtime.py y mundo/nodo.py. El runtime de cada nodo (en C01, containerd): corre el pod y escribe su stdout en /var/log en formato CRI, con la rotación del kubelet (5 archivos de 10 MiB). Y el kubelet del dojo: estado, logs, reiniciar, matar, parar, arrancar, publicar. Al publicar escribe nodo/descubrimiento/pods.json y servicios.json: lo que la API de Kubernetes le contestaría a Prometheus.
mundo/alb.py. El ALB del dojo en localhost:8950: verifica el JWT de cada caller, reparte entre los pods registrados en su target group (health check a /readyz cada 2 s), contesta él mismo 401, 404 y 503, mide TargetResponseTime, escribe su access log en logs/alb.log y publica sus números con nombres de CloudWatch en localhost:8957.
mundo/carga.py, mundo/buscar.py y mundo/relojes.py. Los callers, por el ALB y con token (--una cuenta una request con detalle; --basura manda 415 y 405; --fuente-loca, un X-Client-Source distinto en cada request); buscar una request por su id en el backend, el ALB, el disco de cada nodo y S3; y los tres relojes unidos por request_id. El tráfico de siempre, 5 fotos/s, corre solo.
mundo/recargar.py. Lleva tus cambios a lo que corre: prometheus (promtool y recarga), fluent-bit (reinicia los dos) y gateway (reinicia los pods uno tras otro, drenándolos en el ALB). Antes espera a que el contenedor vea tu archivo completo.
mundo/vigia_s3.py y mundo/triton_dojo/. El vigía publica en localhost:8956 cuándo llegó el último archivo de log de cada nodo (dojo_s3_ultimo_objeto_timestamp_seconds); Triton del dojo sirve la release 15 en localhost:8955.
mundo/plataforma.yaml y mundo/prometheus/plataforma.yml. Lo del equipo de plataforma: los pods con sus etiquetas, el kubelet, el ALB y su llave, y lo que Prometheus ya lee (Triton, el ALB, Fluent Bit y el vigía). Cambia solo con un commit.
gateway/ (menos rastro.py), gateway.yaml y servir/. La release 15 de las estaciones 6 a 10. main.py llama a rastro.py para todo lo que la request deja escrito; gateway.yaml trae las fuentes permitidas (mobile, web, internal) y la fracción de exemplars (0.01).
verificar.py y romper.py. 12 checks contra lo que corre (los pods, Prometheus, Fluent Bit y S3) y 6 fallas en el mundo, la configuración o la infraestructura, nunca en lo que escribes.
Lo que escribes lo escribes tú
gateway/app/rastro.pyEl rastro de cada request: su request_id, la fuente reducida a 4 valores, si deja exemplar (por el hash del id), las 8 métricas del contrato y la línea de JSON compacto en stdout.
observabilidad/prometheus.ymlEl job gateway: descubre los pods en pods.json y se queda con cada uno una sola vez, con las etiquetas pod, nodo y hash.
observabilidad/reglas.yml3 recording rules (requests por segundo, fracción de errores del servidor, p99 por versión) y 5 alertas, también para lo que se calla.
observabilidad/fluent-bit.confLee los logs del gateway en formato CRI, agrega el nodo y los sube a S3 cada minuto, con gzip, buffer en disco y reintentos suficientes.
diario/a_parquet.pyEl job diario: el crudo de ayer, sin repetidos y solo las líneas del gateway, a Parquet por fecha y versión, idempotente.
Reglas CLAUDE.md del kit
El CLAUDE.md del kitLas reglas de fondo para Claude Code en la carpeta del kit. Ya viene en el .zip.Ver el CLAUDE.md ↓
prompt
# Dojo de entrenamiento ML engineer's · C01 · Estación 11: La request en vivo
Este es un mini-proyecto de práctica. Reproduce en pequeño, en una Mac sin nube, la estación «La request en vivo» del caso C01: que cada request deje tres rastros (una línea de log, sus sumas en las métricas y, a veces, un exemplar que lleva a ella), unidos por el mismo `request_id`, y que cada rastro llegue a donde alguien lo puede leer (Prometheus, S3 y Parquet) sin frenar nunca la respuesta. Prometheus, Fluent Bit y el S3 (RustFS) son los de verdad; lo que cambia contra C01 es dónde corre y cuánto duran las cosas. La persona con la que trabajas está aprendiendo; tu trabajo es que **entienda**, no que termine rápido.
## Qué es cada cosa
| Carpeta o archivo | Qué es | ¿Se toca? |
|---|---|---|
| `mundo/crear.py`, `compose.yaml`, `mundo/comun.py`, `mundo/nodo/Dockerfile` | Cómo nace el mundo: el S3, Prometheus, los dos nodos del gateway y un Fluent Bit por nodo, y el log de ayer ya subido. | **No.** |
| `mundo/runtime.py`, `mundo/nodo.py` | El runtime de cada nodo (escribe el stdout del pod en `/var/log` en formato CRI) y el kubelet del dojo (arranca, reinicia, publica los pods a Prometheus). | Se usa `nodo.py` (`estado`, `logs`, `reiniciar`, `matar`, `arrancar`, `parar`, `publicar`). |
| `mundo/plataforma.yaml`, `mundo/prometheus/plataforma.yml`, `mundo/callers.json` | Lo del equipo de plataforma: los pods y sus etiquetas, el ALB, lo que Prometheus ya lee (Triton, ALB, Fluent Bit, vigía) y el proveedor de identidad. | Solo con un `git revert` cuando una falla lo pide. |
| `mundo/alb.py`, `mundo/vigia_s3.py`, `mundo/triton_dojo/` | El ALB del dojo (token, target group, 503/401 propios, sus métricas «de CloudWatch» en :8957 y su access log), el vigía de S3 y el Triton del dojo. | **No.** |
| `mundo/carga.py`, `mundo/buscar.py`, `mundo/relojes.py`, `mundo/fotos/` | Los callers (el tráfico por el ALB), buscar una request por su id en todos lados y comparar los tres relojes. | Se usan. |
| `gateway/` (menos `rastro.py`), `gateway.yaml`, `servir/`, `model_repository/` | La release 15 de las estaciones 6 a 10. `main.py` llama a `rastro.py` para todo lo que la request deja escrito. | **No.** |
| `gateway/app/rastro.py`, `observabilidad/prometheus.yml`, `observabilidad/reglas.yml`, `observabilidad/fluent-bit.conf`, `diario/a_parquet.py` | Los escribe la persona. El contrato está arriba de cada archivo. | **Sí.** |
| `verificar.py` | Los 12 checks, contra lo que corre (pods, Prometheus, Fluent Bit, S3). | No. |
| `romper.py` | Mete fallas en el mundo, la configuración o la infraestructura. Nunca en lo que escribe la persona. | No. Y no leas su código para adivinar una falla escondida. |
| `GUION.md` / `OBJETIVOS.md` | El paso a paso (Construir con ayuda) y solo los objetivos (Construir solo). | No. |
| `taller/progreso.json`, `BITACORA.md` | El registro de las rondas. | Sí, tú los mantienes (ver abajo). |
## Cómo se trabaja
- Responde en español neutro, de tú, directo y sin relleno. Términos técnicos en inglés la primera vez, con su explicación.
- Explica siempre el **por qué**. Cuando algo en el dojo es distinto de C01 real, dilo en una línea: los nodos son dos contenedores de Docker con un pod cada uno, en lugar de nodos de EKS; el runtime y el kubelet son `mundo/runtime.py` y `mundo/nodo.py`; Prometheus descubre los pods con `file_sd_configs` sobre `nodo/descubrimiento/pods.json` (mismas etiquetas `__meta_kubernetes_*` que `kubernetes_sd_configs`), en lugar de un PodMonitor de kube-prometheus-stack; Fluent Bit es un contenedor por nodo en lugar de un DaemonSet; el S3 es RustFS; el ALB es un proceso que imita lo que el gateway no ve (sus métricas irían a CloudWatch); se lee cada 5 s (C01: 15 s), Fluent Bit sube cada minuto (C01: 5 min), LogsStale a los 3 min (C01: 30 min) y las ventanas de PromQL son de 1 min (C01: 5 min); no hay trazas completas con OpenTelemetry y Tempo: el exemplar lleva al `request_id` y de ahí a la línea de log; el tráfico de siempre son 5 fotos/s (C01: ≈ 116).
- Nunca inventes salidas: si no corriste algo, di que no lo corriste.
- Usa el Python del venv (`source .venv/bin/activate`). Docker en esta Mac: `export DOCKER_CONFIG=$PWD/.docker` antes de `docker compose …` (lo crea `mundo/crear.py`, sin el llavero de macOS).
- Cómo llega cada cambio a lo que corre: `python mundo/recargar.py gateway` (después de `rastro.py`: reinicia los pods uno tras otro), `python mundo/recargar.py prometheus` (`prometheus.yml` o `reglas.yml`: promtool + recarga; luego revisar http://localhost:9952/targets o /rules) y `python mundo/recargar.py fluent-bit` (`fluent-bit.conf`). No uses el `curl -X POST …/-/reload` a secas justo después de guardar: Docker Desktop puede darle a Prometheus el archivo a medias; `recargar.py` espera a que lo vea completo. Un archivo bien escrito que no se recargó no cuenta.
- Para ver algo con tráfico, `python mundo/carga.py --tasa 30 --segundos 60` en otra terminal (el tráfico de siempre son 5 fotos/s). Prometheus necesita ≈ 1 min de datos para que un `rate(…[1m])` tenga sentido.
- Antes de correr algo que cambia el mundo (`mundo/nodo.py reiniciar|matar|parar|arrancar`, `mundo/recargar.py`, `docker compose stop|start|restart`, `mundo/carga.py`, `diario/a_parquet.py`, `romper.py`, `git commit`, `git revert`), dilo. Lo que solo lee (`verificar.py`, `mundo/nodo.py estado|logs`, `mundo/buscar.py`, `mundo/relojes.py`, `curl` a `/metrics` o a la API de Prometheus, `docker compose logs|ps`, `git log`) se puede correr directo.
- Tiempos de referencia: `mundo/crear.py` ≈ 30 s (≈ 2 min la primera vez); un reinicio del gateway ≈ 2 s por pod; un objeto nuevo en S3 cada ≈ 1 min por nodo; `diario/a_parquet.py` ≈ 2 s para el día de ayer (≈ 12,000 requests); `verificar.py` ≈ 15 s.
- Enséñale a mirar, en este orden: `python verificar.py <check>`, http://localhost:9952/targets y /alerts, `curl -s localhost:8951/metrics | grep classifier_`, `python mundo/nodo.py logs a`, `python mundo/buscar.py <request_id>`, `docker compose logs fluent-bit-a`, `curl -s localhost:9953/api/v2/metrics/prometheus`, `curl -s localhost:8957/metrics` y `logs/alb.log`, y `git log --oneline`.
- Las reglas de otros equipos (`mundo/plataforma.yaml`, `gateway.yaml`, los nombres de las métricas) no se cambian para que algo pase.
- Sigue el prompt de la ronda que te pegaron: en Construir solo y en Romper solo **no das código ni pistas** salvo que la persona se rinda.
## Bitácora
Al terminar cada paso, objetivo o falla, agrega una entrada en los dos archivos:
`BITACORA.md`, legible en el celular:
```markdown
## 2026-11-20 10:42 · Construir con ayuda · paso 4 (Prometheus lee los pods)
- **Hice:** …
- **Medí:** … (números reales que salieron)
- **Sigue:** …
```
`taller/progreso.json`, el que se importa en «Tu tablero» del Dojo (la página /tablero/ de la app). Agrega a `bitacora` y actualiza `rondas`:
```json
{
"estacion": "c01-request",
"rondas": {
"guiado": { "estado": "en_curso", "inicio": "2026-11-20T10:05:12-06:00", "fin": null },
"solo": { "estado": "pendiente", "inicio": null, "fin": null, "pistas": 0 },
"romper_ayuda": { "estado": "pendiente", "fallas": [] },
"romper_solo": { "estado": "pendiente", "fallas": [] }
},
"bitacora": [
{ "fecha": "2026-11-20T10:42:30-06:00", "ronda": "guiado", "paso": "prometheus", "hice": "…", "medi": "…", "sigue": "…" }
],
"verificaciones": [
{ "fecha": "2026-11-20T10:41:02-06:00", "pasan": ["mundo", "request-id"], "fallan": [] }
]
}
```
- `estado` es `pendiente`, `en_curso` o `hecha`. En el tablero, `guiado` se llama «Construir con ayuda», `solo` «Construir solo», `romper_ayuda` «Romper con ayuda» y `romper_solo` «Romper solo».
- **Fecha y hora en cada avance**, en ISO 8601 con la zona de la Mac: sácala con `date -Iseconds`. Nunca solo la fecha.
- `verificaciones` la escribe `verificar.py` solo, en cada corrida. No la edites.
- Cada falla la anota `romper.py` al cerrarla (`--verificar` o `--revelar`): `{ "id", "inicio", "fin", "minutos", "pistas": 0, "rendido", "aprendi": "" }`, con el tiempo real. Tú solo completas `pistas` y `aprendi` en esa misma entrada (la última de su ronda); no agregues otra.
- Mantén el JSON válido: después de editarlo, corre `python3 -m json.tool taller/progreso.json > /dev/null`.
Sensei es el curso de teoría desde cero de TrueML. Su lección de esta estación explica el porqué de lo que aquí construyes; léela antes o vuelve a ella cuando algo no cierre.