Docs

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.

Aplica a Motor Al lanzar

Ver como Markdown
En esta página
  1. El sistema completo
  2. La vida de una solicitud en 9 pasos
  3. Las reglas de diseño
  4. 1. Los eventos crudos son archivos, no filas
  5. 2. Postgres guarda solo lo que se lee seguido
  6. 3. Todo paso puede correr dos veces sin daño
  7. 4. Un solo binario
  8. 5. Cada fila y cada objeto lleva el proyecto
  9. Qué cambió frente al sistema del que sale
  10. 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

Figura. El motor en una página. El camino encendido es la vía rápida: una falla se vuelve un problema en menos de 2 minutos. Todo lo demás lo cuenta la consolidación en 10.
  1. Tu app envía lotes de eventos, cada 10 segundos.
  2. La ingesta los escribe en el bucket como objetos de segmento (NDJSON, gzip), y una fila de registro por segmento en Postgres.
  3. La vía rápida lee los segmentos nuevos cada 30 segundos.
  4. Escribe los problemas en Postgres.
  5. 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.
  6. El agente lee un problema nuevo, que crece o que volvió, y escribe la frase.
  7. Las alertas quedan registradas, y se envían a tu webhook como un POST firmado.
  8. La API lee Postgres, y archivos del bucket. El servidor MCP y la Consola leen a través de la API.
  9. 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énQué guardaPor qué ahí
Bucket (cualquier almacenamiento compatible con S3)Eventos crudos, archivos por sesión, fragmentos de grabación, capturas de página, source maps, ParquetSe 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, usoSe 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:

ParteTrabajoCuándo corre
IngestaRevisa la llave y cada evento, escribe objetos de segmento en el BucketEn cada solicitud de un SDK
Vía rápidaLee los segmentos nuevos, encuentra fallas, crea y actualiza problemasCada 30 segundos
ConsolidaciónCuenta todo lo demás, arma las sesiones, escribe ParquetCada 5 minutos; Parquet una vez al día
El agenteLee un problema, escribe la frase, la causa y el promptCuando un problema es nuevo, crece o vuelve
AlertasRegistra la alerta, llama a tu webhookCuando 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.

Figura. Los nueve pasos en un reloj. La promesa son 2 minutos desde la primera falla hasta el problema y su alerta.
  1. Un cliente hace clic en Pagar. A las 09:12:04 la página llama a POST /api/checkout y pasa un id de traza. El servidor llama al servicio de pagos, que responde 400: falta el monto. @sypnia/node registra esa llamada fallida dentro de la traza. La página registra el clic, la solicitud fallida y el error que lanza.

  2. 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.

  3. 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 prj y rcv, y agrega las líneas a un búfer en memoria. Para esto no consulta Postgres.

  4. 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
  5. 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.

  6. 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.

  7. 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.»

  8. 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.

  9. Tu agente de código lo lee. El desarrollador le pregunta a su agente qué está fallando. Este llama a la herramienta MCP problem con pay-button-does-nothing y 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.

Figura. Las reglas 1 y 5 en una imagen: los eventos crudos siguen siendo archivos, solo los resultados se vuelven filas, y todos llevan su proyecto.

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.

crates/sypnia-core/src/event.rs
/// 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.

crates/sypnia-db/sql/problem_upsert.sql
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.

crates/sypnia/src/engine.rs
/// 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.

crates/sypnia-core/src/ids.rs
/// `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 originalEl motor de SypniaPor qué
ProyectosUna app, dos entornosLos que quieras; el proyecto va en cada llave y filaBrief: varios proyectos desde la primera tabla
FrescuraTarea cada hora, al minuto 20Vía rápida cada 30 s, consolidación cada 5 minLas promesas de 2 y 10 minutos
Leer eventos crudosDuckDB dentro de la tareaRust simple, en flujoSin motor de consultas externo; se van un binario de 68 MB y un techo de 1.200 MB
Escribir eventos crudosAmazon Data Firehose, búfer de 60 sEl búfer propio del motor (2 s); una cola en AWSSin depender de algo que solo existe en AWS; un problema no puede esperar 60 s en un búfer
Tablas por horaReemplazar la horaIgualProbado
Contadores entre horasSumar, protegido por una corrida por horaSumar, protegido por un registro de segmentosLas corridas ahora van cada pocos minutos y por proyecto
Lotes duplicadosSe guardaban dos vecesSe guardan una vez: batch_idEl incidente del 2026-09-30, cuando un error de CORS duplicó lotes
HuellaFNV-1a sobre unidades de código UTF-16Idéntica, bit por bitLos grupos existentes no se deben partir
IdentidadIds numéricos de usuario y clubIds opacos de persona y cuentaBrief §10.1
SpansUna lista plana de llamadas a la base de datosSpans genéricos con padre, tipo y atributosBrief §10.5, OTLP

Las páginas

  • Flujo de datos

    Cada salto con su presupuesto de tiempo, qué espera y qué no, y cómo se cumplen los 2 y los 10 minutos.
  • Almacenamiento

    El bucket como árbol, el esquema de Postgres, tamaños por millón de eventos y lo que nunca se guarda.
  • Ingesta

    Llaves, orígenes, límites, el búfer, duplicados, y por qué la ingesta no consulta la base de datos.
  • Agregación

    La consolidación sin motor SQL: agrupaciones en memoria, histogramas, sesiones, el registro, Parquet.
  • Agrupación de problemas

    La huella, calculada a mano; source maps; una solicitud, un problema; los estados de un problema.
  • El proceso del agente

    Disparadores, el contexto y su presupuesto, proveedores, la respuesta revisada, el prompt.
  • Formas de despliegue

    El mismo binario como tres funciones de AWS o un proceso, cuánto cuesta cada uno y las piezas que puedes cambiar.
  • El código

    Los crates, los traits principales, las reglas del código y cómo fluye una contribución.

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