Docs

Eventos

Qué le reporta tu app a Sypnia, qué lleva cada evento, cómo viajan los eventos y cuáles cuentan para un plan.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Los eventos al lanzar
  2. Desde el SDK del navegador
  3. Desde los SDK de servidor y OpenTelemetry
  4. Qué no es un evento
  5. Qué lleva cada evento
  6. Rutas sin ids
  7. Cómo viajan los eventos
  8. Ruido que el SDK nunca envía
  9. Qué eventos cuentan para un plan
  10. Ejemplo: un pago fallido, en eventos

Esta página es para quien quiere saber qué sale de su app. Vale igual para el motor de código abierto y para Sypnia Cloud: los SDK y el contrato de eventos son los mismos. El contrato en formato legible por máquinas es el esquema de eventos.

Un evento es una cosa que tu app le reportó a Sypnia: un error, un clic, una página que cargó, una petición y cuánto tardó. Todo lo que Sypnia te dice se construye con eventos.

Los eventos al lanzar

Desde el SDK del navegador

EventoSe envía cuandoQué lleva
Inicio de sesiónEmpieza una sesión.El navegador y el sistema operativo, el tamaño de la pantalla, la zona horaria y la página de la que venía la persona (dirección y ruta, sin su consulta).
IdentificaciónTu código llama a identify().El id de la persona y el id de la cuenta, y sus nombres y el correo de la persona si tu app los envía. Es el único evento que lleva un nombre o un correo. Mira Identificar personas.
Vista de páginaCarga una página, o la app navega a otra. Un cambio solo en la consulta o en el hash no es una vista de página.Cómo llegó la persona (una carga completa, una navegación o una redirección dentro de la app, atrás o adelante) y la ruta de la página anterior.
Salida de páginaLa persona navega a otro lado, oculta la pestaña o la cierra.El tiempo que pasó en la página y hasta dónde bajó, de 0 a 100.
ClicCualquier clic.Qué se tocó, en palabras: su etiqueta (el nombre accesible del control o su texto visible, hasta 80 caracteres), qué tipo de control es (botón, enlace, pestaña, campo…) y dónde estaba (el título del diálogo abierto o el encabezado más cercano). Nunca el valor de un campo.
Clic de rabia, clic muertoSe cumplen las reglas de Clics de rabia y clics muertos.Lo mismo que un clic, más el número de clics de la ráfaga.
Medición de rendimientoEl navegador reporta el LCP, el INP, el CLS o el TTFB de una página.El valor, su calificación y el elemento que hay detrás. Mira Rendimiento. El SDK también envía el FCP, que se guarda con los eventos crudos y no aparece en los números de rendimiento.
ErrorUn error que nadie atrapó, una promesa rechazada sin manejador, un error atrapado por la pantalla de error de tu framework, o un error que reportas tú.Su nombre, su mensaje (hasta 500 caracteres) y su stack (hasta 4.000 caracteres), con los correos reemplazados por [email].
PeticiónLa página llama a tu API, o a otra dirección que hayas listado, y recibe una respuesta, o ninguna.El método, la ruta, el estado, la duración y el id de la traza. En una llamada fallida, el código de error y el comienzo del mensaje de error de la respuesta (hasta 40 y 160 caracteres). Nunca el cuerpo de la petición ni el de la respuesta.
Falla de formularioEl navegador se niega a enviar un formulario porque un campo no es válido.La etiqueta del campo y el motivo (obligatorio, formato incorrecto, demasiado largo…). Nunca lo que se escribió.
Evento propioTu código llama a track(name, props).El nombre y las pocas propiedades que elegiste. Mira Navegador.

Desde los SDK de servidor y OpenTelemetry

EventoSe envía cuandoQué lleva
Petición del servidorTu servidor termina de atender una petición. Una petición que sigue corriendo a los 20 segundos se envía en ese momento como un registro parcial.El método, la ruta, el estado, la duración, la traza a la que pertenece y sus spans: hasta 200 llamadas a la base de datos, llamadas a otros servicios y pasos internos, cada uno con su nombre, su tipo, su inicio, su duración, su estado y un conjunto limitado de atributos. Mira Trazas.
Error del servidorSe lanza una excepción mientras se atiende una petición, falla una llamada que hizo la petición, la petición responde 500 o más, o tu código escribe en console.error durante una petición. Como máximo 5 por petición.El nombre, el mensaje, el stack y la traza a la que pertenece. El mensaje de una llamada fallida se depura antes de salir de tu servidor.

Un backend que reporta por OpenTelemetry envía spans, y el motor los convierte en estas mismas dos cosas.

Qué no es un evento

  • Las grabaciones y las capturas de página se suben aparte de los eventos y se cuentan como grabaciones. Mira Sesiones y grabación.
  • Los resultados de disponibilidad los produce el motor, no tu app. Mira Disponibilidad.

Qué lleva cada evento

CampoSignificado
HoraCuándo pasó, según el reloj de quien lo envía.
ProyectoLo decide la llave de ingesta, no el evento.
Entornoproduction, salvo que tu app diga otra cosa.
VersiónLa versión de tu app que lo envió, si tu app reporta una.
Sesión y dispositivoEl id de la sesión, y un id aleatorio que el SDK guarda en el almacenamiento del navegador para distinguir dispositivos. Ninguno identifica a una persona.
Persona y cuentaSolo si tu app llamó a identify(): el id de la persona, y el id de la cuenta, el equipo o la empresa a la que pertenece la persona en tu app. Los eventos llevan los dos ids y nada más sobre la persona; los nombres y los correos viajan una sola vez, en el evento de identificación. Mira Identificar personas.
PáginaSolo la ruta: sin dominio, sin consulta, sin hash. Y la ruta sin ids, que es la misma ruta con los ids reemplazados y la que se usa para agrupar.
PantallaEl tamaño del área visible y la clase de dispositivo: mobile por debajo de 768 píxeles de ancho, tablet por debajo de 1.024, y si no desktop.
IdiomaEl idioma de la página.

Rutas sin ids

Sypnia agrupa las páginas y las llamadas a la API por su ruta sin ids, así que /orders/8841 y /orders/8842 son la misma página. Un segmento de la ruta se vuelve :id cuando es todo dígitos, un UUID, una cadena hexadecimal de 16 caracteres o más, un token de 20 caracteres o más que contiene un dígito, o cuando contiene %.

Text
/orders/8841/receipt              ->  /orders/:id/receipt
/api/carts/7f3e2a1c9b4d4e5f8a6b   ->  /api/carts/:id
/checkout                         ->  /checkout

Cómo viajan los eventos

  1. El SDK del navegador pone los eventos en una cola en memoria y envía un lote cada 10 segundos, o apenas hay 50 esperando. Un lote lleva como máximo 200 eventos.
  2. Cuando la pestaña se oculta o se cierra, envía de inmediato lo que está esperando, de una forma que el navegador completa aunque la página se esté yendo.
  3. Un lote que falla por la red o porque el servidor está ocupado se vuelve a enviar, después de 1, 4 y 15 segundos; el lote lleva un id, así que un lote repetido no se guarda dos veces.
  4. La ingesta revisa cada evento por separado. Un evento que no es válido, o que tiene más de 7 días, se descarta y se cuenta en la respuesta; el resto del lote se guarda. Las cadenas demasiado largas se cortan, no se rechazan.
  5. La ingesta responde cuando los eventos ya están escritos en un lugar seguro, lo que tarda hasta 2 segundos. La respuesta dice cuántos eventos se guardaron.

Los SDK de servidor no esperan un lote: envían el registro de una petición cuando la petición termina.

La entrega es de mejor esfuerzo. La cola vive en memoria, guarda como máximo 500 eventos y no se conserva entre cargas de página. Cuando se desborda, primero salen los clics más viejos y al final los errores. Un navegador que se cuelga o que pierde la conexión para siempre puede perder sus últimos segundos.

Los eventos crudos conservan los campos que el motor no conoce. Un SDK más nuevo nunca rompe un motor más viejo.

Ruido que el SDK nunca envía

El SDK del navegador deja fuera los errores que no son de tu app:

  • Los errores que lanzan las extensiones del navegador, y los errores cuyo stack está entero en scripts de otros sitios.
  • Script error. sin detalle, que es lo que los navegadores reportan de los scripts de otros sitios.
  • El aviso ResizeObserver loop del navegador.
  • El mismo error otra vez dentro de 5 segundos: cuenta una sola vez.
  • Más de 20 errores en un minuto desde una misma página.

Qué eventos cuentan para un plan Nube

En Sypnia Cloud un plan incluye una cantidad de eventos al mes, para toda la organización. Cuentan tres tipos de evento:

Cuenta como un eventoCon precisión
Un errorCada error guardado, del navegador o del servidor.
Una trazaCada traza, una vez, tenga los spans que tenga. Una petición vista por el navegador y por tu servidor es una sola traza.
Una muestra de rendimientoUna vista de página con sus mediciones. El LCP, el INP, el CLS y el TTFB de una vista de página son una sola muestra.

Todo lo demás es gratis y no cuenta: inicios de sesión, vistas de página, salidas de página, clics, clics de rabia y clics muertos, fallas de formulario y eventos propios. Las grabaciones se cuentan aparte, como grabaciones al mes.

Cada proyecto tiene contadores de uso que puedes leer en cualquier momento, en la app y por la API. Lo que pasa cuando se llega a un límite está en Planes y límites. Un motor en alojamiento propio no tiene límites puestos por nosotros; puedes poner tus propias cuotas en su configuración.

Ejemplo: un pago fallido, en eventos

Un cliente de la tienda abre el checkout y hace clic en Pagar cinco veces. El pago se rechaza. En orden, el SDK del navegador envía:

#EventoDetalle
1Vista de páginaruta /checkout
2Medición de rendimientoLCP de 1.240 ms, bueno, elemento: el resumen del pedido
3Clicbotón «Pay $64.00», en «Your order»
4PeticiónPOST /api/checkout, estado 400, 412 ms
5Clic de rabiabotón «Pay $64.00», 5 clics
6Salida de página30 segundos, bajó hasta 100

El servidor de la API envía los spans de la misma traza, incluida la llamada rechazada al servicio de pagos. De todo esto, dos cosas cuentan para el plan: la traza, y la vista de página con su medición. Juntos se vuelven una ocurrencia del problema «3 personas intentaron pagar hoy y no pudieron».

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