Docs

Flujo de datos

Cada salto que da un evento dentro del motor, con su presupuesto de tiempo, qué espera a qué, cómo frena el motor, qué pasa cuando una pieza se cae y cómo se cumplen las promesas de 2 y 10 minutos.

Aplica a Motor Al lanzar

Ver como Markdown
En esta página
  1. Los saltos
  2. Qué es síncrono
  3. Dos relojes
  4. Cómo se cumplen los 2 minutos
  5. Cómo se cumplen los 10 minutos
  6. Grabaciones
  7. Contrapresión y la señal de «frena»
  8. Cuando una pieza se cae
  9. Qué cambió frente al sistema del que sale
  10. Sigue

Esta página sigue un evento por el motor, salto por salto, y le pone un número a cada uno. Es para quien opera el motor y para quien quiera comprobar que las promesas de frescura son aritmética y no esperanza.

Las promesas, de Cómo funciona:

  • un problema nuevo aparece, y puede alertar, en menos de 2 minutos desde su primer evento;
  • los conteos, los números de rendimiento y la lista de sesiones están completos en 10 minutos;
  • una grabación se puede ver cuando su sesión lleva 2 minutos inactiva, o terminó.

Los saltos

Figura. Los saltos y sus presupuestos. Sobre la línea el SDK está esperando; debajo, nadie. El Bucket es el punto donde un evento queda a salvo.
  1. Tu app envía un lote a la Ingesta, máximo cada 10 segundos.
  2. La Ingesta escribe un segmento en el Bucket, y luego responde 200 con lo que aceptó y lo que descartó.
  3. La Ingesta escribe la fila del registro del segmento en Postgres, después de responder.
  4. La Vía rápida lee los segmentos nuevos cada 30 segundos.
  5. Escribe el problema en Postgres y retiene su alerta.
  6. El agente toma la tarea y escribe la frase.
  7. Postgres libera la alerta hacia Alertas.
  8. La Consolidación lee la hora abierta cada 5 minutos y escribe números y sesiones.
  9. La API lee Postgres; el servidor MCP y la Consola leen a través de la API.
#SaltoQué pasaPresupuesto¿Síncrono?
1Tu app (SDK) → IngestaEl SDK del navegador envía cada 10 s, a los 50 eventos o cuando la página se oculta. Los SDK de servidor envían cuando termina una solicitud.10 s—
2Ingesta → BucketLlave, origen, tamaños, cada evento; las líneas esperan en un búfer y se escriben como un segmento.2 s en el búfer, 300 ms para la escrituraSí: la respuesta espera al objeto
3Ingesta → PostgresUna fila del registro que dice «este segmento existe».50 msNo: después de responder, con reintentos
4Bucket → Vía rápidaEl worker toma los segmentos que nadie revisó. En un solo proceso se despierta apenas cae un segmento.30 s (processing.interval_seconds)No
5Vía rápida → PostgresLeer el segmento, quedarse con las fallas, hacer upsert de problemas, registrar la alerta. Una transacción.5 sNo
6El agenteTraducir la pila con source maps, armar el contexto, llamar al modelo, revisar la respuesta.60 s (ai.timeout_seconds), menos si la alerta ya debe salirNo
7AlertasLiberar la alerta: marcarla, enviar el webhook.10 s por entrega (webhooks.timeout_seconds)No
8Bucket → Consolidación → PostgresReleer la hora abierta, reemplazar sus números, sumar a los contadores, escribir archivos por sesión.Empieza cada 5 min; 60 s por proyecto y horaNo
9Postgres → API, servidor MCP, ConsolaLecturas con índice. Los fragmentos de grabación y las trazas se traen del Bucket.300 ms para una listaSí, para quien lee

Solo el salto 2 hace esperar a alguien, y hace esperar al SDK a propósito: la respuesta 200 significa que los eventos están en el Bucket, no en la memoria de un proceso que puede morir. Todo lo que sigue puede fallar y volver a correr sin perder un evento, porque el segmento sigue ahí.

Qué es síncrono

Figura. El único tramo síncrono. La respuesta sale después de que el objeto existe y antes de escribir nada en Postgres.
  1. Tu app envía un lote: POST /v1/ingest/events con un batch_id y 6 eventos.
  2. Ingesta encuentra el proyecto en su caché de llaves y revisa el origen, los tamaños y cada evento. Sin consulta a la base de datos.
  3. Agrega las líneas al búfer. El búfer espera máximo 2 segundos y se comparte con los otros lotes del proyecto.
  4. Ingesta escribe el búfer en el Bucket como un solo segmento.
  5. El Bucket confirma que el objeto existe.
  6. Solo entonces Ingesta responde 200 con accepted: 6, dropped: 0.
  7. Después de responder, Ingesta escribe en Postgres la fila de registro del segmento, y reintenta hasta lograrlo.
Leer este diagrama como texto

Un diagrama de secuencia con cuatro líneas de vida y el tiempo hacia abajo: Tu app (SDK), Ingesta, Bucket y Postgres. El SDK espera desde el mensaje 1 hasta el 6; en el mensaje 7 ya se fue. Hay dos finales alternos, cada uno junto al paso que reemplaza: si el búfer está lleno, Ingesta responde 503 con Retry-After; si el Bucket rechaza la escritura, Ingesta responde 503 unavailable y el SDK reenvía el mismo batch_id tras 1 s, 4 s y 15 s.

Vale la pena notar tres cosas en la figura.

  • La respuesta es honesta. accepted cuenta eventos que ya están en un objeto. Si el Bucket rechaza la escritura, el SDK recibe 503 unavailable y envía el mismo lote otra vez con el mismo batch_id.
  • El búfer es compartido. Todos los lotes de un proyecto y entorno que llegan dentro de los mismos 2 segundos salen en un solo objeto. Un proyecto con mucho tráfico escribe como máximo 30 objetos por minuto, sin importar cuántos navegadores envíen.
  • Postgres no está en el camino. La fila del registro se escribe después de responder. Si Postgres está caído, la ingesta sigue aceptando y la fila se escribe más tarde.

En AWS una función no puede guardar un búfer entre solicitudes, así que el búfer es una cola: la ingesta responde cuando el lote está en la cola, y el worker escribe el segmento. El contrato es el mismo; el punto donde el dato queda a salvo pasa del Bucket a la cola por unos segundos. Mira Formas de despliegue.

Dos relojes

El motor lee los mismos segmentos dos veces, a dos velocidades, para dos trabajos distintos.

Figura. Dos relojes sobre los mismos archivos. La vía rápida responde «¿se rompió algo nuevo?» cada 30 segundos. La consolidación responde «¿cuánto hubo de todo?» cada 5 minutos.
Leer este diagrama como texto

Una línea de tiempo de 09:10 a 09:25 con tres filas. Arriba, los segmentos en el Bucket: los archivos llegan en momentos irregulares; el que se escribió a las 09:12:16 contiene el pago fallido. En el medio, la Vía rápida: una marca cada 30 segundos; la de las 09:12:30 revisa el segmento de las 09:12:16 y encuentra un problema nuevo, y entre la primera falla (09:12:04) y el problema (09:13:02) pasan 58 segundos, con un presupuesto de 120. Abajo, la Consolidación: una corrida a las 09:15, 09:20 y 09:25, y cada una relee toda la hora 09; el segmento del pago fallido se cuenta en la corrida de las 09:15, 2 minutos y 56 segundos después, con un presupuesto de 10 minutos. La Vía rápida escribe problemas, sus ocurrencias y a quién afectaron. La Consolidación escribe números de páginas y API, sesiones, clics, el índice de trazas y el uso.

Vía rápidaConsolidación
Pregunta¿Se rompió algo nuevo, y a quién le pasó?¿Cuánto pasó de todo?
LeeCada segmento nuevo, una vezToda la hora abierta, de nuevo, en cada corrida
Se queda conSolo fallas: errores, llamadas fallidas, tiempos agotadosTodos los eventos
Escribeproblems, problem_occurrences, problem_hits, alertsNúmeros por hora y por día, sessions, traces, usage_daily, archivos por sesión
Cada30 s5 min
Nunca escribeUn número de la consolidaciónUn problema

Dividir por tabla es lo que mantiene simples a las dos. Ninguna actualiza una fila que es de la otra, así que no hay nada que reconciliar entre ellas.

Esta es la vía rápida. Fíjate en el préstamo: un segmento se reserva por 2 minutos con una sola sentencia, se lee sin dejar una transacción abierta, y se marca como revisado en la misma transacción que escribe sus problemas.

crates/sypnia-pipeline/src/fast_path.rs
pub async fn run(engine: &Engine) -> Result<FastPathReport, EngineError> {
    let mut report = FastPathReport::default();
    held::promote_due(engine, &mut report).await?; // llamadas del navegador que esperaban su mitad del servidor

    // UPDATE … WHERE key = (SELECT … FOR UPDATE SKIP LOCKED LIMIT 1) RETURNING …
    // Dos workers nunca reciben el mismo segmento; el préstamo de un worker caído se vence.
    while let Some(segment) = engine.db.lease_unscanned_segment(LEASE).await? {
        let scope = segment.scope();
        let mut failures = FailureFold::new(&scope);

        let mut lines = engine.store.read_lines(&segment.key).await?;
        while let Some(line) = lines.try_next().await? {
            // Una línea que no se puede leer se cuenta y se salta. Nunca detiene el segmento.
            let Ok(record) = serde_json::from_slice::<Record>(&line) else {
                report.unreadable += 1;
                continue;
            };
            if let Some(failure) = Failure::from_record(&record) {
                failures.push(failure);
            }
        }

        let mut tx = engine.db.begin().await?;
        let fresh = tx.record_batches(&scope, &segment).await?; // los batch_id ya vistos se saltan
        let transitions = problems::apply(&mut tx, failures.only(&fresh)).await?;
        alerts::record(&mut tx, &transitions, engine.clock.now()).await?;
        tx.mark_scanned(&segment, fresh.skipped()).await?;
        tx.commit().await?; // problemas, alertas y registro avanzan juntos, o no avanzan

        agent::enqueue(engine, &transitions).await; // mejor esfuerzo; la siguiente pasada recoge lo que falte
        report.absorb(&segment, &transitions);
    }
    Ok(report)
}

Cómo se cumplen los 2 minutos

El reloj arranca cuando la falla ocurre en tu app. El peor caso es la suma del peor caso de cada salto.

SaltoUn proceso (serve)Funciones de AWS
El SDK retiene el evento10 s10 s
Búfer o cola2 s10 s (la ventana de agrupación de la cola)
Escritura del segmento0,3 s0,3 s
Espera de la vía rápida30 s (0 cuando ingesta y worker comparten proceso)0 s (la cola despierta al worker)
Revisión y transacción5 s5 s
El problema existe47,3 s25,3 s
Solo para una llamada del navegador que espera su mitad del servidor: retención15 s15 s
…y luego la siguiente pasada30 s60 s (la programación de cada minuto, si ningún tráfico despierta antes al worker)
El problema existe, caso retenido92,3 s100,3 s

Las dos columnas terminan por debajo de 120 segundos. La retención se explica en Agrupación de problemas: una llamada fallida vista por el navegador espera hasta 15 segundos la falla que hay detrás en el servidor, para que una solicitud sea un solo problema. Solo aplica a proyectos que también envían datos del servidor.

La alerta se escribe en la misma transacción que el problema, retenida. La libera lo que ocurra primero:

  1. el agente termina la frase;
  2. pasan 100 segundos desde que la falla llegó a la ingesta (110 desde que ocurrió, contando los 10 del SDK).

Así, con un modelo configurado, el agente tiene lo que quede de esos 100 segundos, normalmente más de un minuto. Sin modelo, la alerta se libera de inmediato, con el título técnico. En el peor caso retenido en AWS no queda tiempo para el modelo, y la alerta sale con el título técnico; la frase aparece en el problema cuando se escribe.

Si subes processing.interval_seconds por encima de 30, la primera columna crece lo mismo, y el doble en el caso retenido. Con 60, el caso retenido pasa de 2 minutos. Por eso el ajuste llega hasta 60 y su descripción te lo advierte.

Cómo se cumplen los 10 minutos

PasoPeor caso
El SDK retiene el evento10 s
Búfer y escritura2,3 s
Espera de la siguiente consolidación5 min
La consolidación de este proyecto y hora60 s
Números completos6 min 13 s
Margen para una corrida que falla y se repite en la siguiente pasada3 min 47 s

Una consolidación que falla no se reintenta cinco minutos después. rollup::is_due es verdadero en cada marca de 5 minutos y siempre que la última corrida de un proyecto no haya terminado, así que el reintento llega con la siguiente pasada de 30 segundos.

Dos detalles mantienen bien los números al cambiar de hora:

  • La hora de un segmento es la hora en que se escribió, no la que llevan sus eventos. Eventos enviados a las 09:59:58 pueden caer en la hora 10.
  • Una hora se relee hasta 10 minutos después de terminar, y luego se cierra. No puede existir un segmento escrito en una hora cerrada, porque los segmentos se escriben con la hora actual.

Grabaciones

Un fragmento de grabación no pasa por el búfer. Cada subida se escribe en el Bucket como su propio objeto antes de responder. La API lista los fragmentos de una sesión directamente del Bucket, así que una grabación se puede reproducir apenas existen sus fragmentos. El SDK sube el último fragmento cuando la página se oculta o la sesión queda inactiva; por eso la promesa dice «2 minutos inactiva, o terminada».

Un problema se enlaza con sus sesiones por problem_hits, que escribe la vía rápida. Por eso la grabación de la sesión detrás de un problema recién nacido se puede abrir desde la alerta, minutos antes de que esa sesión aparezca en la lista de sesiones.

Contrapresión y la señal de «frena»

El motor nunca descarta en silencio. Cada tipo de presión tiene una respuesta, y el SDK sabe qué hacer con cada una.

PresiónDónde se notaEl motor respondeEl SDK hace
Demasiadas solicitudes desde una dirección con una llaveIngesta, un contador en memoria429 rate_limited con Retry-AfterEspera y envía el mismo lote otra vez
El búfer de un proyecto está lleno (32 MiB esperando escritura)Ingesta503 unavailable con Retry-After: 2Reintenta tras 1 s, 4 s y 15 s con el mismo batch_id; guarda máximo 500 eventos, los más viejos salen primero
El Bucket rechaza escriturasIngesta503 unavailableLo mismo
El proyecto llegó a su límite de eventosLa respuesta de cada lote y de /v1/ingest/config200 con slow_down: { send: "failures" }; los demás eventos se cuentan en dropped_reasons.limit_reachedEnvía solo errores y solicitudes fallidas hasta until
El proyecto llegó a su límite de grabacionesLo mismoslow_down: { replay: false }; los fragmentos reciben 429 limit_reachedDeja de grabar hasta until
El worker va atrasadoEl registro: segmentos sin revisar, horas sin consolidarNada cambia para los SDK. A los 30 minutos, una alerta engine.failing—
Postgres no tiene conexiones libresAPI503 con Retry-After: 2Tu cliente reintenta

El estado de «frena» se decide lejos de la solicitud. La consolidación cuenta el uso; una pasada lo compara con los límites y escribe el resultado en el proyecto; la ingesta lo lee de su caché. Fíjate en que la función de abajo es pura: los mismos contadores dan siempre la misma respuesta, así que es trivial de probar y segura de correr en cada pasada.

crates/sypnia-core/src/quota.rs
/// Lo que los SDK deben retener. `None` cuando el proyecto está dentro de sus límites,
/// que es siempre el caso cuando un límite es 0 (sin límite: el valor de un motor propio).
pub fn slow_down(usage: &Usage, limits: &Limits, period_end: DateTime<Utc>) -> Option<SlowDown> {
    let events_over = limits.events_per_month > 0 && usage.events >= limits.events_per_month;
    let replays_over = limits.replays_per_month > 0 && usage.replays >= limits.replays_per_month;

    match (events_over, replays_over) {
        (false, false) => None,
        (true, _) => Some(SlowDown {
            reason: SlowDownReason::EventsLimit,
            // Las fallas siempre se aceptan, así los problemas se siguen encontrando.
            send: Send::Failures,
            replay: false,
            until: period_end,
        }),
        (false, true) => Some(SlowDown {
            reason: SlowDownReason::ReplaysLimit,
            send: Send::All,
            replay: false,
            until: period_end,
        }),
    }
}

Cuando una pieza se cae

CaídaQué sigue funcionandoQué se detieneQué se pierdeRecuperación
IngestaLeer: API, servidor MCP, ConsolaRecibirLos eventos que el SDK no alcance a guardar: conserva 500 y reintenta tres vecesNo hace falta
BucketListas y problemas, desde PostgresRecibir (503), grabaciones, líneas de tiempo de sesiones, trazasNada de lo aceptado; los SDK reintentan como arribaNo hace falta
PostgresRecibir: la ingesta usa su caché y sigue escribiendo segmentosLa vía rápida, la consolidación, la API (503), llaves nuevasNada. Los segmentos esperan en el BucketSe escriben las filas del registro que quedaron pendientes; luego el worker se pone al día, de lo más viejo a lo más nuevo
El workerRecibir y leerProblemas nuevos, números, alertas, chequeos de disponibilidadNadaAl arrancar revisa todo lo no revisado y consolida cada hora abierta de las últimas 48 horas
El proveedor de IATodo lo demásLa fraseNada. analysis.status queda en failed tras tres intentosSe intenta de nuevo cuando el problema crece, o a pedido
El receptor de tu webhookTodo lo demás; las alertas se siguen registrandoEsa entregaNada mientras duren los reintentosLas entregas se reintentan con esperas cada vez más largas; una alerta engine.failing si siguen fallando

Dos reglas hacen corta esta tabla:

  • El Bucket es la fuente de la verdad. Todo lo que hay en Postgres y viene de eventos se puede reconstruir desde los segmentos, con sypnia aggregate --from … --to …. Las excepciones son lo que escribieron las personas: estados, notas, reglas, llaves.
  • Una llave revocada sigue rechazada durante una caída de Postgres, y una llave válida sigue funcionando. La caché conserva su última copia buena hasta una hora sin refrescarse. Después, la ingesta responde 503 en vez de adivinar.

Qué cambió frente al sistema del que sale

AlláAquíPor qué
Una tarea cada hora, al minuto 20, hace todoUna vía rápida cada 30 s y una consolidación cada 5 minLas promesas de 2 y 10 minutos
Un búfer administrado de 60 s o 5 MB delante del bucketEl búfer propio del motor, de 2 s o 4 MiB60 s es la mitad del presupuesto de 2 minutos; y el despliegue propio no puede depender de un servicio que solo existe en AWS
La respuesta salía antes de confirmar la escrituraLa respuesta espera al objetoPara que accepted sea verdad
Una hora fallida se reintentaba con una ventana de 48 horasLa misma ventana de 48 horas, más un reintento inmediatoSe conserva; fue lo que salvó horas allá

Sigue

Secciones

Empieza aquíQué es Sypnia, cómo funciona, qué es código abierto y qué es la nube de pago, y las dos maneras de recibir tu primer problema en palabras claras.ConceptosLas diez ideas de las que está hecho Sypnia, cada una definida con precisión, desde un proyecto y sus llaves hasta los problemas, las trazas y las alertas.SDKCómo envía tu app los datos a Sypnia. Un SDK para el navegador, uno para Node, uno para Next.js, y la entrada de OpenTelemetry para cualquier otro backend.El agenteCómo analiza Sypnia un problema, qué escribe, qué le envía a un modelo y qué nunca hace.MCP y skillsConecta tu agente de código a Sypnia para que pregunte qué está fallando en producción, lea lo que necesita para arreglarlo y configure Sypnia por ti.Referencia de la APILa API HTTP de Sypnia: una sola API para el motor de código abierto y para Sypnia Cloud, con cada endpoint, parámetro, respuesta y error.Referencia de la CLIEl comando sypnia: cómo instalarlo, qué variables lee, qué significan sus códigos de salida y dónde está documentado cada comando.Alojamiento propioQué corres cuando alojas tú mismo el motor de Sypnia, qué necesitas, cuánto cuesta y qué no tienes frente a Sypnia Cloud.Cómo está construido el motorTodo el motor de Sypnia en una página, desde un clic en tu app hasta la frase que lee tu agente de código, con las reglas de diseño y el código que las sostiene.Sypnia CloudCómo funciona el servicio pago, desde las organizaciones y los roles hasta los planes, los límites, la facturación, dónde viven tus datos, la GitHub App y el soporte.Privacidad y seguridadQué recoge Sypnia de tu app y de sus usuarios, qué no recoge nunca, cómo funciona el enmascarado, cómo eliminar datos y cómo se protege el servicio.LicenciasQué licencia cubre cada parte de Sypnia, qué puedes hacer con ella, cómo se puede usar el nombre, y los términos de una contribución.GuíasRecetas paso a paso para las formas comunes de usar Sypnia, desde apps hechas con constructores de IA y Next.js en Vercel hasta Supabase, source maps en CI, correos de alerta desde tu propio motor, y venir desde Sentry.ReferenciaLas páginas donde se consulta, desde el esquema de eventos y el glosario hasta lo planeado, el registro de cambios y las preguntas frecuentes.
↑↓ para moverte↵ para abrirEsc para cerrar