Docs

Problemas

Qué es un problema, qué hace que dos fallas sean el mismo problema, y cuándo exactamente un problema es nuevo, crece, está resuelto, está ignorado o volvió.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Qué cuenta como falla
  2. Qué hace que dos fallas sean el mismo problema
  3. Una petición, un problema
  4. Qué cuenta un problema
  5. Estado: abierto, resuelto, ignorado
  6. Marcas: nuevo, creciendo, volvió
  7. La frase
  8. Qué queda dentro de un problema
  9. Ejemplo: el botón Pagar
  10. Referencia

Esta página es para quien lee la lista de problemas de Sypnia, y para quien construye sobre ella. La agrupación, los conteos y el estado son parte del motor de código abierto y funcionan igual en Sypnia Cloud. La frase en palabras simples necesita a el agente, que viene incluido en Cloud y usa tu propia llave de modelo en el motor.

Un problema es un grupo de fallas con una misma causa, contado en una frase. Sypnia dice «problema», nunca «issue». Cuatrocientas personas que chocan con el mismo error son un problema con cuatrocientas personas, no cuatrocientos correos.

Qué cuenta como falla

FallaCon precisión
Un error del navegadorUn 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ú.
Un error del servidorUna excepción lanzada mientras tu servidor atiende una petición, reportada por un SDK de servidor o por OpenTelemetry. Con los SDK de Node y de Next.js, también lo que tu código escribe en console.error mientras atiende una petición.
Una llamada fallidaUna llamada que falla sin lanzar un error: no recibe respuesta, responde 400, o responde 500 o más. Vale para la página que llama a tu API, y para tu servidor que llama a una base de datos o a otro servicio.
Un tiempo agotadoUna petición a tu servidor que sigue corriendo a los 20 segundos y nunca termina (SDK de Node y de Next.js).

Estas no son fallas, y nunca abren un problema por sí solas:

  • Respuestas como 401, 403, 404, 409 o 422. Por lo general es tu app diciendo que no a propósito: contraseña incorrecta, página que no existe, formulario inválido. Sypnia las cuenta en Rendimiento como llamadas rechazadas.
  • Los clics de rabia, los clics muertos y las fallas de formulario. Se muestran en sus propias páginas, se adjuntan a los problemas como evidencia y se usan en las sugerencias semanales.
  • Una página lenta o una llamada lenta. Mira Rendimiento.
  • Que tu app no responda en absoluto. Eso es una caída. Mira Disponibilidad.

Qué hace que dos fallas sean el mismo problema

Cada falla recibe una huella en el lugar donde ocurre, en el SDK. Las fallas con la misma huella, en el mismo proyecto y entorno, son el mismo problema.

Para un error, la huella se hace con tres cosas:

  1. El nombre del error, como TypeError.
  2. Su mensaje sin todo lo que varía: números, valores entre comillas, direcciones, UUID e ids largos. Order 8841 not found y Order 8842 not found son el mismo mensaje.
  3. La primera línea del stack que pertenece a tu propio código: su función y su archivo, sin los hashes que un build les agrega a los nombres de archivo. Las líneas de librerías, del runtime del framework y de extensiones del navegador se saltan.

Para una llamada fallida, la huella se hace con la llamada que falló (su nombre o su destino), cómo falló (el estado o el código de error), y el método y la ruta de la petición en la que ocurrió.

Para un tiempo agotado, es el método y la ruta de la petición.

Por eso el mismo error es un solo problema entre personas, navegadores, dispositivos y versiones. Un mensaje distinto o una línea distinta de tu código es un problema distinto.

Una petición, un problema

Una falla en el navegador y la falla que hay detrás en el servidor comparten una traza. Sypnia las guarda como un solo problema: la falla más profunda de la traza es el problema, y lo que vio la persona queda dentro como evidencia.

En la tienda, la llamada de la página a POST /api/checkout responde 400 porque, en el servidor, la llamada al servicio de pagos respondió 400. Eso es un solo problema, sobre la llamada de pago. Si la tienda tuviera solo el SDK del navegador, el problema sería la llamada fallida de la página.

Qué cuenta un problema

ConteoSignificado
OcurrenciasCuántas veces pasó la falla. El mismo error desde la misma página dentro de 5 segundos cuenta una sola vez.
PersonasLas personas identificadas, más una por cada dispositivo cuyas sesiones nunca se identificaron. Son las «3 personas» de la frase.
SesionesLas sesiones en las que pasó. Las fallas que solo vio tu servidor no tienen sesión.
Primera vez, última vezLa hora de la primera ocurrencia y de la más reciente.
Versión en la que se vio primeroLa versión de la primera ocurrencia. Así es como Sypnia dice «desde el cambio de ayer».

Un problema nuevo aparece dentro de los 2 minutos siguientes a su primer evento. Sus conteos están completos dentro de 10 minutos.

Estado: abierto, resuelto, ignorado

Un problema tiene exactamente un estado. Una persona lo cambia en la app o en la Consola; un token de API puede resolver y reabrir un problema con el alcance read, y necesita admin para ignorarlo. Sypnia cambia el estado por su cuenta en un solo caso: cuando un problema resuelto pasa otra vez.

EstadoSignificadoAlertasQué hace una ocurrencia nueva
AbiertoEstá pasando, o nadie ha dicho lo contrario. Todo problema empieza abierto.SíSe cuenta.
ResueltoAlguien dice que está arreglado.NoEl problema se reabre solo y queda marcado «volvió». Resolver antes de tiempo no tiene riesgo.
IgnoradoConocido y aceptado.NuncaSe cuenta. El problema sigue ignorado y nunca se reabre solo.

Puedes reabrir a mano un problema resuelto o ignorado en cualquier momento.

Sypnia no resuelve problemas por su cuenta. Un problema que deja de pasar sigue abierto, con una «última vez» más vieja, hasta que alguien lo resuelve.

Marcas: nuevo, creciendo, volvió

Además de su estado, un problema abierto puede llevar marcas. Sypnia las calcula; tú no las pones.

MarcaRegla
NuevoSu primera ocurrencia fue hace menos de 24 horas.
CreciendoEl número de personas afectadas llega al menos al doble de lo que era en su última alerta, y al menos a 5. La marca dura 24 horas.
VolvióEstaba resuelto, y pasó otra vez. La marca dura hasta que el problema se resuelve de nuevo.

Un ejemplo de «creciendo»: un problema alerta cuando es nuevo, con 1 persona. A las 5 personas está creciendo: el doble de 1, y al menos 5. Vuelve a crecer a las 10 personas, y después a las 20. Un problema que pasa de 1 persona a 3 no está creciendo: son menos de 5. Los dos números se pueden cambiar en las reglas de alerta del proyecto.

Cada marca crea una alerta cuando Sypnia la pone: una vez cuando el problema es nuevo, una vez cada vez que vuelve, y una vez por cada escalón de crecimiento. Mira Alertas y el resumen diario.

La frase

Antes de que el agente corra, un problema tiene un título técnico, armado a partir de la falla:

Text
createPayment answered 400 in POST /api/checkout

El agente corre cuando un problema es nuevo, cuando vuelve, cuando crece y cuando alguien pide un análisis nuevo. Lee la falla agrupada, el stack con las líneas del código fuente, lo que la persona hizo antes, la traza, la versión y qué cambió, y a cuántas personas y sesiones afectó. Escribe:

  • una frase en palabras simples, que pasa a ser el título del problema,
  • a quién afectó y desde cuándo,
  • la causa probable, con su evidencia,
  • qué hacer,
  • un nivel de confianza,
  • el prompt para tu agente de código.

El agente nunca lee los píxeles de una grabación ni lo que se escribió, y nunca mezcla código. Cómo funciona el análisis tiene los detalles.

El motor de Sypnia y Sypnia Cloud, comparados
Motor de SypniaCódigo abierto, en tu propia infraestructuraSypnia CloudServicio pago, con un plan gratis
Agrupación, conteos, estado, marcasSí.Sí.
La frase y el análisisCon tu propia llave de modelo. Hasta que pongas una, los problemas conservan su título técnico.Incluidos, hasta los análisis al día del plan.
El arregloEl prompt y el servidor MCP.El prompt y el servidor MCP. En los planes Builder y Team, también un pull request abierto por la GitHub App de Sypnia, una vez que enciendes los pull requests en el proyecto.

Qué queda dentro de un problema

  • Un ejemplo completo de la falla: mensaje, stack, página, versión. Con source maps el stack muestra tus propios archivos y líneas. Mira Versiones y source maps.
  • Sesiones recientes en las que pasó, con sus grabaciones.
  • La traza de una ocurrencia.
  • Las ocurrencias, las personas y las sesiones de cada día.

Los ejemplos, las sesiones y las trazas vencen con la retención de tus datos. El problema en sí, con su frase, su estado y sus conteos diarios, se guarda mientras exista el proyecto, para que Sypnia pueda decir «volvió» meses después. Mira Ubicación y retención de los datos.

Ejemplo: el botón Pagar

Ayer a las 18:40 la tienda desplegó la versión 4f2a91c, que cambió el nombre de cart.total a cart.totalCents. El checkout todavía lee el nombre viejo.

  1. Hoy, 09:12. Un cliente hace clic en Pagar. El servicio de pagos responde 400 porque falta el monto. Dentro de 2 minutos Sypnia abre un problema, marcado nuevo, con 1 persona. Sale una alerta.
  2. 09:14. El agente ya lo leyó. El título se vuelve una frase, y el problema nombra la versión 4f2a91c como la primera en la que se vio.
  3. Para las 16:00. Dos clientes más chocan con lo mismo. La misma llamada, la misma respuesta, la misma ruta: el mismo problema. Ahora dice «3 personas intentaron pagar hoy y no pudieron. El botón Pagar no hace nada desde el cambio de ayer.»
  4. 16:30. Mezclas el arreglo y marcas el problema como resuelto.
  5. Tres semanas después. Otro cambio vuelve a romper el monto. Llega la misma falla, el problema se reabre solo, marcado volvió, y sale una alerta nueva.

Referencia

Los campos de un problema y las llamadas para listar, leer, resolver e ignorar uno están en la referencia de la API. Cómo se construye la agrupación está en Agrupación de problemas.

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