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.
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
| Uso | Có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 viejas | Cada 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. |
| Filtrar | Los problemas, las sesiones y los números de rendimiento se pueden leer para una sola versión. |
| Source maps | Los 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:
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:
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 uploadcon--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ímite | Valor |
|---|---|
| Líneas de un stack que se traducen | Las primeras 30 |
| Tamaño de un source map | 64 MB. Uno más grande se rechaza, y sus líneas quedan como salieron del build. |
| Cuánto se guardan los source maps | 90 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
| Motor de SypniaCódigo abierto, en tu propia infraestructura | Sypnia CloudServicio pago, con un plan gratis | |
|---|---|---|
| Versiones, creadas solas o registradas | Sí. | Sí. |
| Source maps y stacks traducidos | Sí. 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ón | Lo 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, enconfirmPayment(), 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.