Cómo está construido el motor
Todo 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.
En esta página
- El sistema completo
- La vida de una solicitud en 9 pasos
- Las reglas de diseño
- 1. Los eventos crudos son archivos, no filas
- 2. Postgres guarda solo lo que se lee seguido
- 3. Todo paso puede correr dos veces sin daño
- 4. Un solo binario
- 5. Cada fila y cada objeto lleva el proyecto
- Qué cambió frente al sistema del que sale
- Las páginas
Esta sección es el diseño del motor, escrito antes que su código. El código implementa exactamente lo que dicen estas páginas. Léela si operas el motor por tu cuenta, si quieres contribuir o si quieres saber por qué puedes confiar en un número de tu pantalla.
Todo lo que hay aquí es el motor de código abierto Motor. Sypnia Cloud ejecuta este mismo motor y le agrega una parte privada alrededor: cuentas, facturación, la app, la GitHub App y un modelo administrado para el agente. Donde una página toca alguna de esas piezas, lleva la insignia Nube.
El diseño no es nuevo. Es el sistema de observabilidad que funciona en producción desde el 2026-09-30 dentro de la primera app que usa Sypnia, ahora con varios proyectos, reescrito en Rust y más rápido: minutos donde el original espera una tarea de cada hora. Cada página dice qué se conservó, qué cambió y por qué.
El sistema completo
- Tu app envía lotes de eventos, cada 10 segundos.
- La ingesta los escribe en el bucket como objetos de segmento (NDJSON, gzip), y una fila de registro por segmento en Postgres.
- La vía rápida lee los segmentos nuevos cada 30 segundos.
- Escribe los problemas en Postgres.
- La consolidación lee la hora abierta cada 5 minutos. Escribe las cifras y el índice de sesiones en Postgres, y los archivos por sesión y Parquet de vuelta en el bucket.
- El agente lee un problema nuevo, que crece o que volvió, y escribe la frase.
- Las alertas quedan registradas, y se envían a tu webhook como un POST firmado.
- La API lee Postgres, y archivos del bucket. El servidor MCP y la Consola leen a través de la API.
- Tu agente de código le pregunta al servidor MCP. Tú lees la Consola o la API.
Hay dos almacenes y nada más:
| Almacén | Qué guarda | Por qué ahí |
|---|---|---|
| Bucket (cualquier almacenamiento compatible con S3) | Eventos crudos, archivos por sesión, fragmentos de grabación, capturas de página, source maps, Parquet | Se escribe una vez, se lee poco, es grande. Guardar un archivo no cuesta casi nada. |
| Postgres (15 o posterior) | Proyectos y llaves, problemas, números por hora y por día, el índice de sesiones, alertas, uso | Se lee en cada pantalla y en cada llamada de MCP, es pequeño y se actualiza en el sitio. |
Y cinco partes en movimiento, todas dentro de un solo binario:
| Parte | Trabajo | Cuándo corre |
|---|---|---|
| Ingesta | Revisa la llave y cada evento, escribe objetos de segmento en el Bucket | En cada solicitud de un SDK |
| Vía rápida | Lee los segmentos nuevos, encuentra fallas, crea y actualiza problemas | Cada 30 segundos |
| Consolidación | Cuenta todo lo demás, arma las sesiones, escribe Parquet | Cada 5 minutos; Parquet una vez al día |
| El agente | Lee un problema, escribe la frase, la causa y el prompt | Cuando un problema es nuevo, crece o vuelve |
| Alertas | Registra la alerta, llama a tu webhook | Cuando una regla se cumple |
La API, el servidor MCP y la Consola solo leen lo que esas partes escribieron. Nunca calculan.
La vida de una solicitud en 9 pasos
El ejemplo es el mismo de toda la documentación: una tienda cuya versión 4f2a91c renombró cart.total a cart.totalCents. El pago sigue leyendo el nombre viejo, así que los cobros salen sin monto.
-
Un cliente hace clic en Pagar. A las 09:12:04 la página llama a
POST /api/checkouty pasa un id de traza. El servidor llama al servicio de pagos, que responde400: falta el monto.@sypnia/noderegistra esa llamada fallida dentro de la traza. La página registra el clic, la solicitud fallida y el error que lanza. -
El SDK arma un lote. El SDK del navegador guarda los eventos en memoria y los envía cada 10 segundos, al llegar a 50 eventos o cuando la página se oculta. Un lote es un cuerpo JSON pequeño con un
batch_id. -
La Ingesta revisa y acepta. Motor Encuentra el proyecto de la llave de ingesta en una caché, revisa el origen, el tamaño y cada evento, sella
prjyrcv, y agrega las líneas a un búfer en memoria. Para esto no consulta Postgres. -
El Bucket recibe un segmento. En menos de 2 segundos el búfer se vuelve un objeto, y solo entonces la ingesta le responde al SDK. Los eventos ya están a salvo, pase lo que pase después.
Text prj_5k2m9x4q7w1z/events/production/dt=2026-03-12/hr=09/20260312T091216Z-7f3a9c.ndjson.gz -
La Vía rápida encuentra una falla nueva. Cada 30 segundos toma los segmentos que nadie ha revisado, los lee y se queda solo con las fallas. Encuentra una huella que nunca había visto en este proyecto y entorno:
88a44b15205cb153. -
Nace un problema. Una sola transacción escribe el problema, su primera ocurrencia, la persona y la sesión afectadas, y marca el segmento como revisado. En el ejemplo son las 09:13:02, 58 segundos después del clic. El presupuesto es 120.
-
El agente escribe la frase. Si configuraste un modelo, el agente arma un contexto (la falla, la pila con líneas de código, la traza, la versión, los conteos), llama al modelo y revisa la respuesta. El título técnico «createPayment answered 400 in POST /api/checkout» se vuelve «1 persona intentó pagar y no pudo. El botón Pagar no hace nada desde el cambio de ayer.»
-
Alertas. La transacción del paso 6 también escribió una alerta, retenida hasta que la frase esté lista o hasta que pasen 100 segundos desde que llegó la falla, lo que ocurra primero. Entonces se libera: queda registrada y se envía a tu webhook. Nube Sypnia Cloud además la envía por correo y la muestra en la app.
-
Tu agente de código lo lee. El desarrollador le pregunta a su agente qué está fallando. Este llama a la herramienta MCP
problemconpay-button-does-nothingy recibe la frase, la causa con su evidencia, la pila en el código original y el prompt. Nube En Sypnia Cloud el arreglo también puede llegar como pull request.
Mientras tanto, cada 5 minutos, la Consolidación cuenta el resto: la vista de página, el clic, el clic de rabia que sigue, cuánto tardó POST /api/checkout. Esos números están completos en 10 minutos.
Las reglas de diseño
Cinco reglas explican casi todas las decisiones de esta sección.
1. Los eventos crudos son archivos, no filas
Un evento se escribe una vez y casi nunca se vuelve a leer. Una fila en una base de datos paga índices, mantenimiento y memoria para siempre; una línea gzip en un bucket paga una fracción de centavo al año. El sistema del que sale este motor lo aprendió por las malas: su base de datos compartida se quedó sin memoria una vez, y los eventos crudos eran lo único que nunca estuvo en ella.
Los archivos también dan esquema al leer. Un evento conserva todos los campos con los que llegó, incluidos los que esta versión del motor no conoce. Un SDK más nuevo nunca rompe un motor más viejo.
El tipo que lee una línea carga esa regla. Fíjate en extra: atrapa lo que las estructuras de arriba no nombraron, y se escribe de vuelta sin cambios.
/// Una línea de un segmento. La etiqueta es el campo `type` del evento.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum Event {
SessionStart(Browser<SessionStart>),
Identify(Browser<Identify>),
PageView(Browser<PageView>),
PageLeave(Browser<PageLeave>),
Click(Browser<Click>),
RageClick(Browser<RepeatedClick>),
DeadClick(Browser<RepeatedClick>),
Vital(Browser<Vital>),
Request(Browser<Request>),
Error(Browser<ErrorEvent>),
Custom(Browser<Custom>),
FormInvalid(Browser<FormInvalid>),
ServerRequest(Server<ServerRequest>),
ServerError(Server<ServerError>),
/// Un `type` que esta versión no conoce. Se guarda y se compacta como
/// cualquier línea; lo saltan las partes que no saben leerlo. Nunca se rechaza.
#[serde(untagged)]
Unknown(serde_json::Map<String, serde_json::Value>),
}
/// Los campos que lleva todo evento del navegador, alrededor de los de su tipo.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Browser<T> {
#[serde(flatten)]
pub base: Base, // v, ts, env, ver, person, account, prj, rcv
pub sid: SessionId,
pub did: Option<DeviceId>,
pub url: Option<String>,
pub route: Option<Route>,
pub dev: Option<Device>,
#[serde(flatten)]
pub body: T,
/// Esquema al leer: todo campo no nombrado arriba, tal como llegó.
#[serde(flatten)]
pub extra: serde_json::Map<String, serde_json::Value>,
}2. Postgres guarda solo lo que se lee seguido
Problemas, números por hora, la lista de sesiones, alertas. Un millón de eventos se vuelve unos miles de filas. Por eso basta un Postgres pequeño, y por eso el motor no necesita un motor de consultas al lado: nada de lo que ves en pantalla se calcula desde eventos crudos en el momento en que lo pides.
3. Todo paso puede correr dos veces sin daño
Las funciones se reintentan, los procesos se mueren, las redes pierden respuestas cuando el trabajo ya estaba hecho. Por eso toda escritura del motor es de una de tres clases:
- sobrescribir con la misma llave: un segmento, un fragmento de grabación, un archivo por sesión;
- reemplazar: los números de una hora se borran y se escriben de nuevo, completos;
- sumar con un registro que lo protege: un contador sube en la misma transacción que anota de qué segmento vino, así que el mismo segmento nunca se suma dos veces.
Este es el upsert detrás de un problema. Los contadores suman, las fechas se ensanchan, el título queda como se vio la primera vez, y un problema resuelto se reabre solo.
INSERT INTO problems AS p
(id, project_id, environment, fingerprint, kind, origin, title, route,
first_seen, last_seen, first_release, last_release, occurrences, sample)
VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $11, $12, $13)
ON CONFLICT (project_id, environment, fingerprint) DO UPDATE SET
occurrences = p.occurrences + EXCLUDED.occurrences,
first_seen = LEAST(p.first_seen, EXCLUDED.first_seen),
last_seen = GREATEST(p.last_seen, EXCLUDED.last_seen),
last_release = COALESCE(EXCLUDED.last_release, p.last_release),
sample = COALESCE(p.sample, EXCLUDED.sample),
-- un problema resuelto que ocurre de nuevo vuelve; uno ignorado sigue ignorado
regressed = p.regressed OR p.status = 'resolved',
status = CASE WHEN p.status = 'resolved' THEN 'open' ELSE p.status END
RETURNING p.id, p.status, p.regressed, (xmax = 0) AS is_new;4. Un solo binario
La ingesta, la vía rápida, la consolidación, el agente, la API, el servidor MCP y la Consola son un solo programa, sypnia. En un servidor corre como un proceso largo. En AWS el mismo archivo corre como tres funciones. Los dos construyen el mismo Engine y solo difieren en qué lo despierta.
Fíjate en que el motor conoce cuatro cosas solo a través de traits. Cada una es una pieza que puedes cambiar: el almacén, la base de datos, el modelo y la manera en que sale una alerta.
/// Todo lo que el motor necesita del mundo exterior.
/// `serve` y las funciones de AWS construyen exactamente uno de estos.
pub struct Engine {
pub config: Arc<Config>,
pub store: Arc<dyn ObjectStore>, // S3, R2, MinIO, una carpeta en pruebas
pub db: Arc<dyn Database>, // Postgres
pub ai: Option<Arc<dyn AiProvider>>, // None hasta que pongas la llave de un modelo
pub sinks: Vec<Arc<dyn AlertSink>>, // el registro, luego tus webhooks
pub clock: Arc<dyn Clock>, // la hora real, o una hora grabada en pruebas
}
impl Engine {
/// Una pasada del worker: lo que `sypnia aggregate` corre una vez
/// y `sypnia serve` corre cada `processing.interval_seconds`.
pub async fn pass(&self) -> Result<PassReport, EngineError> {
let mut report = PassReport::default();
report.fast_path = fast_path::run(self).await?; // problemas, en menos de 2 minutos
report.alerts = alerts::release_due(self).await?;
report.uptime = uptime::run_due(self).await?;
if rollup::is_due(self).await? {
report.rollup = Some(rollup::run(self).await?); // números, en 10 minutos
}
Ok(report)
}
}5. Cada fila y cada objeto lleva el proyecto
Toda llave de objeto empieza con el id del proyecto. Toda tabla tiene project_id como primera columna de su llave primaria. No hay una tabla compartida de eventos, ni un prefijo compartido, ni una consulta que se pueda escribir sin un proyecto. Borrar un proyecto es borrar un prefijo y las filas de un id.
En el código, una llamada al almacén o a la base de datos no se puede hacer sin un Scope, así que olvidar el proyecto es un error de compilación, no una fuga.
/// `prj_` y 12 caracteres de [0-9a-z]. Barato de clonar, imposible de armar desde un texto cualquiera.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(try_from = "String", into = "String")]
pub struct ProjectId(Arc<str>);
impl TryFrom<String> for ProjectId {
type Error = InvalidId;
fn try_from(s: String) -> Result<Self, InvalidId> {
let ok = s.len() == 16
&& s.starts_with("prj_")
&& s[4..].bytes().all(|b| b.is_ascii_digit() || b.is_ascii_lowercase());
if ok { Ok(Self(s.into())) } else { Err(InvalidId::Project) }
}
}
/// A dónde pertenece un dato. Toda llave y toda consulta parte de uno.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Scope {
pub project: ProjectId,
pub env: Environment, // "production" cuando quien envía no nombra ninguno
}Qué cambió frente al sistema del que sale
| El original | El motor de Sypnia | Por qué | |
|---|---|---|---|
| Proyectos | Una app, dos entornos | Los que quieras; el proyecto va en cada llave y fila | Brief: varios proyectos desde la primera tabla |
| Frescura | Tarea cada hora, al minuto 20 | Vía rápida cada 30 s, consolidación cada 5 min | Las promesas de 2 y 10 minutos |
| Leer eventos crudos | DuckDB dentro de la tarea | Rust simple, en flujo | Sin motor de consultas externo; se van un binario de 68 MB y un techo de 1.200 MB |
| Escribir eventos crudos | Amazon Data Firehose, búfer de 60 s | El búfer propio del motor (2 s); una cola en AWS | Sin depender de algo que solo existe en AWS; un problema no puede esperar 60 s en un búfer |
| Tablas por hora | Reemplazar la hora | Igual | Probado |
| Contadores entre horas | Sumar, protegido por una corrida por hora | Sumar, protegido por un registro de segmentos | Las corridas ahora van cada pocos minutos y por proyecto |
| Lotes duplicados | Se guardaban dos veces | Se guardan una vez: batch_id | El incidente del 2026-09-30, cuando un error de CORS duplicó lotes |
| Huella | FNV-1a sobre unidades de código UTF-16 | Idéntica, bit por bit | Los grupos existentes no se deben partir |
| Identidad | Ids numéricos de usuario y club | Ids opacos de persona y cuenta | Brief §10.1 |
| Spans | Una lista plana de llamadas a la base de datos | Spans genéricos con padre, tipo y atributos | Brief §10.5, OTLP |
Las páginas
- Cada salto con su presupuesto de tiempo, qué espera y qué no, y cómo se cumplen los 2 y los 10 minutos.
- El bucket como árbol, el esquema de Postgres, tamaños por millón de eventos y lo que nunca se guarda.
- Llaves, orígenes, límites, el búfer, duplicados, y por qué la ingesta no consulta la base de datos.
- La consolidación sin motor SQL: agrupaciones en memoria, histogramas, sesiones, el registro, Parquet.
- La huella, calculada a mano; source maps; una solicitud, un problema; los estados de un problema.
- Disparadores, el contexto y su presupuesto, proveedores, la respuesta revisada, el prompt.
- El mismo binario como tres funciones de AWS o un proceso, cuánto cuesta cada uno y las piezas que puedes cambiar.
- Los crates, los traits principales, las reglas del código y cómo fluye una contribución.