Docs

Versiones y source maps

Cómo sabe Sypnia de qué versión de tu app salió una falla, cómo dice «desde el cambio de ayer», y cómo los source maps convierten el código compilado de vuelta en el tuyo.

Aplica a MotorNube Al lanzar

Ver como Markdown
En esta página
  1. Versión (release)
  2. Para qué se usa una versión
  3. Source maps
  4. Las reglas
  5. Límites
  6. Motor y Cloud
  7. Ejemplo: el cambio de ayer
  8. Referencia

Esta página es para quien despliega la app. Las versiones y los source maps son parte del motor de código abierto y funcionan igual en Sypnia Cloud. Una parte cambia: en Cloud, la GitHub App de Sypnia puede leer de tu repositorio qué cambió entre dos versiones.

Dos cosas hacen que un problema sea útil en vez de desconcertante: saber con qué cambio empezó, y ver tu propio código en su stack en vez del archivo compilado. Las versiones dan lo primero, los source maps lo segundo. Las dos cosas son opcionales, y las dos toman unas pocas líneas en tu build.

Versión (release)

Una versión es una versión de tu app que publicaste. Se identifica con una cadena que tu app envía con cada evento. Usa el commit corto de git, como 4f2a91c: es único, y apunta al código.

Cómo llega a existir una versión:

  • Sola. La primera vez que un evento trae una versión que Sypnia no había visto en ese proyecto, la versión se crea. Su inicio es la hora de ese primer evento.
  • Desde tu build. Tu build puede registrar la versión cuando despliega, y agregar lo que el motor no puede saber: cuándo salió, el commit, la versión que había antes, y qué cambió desde entonces (los commits y los archivos que tocaron). Una versión registrada empieza a la hora que tú des, o a la hora en que la registraste, que es la hora del despliegue.

Las versiones pertenecen a un proyecto y a un entorno, y se ordenan por su inicio. Tu frontend y tu backend pueden enviar versiones distintas; cada evento conserva la suya.

Para qué se usa una versión

UsoCómo
«Desde el cambio de ayer»Un problema recuerda la versión de su primera ocurrencia. Si el problema nunca se vio en las versiones anteriores, esa versión es donde empezó.
Qué cambióEl agente lee lo que registraste para la versión: los mensajes de los commits y los nombres de los archivos que cambiaron, y sus diffs solo si tu build decidió enviarlos. En Sypnia Cloud, con la GitHub App instalada, lo que cambió también se puede leer de GitHub.
Pestañas viejasCada ocurrencia muestra su versión, y un problema resuelto con la versión que lo arregla no se reabre por fallas de versiones más viejas. Mira Problemas.
FiltrarLos problemas, las sesiones y los números de rendimiento se pueden leer para una sola versión.
Source mapsLos source maps se guardan por versión.

Un backend que reporta por OpenTelemetry define su versión con el atributo de recurso estándar service.version. Mira OpenTelemetry.

Si tu app no envía ninguna versión, todo sigue funcionando. Los problemas dicen entonces cuándo empezaron, y no con qué cambio.

Source maps

Un build convierte tu código en algo más pequeño. Un error en producción apunta entonces al archivo compilado:

Text
TypeError: Cannot read properties of undefined (reading 'toFixed')
    at o (https://yourapp.com/assets/checkout-3f9c.js:1:48211)

Un source map es el archivo que tu herramienta de build escribe para traducir eso de vuelta. Con los source maps de la versión, Sypnia muestra:

Text
TypeError: Cannot read properties of undefined (reading 'toFixed')
    at confirmPayment (src/checkout/checkout.tsx:142:18)

Las reglas

  • Súbelos en tu build, para una versión. Los source maps se guardan con el proyecto y la versión. Para subirlos hace falta un token de API con el alcance ci, que puede registrar versiones y subir source maps y nada más. Guárdalo en los secretos de tu CI.
  • Después quítalos de lo que publicas. Los source maps contienen tu código fuente. Sypnia nunca se los sirve a nadie: solo los usa para traducir stacks. La CLI hace los dos pasos, y registra la versión, con un solo comando: sypnia sourcemaps upload con --delete-after. Mira la referencia de la CLI y la guía Source maps en CI.
  • La traducción no cambia la agrupación. La huella de una falla se calcula en el SDK a partir del código compilado, sin los hashes del build, así que un problema es el mismo problema antes y después de subir los source maps. Los source maps cambian lo que lees, no lo que se agrupa.
  • Subirlos tarde no es grave. Cuando los source maps de una versión llegan después de una falla, los problemas de esa versión se traducen en ese momento. Si el agente ya analizó el problema sin ellos, pide un análisis nuevo: con las líneas del código fuente tiene más para leer.
  • Una línea sin mapa se queda como está. La traducción nunca hace fallar un problema. Traduce lo que puede.

Límites

LímiteValor
Líneas de un stack que se traducenLas primeras 30
Tamaño de un source map64 MB. Uno más grande se rechaza, y sus líneas quedan como salieron del build.
Cuánto se guardan los source maps90 días después de la última vez que se vio la versión

Estos límites vienen del sistema del que se extrajo Sypnia, donde un despliegue sube alrededor de mil source maps.

Motor y Cloud

El motor de Sypnia y Sypnia Cloud, comparados
Motor de SypniaCódigo abierto, en tu propia infraestructuraSypnia CloudServicio pago, con un plan gratis
Versiones, creadas solas o registradasSí.Sí.
Source maps y stacks traducidosSí. Los source maps se guardan en tu propio bucket.Sí. Los source maps se guardan en Sypnia Cloud, privados para tu proyecto.
Qué cambió en una versiónLo que registró tu build. El agente no puede leer tu repositorio.Lo que registró tu build, o lo que Sypnia lee de GitHub cuando la GitHub App de Sypnia está instalada.

Ejemplo: el cambio de ayer

El build de la tienda corre en cada despliegue. Después de compilar, registra la versión y sube sus source maps. Ayer a las 18:40 desplegó el commit 4f2a91c, registrado como el que sigue a 9c1e7b2, con la descripción «Rename cart.total to cart.totalCents».

Esta mañana falló el primer pago. La primera ocurrencia del problema trae la versión 4f2a91c, y la falla nunca se vio en 9c1e7b2 ni antes. Así que Sypnia puede decir más que «3 personas no pudieron pagar»:

  • Desde cuándo: el cambio de ayer, desplegado a las 18:40. Antes funcionaba.
  • Dónde: src/checkout/checkout.tsx:142, en confirmPayment(), gracias a los source maps.
  • Por qué: la versión cambió el nombre de cart.total, y la línea 142 todavía lo lee.

Sin una versión, el mismo problema diría «desde hoy, 09:12». Sin source maps, apuntaría a checkout-3f9c.js:1:48211.

Referencia

Registrar una versión y subir source maps: la referencia de la API y la referencia de la CLI. Definir la versión en tu app: Navegador, Node y Next.js.

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