Qué pasa cuando algo falla
Cada salto del motor con lo que puede fallar en él, dónde esperan los datos mientras tanto, cuántas veces se intenta, a dónde va lo que no se pudo hacer, a quién se le avisa y cómo se vuelve a procesar. Colas, colas de mensajes fallidos y salud, en las dos formas de despliegue.
En esta página
- La garantía
- Salto por salto
- Las fallas, una por una
- La Ingesta está caída
- El Bucket está caído
- Postgres está caído
- Un lote o un segmento envenenado
- Un proyecto lento
- El proveedor de IA falla o está lento
- Tu receptor de webhooks está caído
- Un despliegue en mitad de una corrida
- La misma corrida empieza dos veces
- Relojes que no coinciden
- La cola se atrasa
- Colas y colas de mensajes fallidos
- En AWS: una cola y su cola de mensajes fallidos
- En un solo proceso: el búfer
- Trabajo como filas
- Salud
- GET /healthz
- GET /v1/engine/status
- sypnia doctor
- Lo que no prometemos
- Qué cambió frente al sistema del que sale
- Sigue
Esta página responde una pregunta: ¿el motor es frágil? Recorre cada salto que da un evento y dice qué puede fallar ahí, dónde esperan los datos mientras falla, cuántas veces se intenta, a dónde va lo que no se pudo hacer, a quién se le avisa y el comando exacto que lo vuelve a procesar.
La garantía
Entre pasos, al menos una vez. Dentro de un paso, se puede repetir sin daño. Juntas: cada evento se cuenta una vez.
Ningún paso del motor confía en que corre exactamente una vez. Las funciones se reintentan, las colas entregan dos veces, a los procesos los matan después de hacer el trabajo y antes de decirlo. En vez de fingir lo contrario, el motor hace que la segunda corrida no cause daño. Lo logran tres mecanismos, y los tres están en las páginas anteriores:
| Mecanismo | Qué protege | Dónde |
|---|---|---|
batch_id en cada línea guardada | Un lote que llega dos veces, porque un SDK reintentó o una cola entregó dos veces, se guarda y nunca se cuenta dos veces | Ingesta |
El registro: una fila por segmento, con scanned_at y rolled_at | Un segmento lo revisa un solo worker, y sus contadores se suman en la misma transacción que lo marca. Pasan las dos cosas o ninguna | Agregación |
| Upserts y llaves únicas | Un problema tiene una fila por huella; una alerta tiene una fila por causa (dedupe_key); una tarea tiene una fila abierta por problema; los números de una hora se reemplazan enteros | Agrupación de problemas, Almacenamiento |
La guarda contra duplicados es una sola sentencia. Fíjate en que no necesita candado ni una lectura previa de «¿ya lo vi?»: la llave primaria responde, y los ids que no se insertaron son los duplicados.
-- La corre la vía rápida dentro de la transacción que marca el segmento como revisado.
-- $3 = los ids de lote que trae el segmento. Devuelve los que son nuevos.
INSERT INTO ingest_batches (project_id, batch_id, segment)
SELECT $1, batch_id, $2
FROM unnest($3::text[]) AS t(batch_id)
ON CONFLICT (project_id, batch_id) DO NOTHING
RETURNING batch_id;
-- Todo id de $3 que no volvió ya pertenece a un segmento anterior.
-- Esos van a segments.skipped, y desde entonces todo lector salta sus líneas.La segunda mitad de la garantía es que el trabajo nunca queda solo en memoria una vez aceptado. En todo momento un evento aceptado está en uno de cuatro lugares durables:
| Lugar | Guarda | Por cuánto tiempo |
|---|---|---|
| La cola de entrada Motor solo en la forma de AWS | Lotes validados que aún no están en un segmento | Segundos, normalmente; hasta 4 días |
| El Bucket | Segmentos, fragmentos de grabación, archivos por sesión | Hasta que la retención los borra |
| El registro en Postgres | Qué segmentos existen, cuáles están revisados, cuáles están consolidados | Lo mismo que el segmento |
| Una fila con una hora | Tareas del agente, alertas retenidas, entregas de webhook, horas por consolidar de nuevo | Hasta que se hace, o se marca como abandonada |
La figura que sigue es el flujo de datos de la página anterior dibujado para esta pregunta: cada flecha que puede fallar tiene su ciclo de reintento, cada lugar de espera está marcado y se muestra cada salida para el trabajo que no se pudo hacer.
Salto por salto
Una fila por salto. «Intentos» cuenta el primero. Las secciones después de la tabla entran en las filas que lo necesitan.
| # | Salto | Qué puede fallar | Qué pasa, y dónde esperan los datos | Se rinde después de, y va a | A quién se le avisa | Cómo se vuelve a procesar | Qué ves mientras tanto |
|---|---|---|---|---|---|---|---|
| 1 | Tu app (SDK) → Ingesta | La Ingesta no responde, 429, 503, se agota el tiempo | El SDK del navegador conserva el lote y lo envía de nuevo a 1 s, 4 s y 15 s con el mismo batch_id, y después con el siguiente envío cada 10 s. Los eventos esperan en su cola: 500 eventos en memoria, salen primero los más viejos. Los SDK de servidor reintentan y luego descartan | La cola de 500 se llena, o la pestaña se cierra: esos eventos se pierden | A nadie de inmediato. El hueco se ve como un data_through que no avanza; un monitor tuyo sobre /healthz lo ve primero | No se puede: los datos nunca llegaron | Leer sigue funcionando. No hay datos nuevos |
| 2 | Ingesta → la cola o el búfer | La cola rechaza el envío (AWS). El búfer está lleno: 32 MiB esperando en total, u 8 MiB de un solo proyecto (un proceso) | La Ingesta responde 503 unavailable con Retry-After: 2. No guardó nada, así que el reintento del SDK del salto 1 lo cubre | Como el salto 1 | La línea de log de la Ingesta; engine.failing si dura 30 minutos | No hace falta | Como el salto 1 |
| 3 | La cola o el búfer → Bucket | El Bucket rechaza la escritura | Un proceso: los lotes de ese segmento reciben 503 y sus SDK reintentan. AWS: el mensaje se queda en la cola y se entrega de nuevo a los 15 s, 1 min, 5 min y 15 min | AWS: 5 entregas, y luego la cola de mensajes fallidos, donde se guarda 14 días | La alarma de mensajes fallidos; la alarma de antigüedad de la cola; engine.failing | Redrive: un comando, más abajo | Las listas y los problemas se siguen leyendo de Postgres. Las grabaciones y las líneas de tiempo responden 503 |
| 4 | Ingesta o worker → Postgres (la fila del registro) | Postgres caído, sin conexiones libres | Un proceso: la fila se conserva y se reintenta; el segmento ya está en el Bucket. AWS: el mensaje no se borra hasta que la fila exista, así que la cola lo entrega de nuevo | Un proceso: nunca se rinde; al reiniciar encuentra el segmento listando el Bucket. AWS: como el salto 3 | engine.failing a los 30 minutos | Nada que hacer. Después de restaurar un respaldo: sypnia aggregate --from <hora> vuelve a listar el Bucket | Los eventos están a salvo y aún no se cuentan |
| 5 | Bucket → Vía rápida → Postgres | El objeto no se puede leer; una línea que rompe al lector; la transacción falla; el worker muere a mitad de la revisión | La reserva del segmento vence a los 2 minutos, o se devuelve con una espera de 10 s, 30 s, 2 min, 5 min. Otro worker lo toma. El segmento espera en el Bucket, su fila en el registro | 5 intentos, y luego cuarentena: quarantined_at y el error en su fila del registro | Una alerta engine.failing que nombra el segmento, de inmediato | sypnia aggregate --project <p> --from <t> --to <t> le da cinco intentos nuevos | Todo lo demás del proyecto, y todos los demás proyectos, fluyen. Los eventos de ese segmento no se cuentan |
| 6 | Bucket → Consolidación → Postgres | Se pasa del presupuesto de memoria, un error de lectura, el commit falla, el worker muere | No se escribió nada: la corrida es una transacción. La hora se marca failed y se intenta de nuevo en la siguiente pasada, luego a 1, 5 y 15 minutos, y después cada 30 | Nunca, dentro de 48 horas. Una corrida que falla 5 veces en el mismo segmento pone ese segmento en cuarentena y sigue sin él | engine.failing a los 30 minutos, con el proyecto y la hora | Sola; o sypnia aggregate --from … --to … para horas de más de 48 horas | Los problemas llegan a tiempo. Los números de ese proyecto y esa hora llegan tarde |
| 7 | Vía rápida → el agente → el proveedor de IA | El proveedor responde un error, se agota el tiempo (60 s) o devuelve una respuesta que no pasa la revisión | La tarea es una fila. Se intenta de nuevo a los 5 s y a los 30 s. La alerta no espera: sale en su release_by con el título técnico | 3 intentos, y luego la tarea queda dead y el problema muestra analysis.status: failed con el motivo | El problema mismo, en la API, el servidor MCP y la Consola | POST /v1/problems/{problem}/analyze; o sola cuando el problema crece | El problema, sus conteos, su alerta y su prompt, sin la frase |
| 8 | Postgres → Alertas | El worker muere entre escribir la alerta y liberarla | La alerta es una fila con release_by. Cualquier pasada libera lo que ya pasó su hora; liberar es un UPDATE … WHERE released_at IS NULL | Nunca | — | No hace falta | La alerta, máximo una pasada tarde |
| 9 | Alertas → tu webhook | Tu receptor está caído, lento (10 s) o responde algo que no es 2xx | La entrega es una fila. 7 intentos: de inmediato, y luego a 1 min, 5 min, 30 min, 2 h, 6 h y 12 h, con el mismo id de evento | 7 intentos, y luego la entrega queda failed. Tras 3 días de puras fallas el webhook se apaga | GET /v1/webhooks/{id}/deliveries; una alerta engine.failing cuando el webhook se apaga | POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry; PATCH al webhook para encenderlo | La alerta queda registrada y se ve en la Consola y la API todo el tiempo |
| 10 | Postgres y Bucket → API, servidor MCP, Consola | Postgres no tiene conexiones libres; el Bucket no responde | 503 unavailable con Retry-After: 2, de inmediato. La API no hace cola | — | Quien llama | Quien llama reintenta | Un error con un tiempo de espera, nunca un número equivocado |
| 11 | La programación → el worker (AWS) | Un tic se pierde, llega tarde o llega dos veces | El siguiente tic, un minuto después, hace todo lo que habría hecho el perdido: todo el trabajo pendiente son filas | Nunca | La alarma del worker, si la función misma falla | No hace falta | Máximo un minuto más de demora |
Tres cosas valen para todas las filas:
- Quien envía conserva el trabajo hasta que quien recibe lo tiene de forma durable. El SDK conserva el lote hasta el
200; la cola conserva el mensaje hasta que el worker lo borra; el registro conserva el segmento hasta que su transacción confirma. - Rendirse es un estado, no una desaparición. Una cola de mensajes fallidos, un segmento en cuarentena, una tarea
deady una entregafailedson cosas que puedes listar, leerles el error y enviar de nuevo. - Una falla demora; no corrompe. Un paso que corre dos veces escribe el mismo resultado. Es la regla 3 del resumen, y las pruebas de reproducción de el código corren cada paso dos veces para probarlo.
Las fallas, una por una
La Ingesta está caída
Los SDK guardan lo que pueden (salto 1) y leer no se afecta: la API, el servidor MCP y la Consola no dependen de la Ingesta. En AWS «la Ingesta está caída» quiere decir que la función falla o llegó a su tope de 40 copias; la dirección responde 503 o 429 y los SDK reintentan. En la forma de un solo proceso quiere decir que el proceso está caído, y la API con él, salvo que corras los roles por separado.
Se pierde lo que el SDK no pudo guardar: más de 500 eventos en una pestaña, una pestaña que se cerró, el último lote de una página que se envió con sendBeacon y no tuvo respuesta. El motor no puede saber de eventos que nunca recibió, así que esta pérdida solo se ve como un hueco.
El Bucket está caído
La Ingesta responde 503 y no acepta nada que no esté guardado, así que no hay nada que recuperar: los SDK reintentan. En AWS, los lotes que ya están en la cola esperan ahí. Leer de Postgres sigue funcionando: la lista de problemas, un problema, los números, las alertas. Todo lo que necesita un objeto responde 503: grabaciones, la línea de tiempo de una sesión, el detalle de una traza.
Postgres está caído
Se sigue recibiendo. La Ingesta no consulta Postgres: usa su caché de llaves, que sigue siendo válida hasta una hora sin refrescarse. Los segmentos se escriben; la vía rápida, la consolidación y la API se detienen. Cuando Postgres vuelve, el worker toma todo lo no revisado, lo más viejo primero y un proyecto a la vez por turnos, y consolida cada hora abierta.
| Forma | Dónde esperan los eventos durante la caída | Si dura |
|---|---|---|
| Un proceso | En el Bucket, como segmentos. Sus filas del registro se conservan en memoria y se reintentan; un worker que arranca lista las últimas dos horas de cada proyecto y agrega cualquier segmento que el registro no conozca | Más de una hora: la Ingesta responde 503, porque su caché de llaves es demasiado vieja para confiar en ella |
| Funciones de AWS | En la cola de entrada. Un mensaje solo se borra cuando existen su segmento y su fila del registro | Más de unos 20 minutos: los lotes llegan a su quinta entrega y pasan a la cola de mensajes fallidos, donde esperan hasta 14 días un comando de redrive |
Lo que Postgres guarda y el Bucket no puede devolver es lo que escribió la gente: estados, notas, reglas, llaves, tokens. Para eso son sus respaldos. Todo lo que viene de eventos se reconstruye con sypnia aggregate --from … --to ….
Un lote o un segmento envenenado
Una entrada «envenenada» es la que falla cada vez que se intenta: un objeto cortado, una línea que dispara un error en un lector, un valor que una tabla rechaza. El peligro no es el segmento perdido. Es un worker que lo toma, muere, lo vuelve a tomar y nunca llega al trabajo que hay detrás.
Tres capas lo impiden:
- Un evento malo nunca se vuelve un segmento malo. La Ingesta juzga cada evento por separado: lo recorta, lo limpia o lo descarta, y lo dice en la respuesta. Una línea que aun así no se puede interpretar al leerla se cuenta (
unreadable) y se salta. Ninguna de las dos cosas detiene nada. - Un mensaje malo no bloquea la cola (AWS). El worker le responde a la cola con la lista de los mensajes que no pudo escribir, no con una sola falla para toda la entrega. Los buenos se borran; uno malo vuelve solo y, tras 5 entregas, va a la cola de mensajes fallidos.
- Un segmento malo queda en cuarentena. Cada reserva cuenta un intento. Un segmento que se reservó 5 veces y nunca se revisó se marca con
quarantined_at, con el último error, y ningún lector lo vuelve a tomar.
Toda la decisión es la función de abajo. Fíjate en que el intento ya lo contó la reserva, así que un worker que muere antes de llegar a este código igual gasta un intento.
const MAX_ATTEMPTS: u32 = 5;
/// Cuánto espera un segmento que falló antes de su siguiente intento.
fn backoff(attempts: u32) -> Duration {
match attempts {
0 | 1 => Duration::from_secs(10),
2 => Duration::from_secs(30),
3 => Duration::from_secs(120),
_ => Duration::from_secs(300),
}
}
/// La llama `run` cuando `scan_segment` devolvió un error. Un segmento malo nunca termina la pasada.
async fn give_back(engine: &Engine, segment: &Segment, error: &EngineError) -> Result<Outcome, EngineError> {
if segment.attempts < MAX_ATTEMPTS {
// Suelta la reserva antes de tiempo, con una espera. Puede que otro worker sí lo logre.
engine.db.release_segment(segment, backoff(segment.attempts), &error.to_string()).await?;
return Ok(Outcome::Retrying);
}
// Fuera del camino de todo lector. El objeto se queda donde está; la hora se consolida sin él.
let mut tx = engine.db.begin().await?;
tx.quarantine_segment(segment, &error.to_string()).await?;
alerts::record_engine_failing(&mut tx, Failing::Quarantined(segment), engine.clock.now()).await?;
tx.commit().await?;
Ok(Outcome::Quarantined)
}Un segmento en cuarentena son 2 segundos de eventos de un proyecto, máximo 4 MiB. Sus eventos no están en ningún conteo hasta que alguien lo vuelva a procesar. Para hacerlo, casi siempre después de actualizar a una versión que corrige al lector:
sypnia aggregate --project shop --from 2026-03-12T09:00:00Z --to 2026-03-12T10:00:00ZVolver a procesar un rango quita la cuarentena de los segmentos que hay en él, le da a cada uno cinco intentos nuevos, y agrega al registro cualquier segmento del rango que esté en el Bucket y no en el registro. Nada se cuenta dos veces: los segmentos que ya se habían sumado conservan su rolled_at.
Un proyecto lento
Un proyecto no debe atrasar a los demás, envíe lo que envíe. Cada parte tiene su propia guarda:
| Parte | Qué podría acaparar un proyecto pesado | La guarda |
|---|---|---|
| Ingesta | El búfer | Un segmento abierto por proyecto. De los 32 MiB que pueden esperar en total, un proyecto puede tener 8 MiB; pasado eso, sus lotes reciben 503, los de los demás no. Los límites de frecuencia son por llave |
| Vía rápida | El tiempo del worker | Turnos. Cada reserva va al proyecto que lleva más tiempo sin ser atendido, y toma un segmento. Un proyecto con mil segmentos atrasados recibe un turno por ronda, igual que un proyecto con uno |
| Consolidación | La memoria y las corridas de processing.concurrency | 256 MB por corrida, de forma obligatoria; una corrida que se pasa de su presupuesto se detiene y marca la hora failed. Los proyectos se toman empezando por el que lleva más tiempo sin consolidar, y una hora fallida espera 1, 5, 15 y luego 30 minutos entre intentos, así que no puede ocupar una corrida para siempre |
| El agente | Llamadas al modelo | 100 análisis al día por proyecto y 3 por problema; una tarea abierta por problema |
| API | Conexiones | Un grupo pequeño y acotado; 503 con Retry-After en vez de una cola |
La reserva es una sola sentencia. Fíjate en el orden: primero por cuándo tuvo su último turno el proyecto, y luego por antigüedad. El índice que lee solo contiene segmentos que están esperando, así que es pequeño por construcción.
-- $1 = la reserva (2 minutos). Devuelve un segmento, o ninguno.
WITH pick AS (
SELECT s.project_id, s.key
FROM segments s
LEFT JOIN project_turns t USING (project_id)
WHERE s.scanned_at IS NULL
AND s.quarantined_at IS NULL
AND (s.leased_until IS NULL OR s.leased_until < now()) -- libre, ya esperó, o su worker murió
ORDER BY t.fast_path_at NULLS FIRST, s.created_at
LIMIT 1
FOR UPDATE OF s SKIP LOCKED -- dos workers nunca reciben el mismo
), turn AS (
INSERT INTO project_turns (project_id, fast_path_at)
SELECT project_id, now() FROM pick
ON CONFLICT (project_id) DO UPDATE SET fast_path_at = EXCLUDED.fast_path_at
)
UPDATE segments s
SET leased_until = now() + $1,
attempts = s.attempts + 1 -- se cuenta aquí, antes de cualquier trabajo
FROM pick
WHERE s.project_id = pick.project_id AND s.key = pick.key
RETURNING s.*;El proveedor de IA falla o está lento
El agente es la única parte que espera a un servicio que el motor no controla, así que nada más espera al agente. La alerta se libera en su release_by, exista o no la frase. Una llamada tiene 60 segundos (ai.timeout_seconds); una tarea tiene 3 intentos, a los 5 y a los 30 segundos; después la tarea queda dead y el problema dice analysis.status: failed con el error del proveedor. Cuando 5 tareas seguidas terminan así, el agente deja de llamar durante 5 minutos, para que una caída del proveedor no gaste el tiempo del worker en llamadas que no pueden salir bien; las tareas siguen en cola.
Un análisis fallido se intenta de nuevo solo cuando el problema crece o vuelve, y de inmediato cuando lo pides: POST /v1/problems/{problem}/analyze.
Tu receptor de webhooks está caído
La alerta existe antes de intentar cualquier entrega: es una fila, se ve en la Consola y la devuelve GET /v1/alerts. La entrega es una segunda fila con sus propios intentos (salto 9). Un receptor que estuvo caído un día recibe la alerta en el séptimo intento, con el mismo id de evento, así que puede ignorar lo que ya manejó. Un receptor que estuvo caído más tiempo lee lo que se perdió con GET /v1/alerts, o pide de nuevo entregas sueltas.
Un despliegue en mitad de una corrida
| Forma | Qué hace un despliegue | Por qué no se rompe nada |
|---|---|---|
| Un proceso | SIGTERM: las solicitudes tienen 20 segundos, los segmentos abiertos se escriben, la pasada termina su paso actual y luego el proceso sale | Un paso que se cortó es una reserva que vence o una transacción que nunca confirmó. El proceso nuevo lo hace otra vez |
| Funciones de AWS | Las llamadas en curso terminan en la versión vieja; las nuevas empiezan en la nueva | Lo mismo, y la cola conserva lo que una llamada interrumpida no borró |
| Las dos | La versión vieja y la nueva corren juntas un momento | Las migraciones solo agregan: un binario más viejo sigue funcionando contra un esquema más nuevo |
Un worker al que matan en mitad de una consolidación deja su hora marcada running. Otro worker toma esa hora a los 20 minutos. Es el único caso en que los números pueden tardar más de 10 minutos; los problemas no se afectan, porque la reserva de un segmento es de 2 minutos.
La misma corrida empieza dos veces
Pasa: una programación que entrega un tic dos veces, dos workers, el reintento de una llamada que en realidad sí había terminado bien. Cada trabajo tiene un reclamo que solo una corrida puede ganar:
| Trabajo | El reclamo |
|---|---|
| Revisar un segmento | La reserva: FOR UPDATE SKIP LOCKED |
| Sumar los contadores de un segmento | UPDATE segments SET rolled_at … WHERE rolled_at IS NULL; si la cuenta queda corta, la transacción se deshace |
| Los números de una hora | Se reemplazan enteros; dos corridas escriben las mismas filas |
| Una tarea del agente | El reclamo de la tabla de tareas; una tarea abierta por problema |
| Liberar una alerta | UPDATE … WHERE released_at IS NULL |
| Una entrega de webhook | La reserva de la fila de la entrega; tu receptor ve el mismo id evt_… si un intento se repite |
| La tarea diaria | Una fila de tarea por proyecto y día |
Relojes que no coinciden
| Reloj | Dónde está mal | Qué hace el motor |
|---|---|---|
| Un dispositivo | ts en el pasado o en el futuro | Cada lote trae sent_at. Cuando difiere de la hora de llegada en más de 2 minutos, las horas del lote se corren esa diferencia para ordenar. Un evento de más de 7 días se descarta como too_old y se cuenta en la respuesta |
| Un proceso del motor | Su hora difiere de la de la base de datos | Las reservas, release_by y todo «¿ya toca?» usan el reloj de la base de datos (now() en la sentencia), no el del proceso. sypnia doctor falla su revisión clock por encima de 5 segundos de diferencia |
| Un proceso de ingesta, por minutos | Un segmento queda nombrado dentro de una hora que ya está cerrada | El registro tiene un segmento de una hora cerrada sin consolidar; la consolidación vuelve a abrir esa hora. Las horas cuentan por llegada, así que nada se pierde ni se duplica |
La cola se atrasa
En AWS, un worker más lento que lo que llega se nota en la cola de entrada antes que en cualquier otra parte. Mientras dura no se pierde nada: la cola guarda un mensaje 4 días. Crecen dos cosas, y las dos se vigilan: la antigüedad del mensaje más viejo (una alarma a los 2 minutos) y el atraso del propio motor (una alerta engine.failing a los 30 minutos). Los SDK no notan nada, porque la Ingesta responde apenas el lote está en la cola. Lo primero que hay que subir es el número de copias de la función worker.
Colas y colas de mensajes fallidos
En AWS: una cola y su cola de mensajes fallidos
La cola de entrada ocupa el lugar que el búfer en memoria tiene en la otra forma. Es la única cola del motor; por qué hay una y no cuatro está en Formas de despliegue. La plantilla la crea con estos valores, y la razón de cada uno:
| Ajuste | Valor | Por qué |
|---|---|---|
| Tipo | Estándar | El orden no importa y un duplicado no hace daño: batch_id |
| Un mensaje | Un lote validado, en gzip, máximo 256 KiB | Un lote más grande lo escribe la Ingesta en el Bucket y el mensaje solo lo nombra |
| Retención de mensajes | 4 días | Un worker puede estar roto un fin de semana largo sin que se pierda nada |
| Ventana de agrupación | 10 segundos, o 500 mensajes, o 6 MB | Los segmentos siguen siendo pocos; una falla espera aquí máximo 10 segundos |
| Tiempo de invisibilidad | 15 minutos | No puede ser menor que el tiempo límite del worker. El worker mismo lo acorta para un mensaje que devuelve |
| Entregas antes de la cola de mensajes fallidos | 5 (maxReceiveCount) | Con las esperas de abajo, unos 20 minutos intentando |
| Retención de la cola de mensajes fallidos | 14 días, contados desde el primer envío | Tiempo para mirar, corregir y hacer redrive |
| Cifrado | En reposo, con las llaves del servicio | Los mensajes llevan datos de eventos |
Qué le dice el worker a la cola. Una entrega trae muchos mensajes. El worker escribe sus segmentos y sus filas del registro, y luego responde con los ids de los mensajes que no pudo terminar. Solo esos vuelven. Fíjate en que un error nunca se escapa del manejador: un manejador que falla entero devolvería los mensajes buenos junto con el malo.
/// El caso de la cola en `worker_event`. La respuesta nombra los mensajes que hay que entregar de nuevo.
async fn intake_batch(engine: &Engine, batch: SqsEvent) -> SqsBatchResponse {
let mut failed = Vec::new();
// Un grupo por proyecto y entorno: los mensajes que van a compartir un segmento.
for group in intake::group(batch.records) {
match intake::write_segment(engine, &group).await {
// El objeto existe y su fila del registro también. Revisar puede fallar: la pasada lo recoge.
Ok(segment) => {
let _ = fast_path::scan(engine, std::slice::from_ref(&segment)).await;
}
Err(error) => {
tracing::warn!(%error, scope = %group.scope, "segment not written; messages go back");
for message in &group.messages {
// 15 s, 1 min, 5 min, 15 min, según cuántas veces se entregó.
queue::delay(engine, message, redelivery_wait(message.receive_count)).await;
failed.push(BatchItemFailure { item_identifier: message.id.clone() });
}
}
}
}
SqsBatchResponse { batch_item_failures: failed }
}Un mensaje que el worker devuelve se ve de nuevo después de su espera. Un mensaje a cuyo worker lo mataron, por memoria o por tiempo, se ve de nuevo cuando termina el tiempo de invisibilidad: hasta 15 minutos después. Esos eventos llegan tarde, no se pierden, y son el único caso en AWS en que un problema puede no cumplir sus 2 minutos sin que nada esté roto de forma permanente.
Redrive
Los mensajes de la cola de mensajes fallidos se quedan ahí 14 días. Nada los lee por su cuenta: un lote que no se pudo escribir cinco veces es un error que hay que mirar o una caída que hay que esperar, y a ninguno de los dos lo ayuda un sexto intento inmediato. Cuando la causa ya no esté, devuélvelos:
# Cuántos hay estacionados
aws sqs get-queue-attributes --queue-url "$SYPNIA_INTAKE_DEAD_LETTER_QUEUE_URL" \
--attribute-names ApproximateNumberOfMessages
# Mirar uno sin quitarlo
aws sqs receive-message --queue-url "$SYPNIA_INTAKE_DEAD_LETTER_QUEUE_URL" \
--max-number-of-messages 1 --visibility-timeout 0
# Devolverlos todos a la cola de entrada
aws sqs start-message-move-task --source-arn "$(aws sqs get-queue-attributes \
--queue-url "$SYPNIA_INTAKE_DEAD_LETTER_QUEUE_URL" \
--attribute-names QueueArn --query Attributes.QueueArn --output text)"Los mensajes devueltos llegan como nuevos y siguen el camino normal. Si algunos en realidad ya se habían escrito, sus ids de lote ya se conocen y sus líneas se saltan.
Alarmas
La plantilla crea tres alarmas. Son alarmas de CloudWatch porque deben funcionar cuando el motor mismo no funciona; apúntalas a una notificación tuya.
| Alarma | Se dispara cuando | Quiere decir |
|---|---|---|
DeadLetterNotEmpty | La cola de mensajes fallidos tiene al menos 1 mensaje, durante 1 minuto | Se apartaron lotes. Mira uno, corrige, haz redrive |
IntakeBacklog | El mensaje más viejo de la cola de entrada tiene más de 120 segundos, durante 3 minutos seguidos | El worker no da abasto, o no está corriendo |
WorkerFailing | La función worker terminó en error en 3 de los últimos 5 minutos | Un error de código, un permiso que falta, Postgres o el Bucket fuera de alcance |
En un solo proceso: el búfer
sypnia serve no tiene cola, porque no la necesita: el proceso es la memoria.
| Dónde espera un lote | En el segmento abierto de su proyecto, en memoria, máximo 2 segundos |
| Cuándo se le responde al SDK | Después de que el segmento está en el Bucket. No antes |
| Qué pierde una caída del proceso | Nada de lo que se respondió con 200. Los lotes de los segmentos abiertos, máximo 2 segundos de tráfico, no habían sido respondidos: sus SDK reciben un error de red y los envían de nuevo |
| Qué puede costar igual una caída | Esos mismos lotes, si el proceso sigue caído más tiempo del que los SDK pueden guardarlos (salto 1) |
| Una fila del registro que aún no se escribió | Se encuentra de nuevo listando: al arrancar, un worker lista las últimas dos horas de cada proyecto y agrega lo que el registro no conoce. La tarea diaria revisa también el día anterior |
| Una parada ordenada | Los segmentos abiertos se escriben antes de que el proceso salga |
Esta es la diferencia honesta entre las dos formas. En AWS el punto durable es la cola, un servicio administrado que sigue funcionando mientras las funciones fallan. En un solo proceso el punto durable es el Bucket, y entre el SDK y el Bucket hay un proceso y 2 segundos. Corre dos procesos ingest detrás de un balanceador si esos segundos te importan: el reintento de un SDK llega entonces al otro.
Trabajo como filas
Todo lo que debe pasar más tarde, después del Bucket, es una fila en Postgres con una hora, no un mensaje en una cola. Tres clases de trabajo usan el patrón:
| Trabajo | Tabla | Intentos y esperas | Abandonado | Se ve en | Se vuelve a procesar con |
|---|---|---|---|---|---|
| El análisis del agente, la tarea diaria, las sugerencias semanales | jobs | 3: a los 5 s y a los 30 s | status = 'dead', last_error | El problema: analysis.status: failed. GET /v1/engine/status: jobs.dead | POST /v1/problems/{problem}/analyze |
| Liberar una alerta | alerts (release_by, released_at) | Cada pasada, hasta que se hace | Nunca | GET /v1/alerts | — |
| Una entrega de webhook | webhook_deliveries | 7: a 1 min, 5 min, 30 min, 2 h, 6 h, 12 h | status = 'failed', error | GET /v1/webhooks/{id}/deliveries?status=failed | POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/retry |
| Una hora por consolidar de nuevo | hours (status, attempts, next_attempt_at) | Siguiente pasada, luego 1, 5, 15, 30 min | Nunca dentro de 48 horas | GET /v1/engine/status: hours.failed | sypnia aggregate --from … --to … |
Por qué filas y no más colas:
- La fila se escribe en la transacción que la causa. Un problema nace y su tarea existe, o ninguna de las dos cosas. Un mensaje de cola enviado después de un commit se puede perder entre los dos; uno enviado antes puede anunciar un trabajo que se deshizo.
- Una fila se puede leer. «¿Qué está esperando, desde cuándo, cuántas veces se intentó, qué dijo?» es una consulta, y la API la responde. Una cola solo se puede contar.
- Nada más que desplegar. La forma de un solo proceso no tiene ningún servicio de colas, y el mismo código corre en las dos.
La tabla y el reclamo. Fíjate en la segunda condición del reclamo: una tarea running cuya reserva venció era de un worker que murió, y otro la toma.
CREATE TABLE jobs (
id text PRIMARY KEY, -- job_…
project_id text NOT NULL REFERENCES projects ON DELETE CASCADE,
kind text NOT NULL CHECK (kind IN ('analysis', 'daily', 'suggestions')),
subject text NOT NULL, -- el id del problema, el día, la semana
status text NOT NULL DEFAULT 'queued'
CHECK (status IN ('queued', 'running', 'done', 'dead')),
again boolean NOT NULL DEFAULT false, -- llegó un disparador mientras corría: correr una vez más
attempts integer NOT NULL DEFAULT 0,
next_attempt_at timestamptz NOT NULL DEFAULT now(),
leased_until timestamptz,
last_error text,
created_at timestamptz NOT NULL DEFAULT now(),
finished_at timestamptz
);
-- Una tarea abierta por sujeto: un segundo disparador enciende `again` en vez de insertar.
CREATE UNIQUE INDEX jobs_one_open ON jobs (project_id, kind, subject)
WHERE status IN ('queued', 'running');
CREATE INDEX jobs_due ON jobs (next_attempt_at) WHERE status = 'queued';-- $1 = clase, $2 = la reserva. Devuelve una tarea, o ninguna.
UPDATE jobs j
SET status = 'running', attempts = j.attempts + 1, leased_until = now() + $2
WHERE j.id = (
SELECT id FROM jobs
WHERE kind = $1
AND ((status = 'queued' AND next_attempt_at <= now())
OR (status = 'running' AND leased_until < now())) -- su worker murió
ORDER BY next_attempt_at
LIMIT 1
FOR UPDATE SKIP LOCKED)
RETURNING j.*;Una tarea que falla vuelve a queued con un next_attempt_at posterior, o pasa a dead en su tercera falla. En AWS el worker se llama a sí mismo para correr una tarea de inmediato; esa llamada es solo un atajo. Si se pierde, el tic de cada minuto encuentra la fila. Los reintentos propios de Lambda para esa llamada están apagados, porque la fila es el reintento.
Salud
Tres cosas responden «¿está funcionando?», de la más barata a la más completa.
GET /healthz
Pública, sin credencial. Responde 200 cuando el proceso está arriba y atendiendo, y a propósito no prueba Postgres ni el Bucket: una caída de la base de datos no debe sacar a la Ingesta de un balanceador, porque la Ingesta funciona sin la base de datos.
{ "status": "ok", "version": "1.0.0", "role": "all" }Vigílala desde fuera de la máquina donde corre el motor. Un motor caído no puede levantar su propia alerta.
GET /v1/engine/status
Con el token raíz Motor. El estado del procesamiento, de todos los proyectos. Es lo que imprime la revisión pipeline de sypnia doctor y con lo que se decide la alerta engine.failing.
{
"state": "ok",
"engine_version": "1.0.0",
"last_pass_at": "2026-03-12T10:34:10Z",
"lag_seconds": 21,
"rollup_lag_seconds": 190,
"segments": { "unscanned": 2, "unrolled": 5, "quarantined": 0 },
"hours": { "failed": 0 },
"jobs": { "queued": 1, "running": 1, "dead": 0 },
"alerts": { "held": 1 },
"webhook_deliveries": { "pending": 0, "failed": 0 },
"queue": { "waiting": 0, "oldest_seconds": 0, "dead_letter": 0 }
}| Campo | Significado |
|---|---|
lag_seconds | El número de frescura. La antigüedad del segmento más viejo que la vía rápida no ha revisado y que no está en cuarentena. En AWS, la antigüedad del mensaje más viejo de la cola de entrada cuando ese es más viejo. 0 cuando nada espera |
rollup_lag_seconds | La antigüedad del segmento más viejo que la consolidación aún no ha sumado |
state | ok: lag_seconds por debajo de 120 y rollup_lag_seconds por debajo de 600, las dos promesas. behind: por encima de cualquiera. failing: lag_seconds por encima de 1.800, o algo en cuarentena, una hora fallida durante 30 minutos, o un mensaje en la cola de mensajes fallidos |
queue | La cola de entrada. null en la forma de un solo proceso |
Por proyecto, la misma idea es data_through en GET /v1/summary, que cualquier token read puede llamar y que Sypnia Cloud muestra en la app Nube.
El objetivo de frescura. lag_seconds por debajo de 120 y rollup_lag_seconds por debajo de 600. El motor mide los dos en cada pasada y los escribe en su log; cuando cualquiera se queda por encima de 1.800 segundos crea la alerta engine.failing, que va a tu webhook como cualquier otra. El objetivo es una regla de diseño, verificada por las pruebas. Un porcentaje medido se publicará aquí cuando el motor haya corrido con volumen.
sypnia doctor
doctor prueba aquello de lo que depende el motor, una línea por cosa. Dos de sus revisiones son sobre esta página:
config ok 14 settings read, 0 unknown
database ok postgres 16.4, schema 12 (up to date), 3 ms
storage ok s3://sypnia-shop: put, get, delete, presign
address ok https://sypnia.example.com/healthz answered 200
pipeline ok last pass 12 s ago, lag 21 s, 0 quarantined, 0 failed hours, 0 dead jobs
queue ok intake 0 waiting, dead-letter 0
ai ok openrouter, model <model>: answered in 0.9 s
webhook skip SYPNIA_ALERT_WEBHOOK_URL is not set (alerts are recorded only)
clock ok 0.2 s from the database's clock
all checks passed| Revisión | Falla cuando | Imprime |
|---|---|---|
pipeline | Ninguna pasada terminó en los últimos 3 minutos; lag_seconds por encima de 120; un segmento en cuarentena; una hora fallida; una tarea dead | Cada segmento en cuarentena con su error, y la línea de sypnia aggregate que lo vuelve a procesar |
queue | La cola de entrada o su cola de mensajes fallidos no se pueden leer; la cola de mensajes fallidos no está vacía | Cuántos mensajes hay estacionados, y el comando de redrive. Se omite en la forma de un solo proceso |
clock | El reloj de la máquina está a más de 5 segundos del de la base de datos | Las dos horas |
Un número más es un número de salud y no solo una línea de log: problemas traducidos con source maps ÷ problemas que tenían versión y pila, en 24 horas. El sistema del que sale este motor pasó una vez seis días sin traducir nada y nadie lo notó. doctor lo imprime, y Agrupación de problemas lo explica.
Lo que no prometemos
- Los eventos que el motor nunca aceptó. Mientras la Ingesta no responde, un SDK guarda 500 eventos y reintenta; una pestaña que se cierra se lleva su cola; el último lote de una página, enviado cuando la página se oculta, se envía una sola vez. Un SDK de servidor reintenta y luego descarta. No hay almacenamiento en el dispositivo.
- Entrega exactamente una vez de un webhook. Es al menos una vez. Tu receptor recibe otra vez el mismo id
evt_…cuando un intento se repite; ignora un id que ya manejaste. - Los 2 minutos durante una caída. Las promesas de frescura valen mientras las piezas del motor están arriba. Durante una falla y justo después, los datos llegan tarde, tanto como duró la falla más lo que tarde en ponerse al día. No se pierden y no quedan mal.
- Los 2 minutos para un lote a cuyo worker lo mataron (AWS). Se entrega de nuevo cuando termina su tiempo de invisibilidad, hasta 15 minutos después.
- Los 10 minutos para una hora a cuyo worker lo mataron a mitad de la corrida. Otro worker toma la hora a los 20 minutos.
- Lo que escribió la gente, sin un respaldo de Postgres. Los estados, notas, reglas, llaves y tokens solo existen ahí. Los números y los problemas se pueden reconstruir desde el Bucket mientras la retención conserve los segmentos; más viejos que eso, no.
- Los eventos de un segmento en cuarentena, hasta que alguien lo vuelva a procesar. Están a salvo en el Bucket y no están en ningún conteo.
- El orden entre eventos de lotes distintos. Las líneas de tiempo se ordenan por la hora de los propios eventos, corregida por el reloj del dispositivo. Dos eventos separados por unos milisegundos en dos dispositivos pueden aparecer en cualquier orden.
- Una alarma cuando todo está caído en la forma de un solo proceso. Si el único proceso se detiene, nada dentro de él te puede avisar. Vigila
/healthzdesde otro lado. - Un límite a la caída de otro. Si tu proveedor de bucket o tu Postgres pierde datos que había confirmado, el motor no los puede devolver.
Qué cambió frente al sistema del que sale
| Allá | Aquí | Por qué |
|---|---|---|
| Un flujo de entrega administrado; un registro que fallaba se escribía bajo un prefijo de errores y nadie lo leía | Una cola con cola de mensajes fallidos, una alarma y un comando de redrive | Lo que se aparta debe ser visible y poderse volver a procesar |
| Una hora que fallaba dos veces no se volvía a intentar | Se intenta en la siguiente pasada, luego con esperas crecientes, durante 48 horas; una alerta a los 30 minutos | El incidente del 2026-09-30 |
| Una línea corrupta se volvía una fila de valores vacíos | Una línea que no se puede interpretar se cuenta y se salta; un segmento que no se puede leer queda en cuarentena tras 5 intentos | Una entrada mala solo debe costarse a sí misma |
| Una tarea para una sola app: nadie con quien ser justo | Turnos por proyecto en la vía rápida, un presupuesto de memoria por corrida, una parte del búfer | Muchos proyectos comparten un motor |
| La salud era una línea de log | /healthz, /v1/engine/status, sypnia doctor, la alerta engine.failing | Seis días sin traducir pilas, sin que nadie lo notara |
Sigue
-
Una implementación de referencia en AWS
Las mismas garantías, servicio por servicio: la cola, las funciones, las alarmas y lo que cuesta cada una. - El registro en detalle: cómo un contador se suma exactamente una vez.
-
Actualizaciones, respaldos y retención
Respaldar lo que solo guarda Postgres, y restaurarlo.