Mapas de código fuente
El código que llega al navegador suele estar minificado, así que su pila de llamadas apunta a /assets/index-a1b2c3d4.js:1:48213 in e. Si subes los mapas de código fuente de cada build, Collector muestra src/cart/coupon.ts:5 in applyCoupon, con las líneas de alrededor, y agrupa los errores por tu código original: un build nuevo no abre problemas nuevos. Lo mismo vale para un servidor Node empaquetado.
Lo que hace falta
- Una credencial de subida (
cltu_…), guardada en los secretos de tu integración continua comoCOLLECTOR_UPLOAD_TOKEN. - El DSN del proyecto en
COLLECTOR_DSN, para saber dónde está Collector. - La CLI
collectoren tu integración continua. - La misma versión en la subida y en tu aplicación: el
releaseque manda el SDK.
Subir
Antes de desplegar: los eventos de una versión cuyos mapas todavía no se subieron quedan minificados.
collector upload ./dist --release "$GIT_SHA"
La CLI busca cada archivo .map bajo el directorio y lo empareja con su bundle (por el comentario sourceMappingURL, el campo file del mapa o el nombre). Solo sube los mapas, no el código minificado. Avisa si un mapa no tiene sourcesContent (sin él no hay líneas de código que mostrar) y saltea los de más de 20 MB.
| Opción | Valor de entrada | |
|---|---|---|
--release | COLLECTOR_RELEASE | Obligatoria. La versión que reporta tu aplicación. |
--dsn | COLLECTOR_DSN | El DSN del proyecto. |
--url-prefix | / | La ruta URL en la que se sirve el directorio, como /static/. |
--delete | apagada | Borra los .map (y los comentarios que apuntan a ellos) después de subirlos. |
--dry-run | apagada | Lista lo que subiría, sin mandar nada. |
En vez de credencial de subida y DSN, también sirve una credencial de acceso de un propietario o administrador del proyecto, con --org y --project. Si hay credencial de subida, siempre gana.
Volver a subir la misma versión y ruta reemplaza ese mapa, así que reintentar es seguro.
Con Vite
Define la versión al construir y deja los mapas fuera del bundle; después súbelos y bórralos:
// vite.config.ts
export default defineConfig({
define: { __COLLECTOR_RELEASE__: JSON.stringify(process.env.GIT_SHA) },
build: { sourcemap: "hidden" },
});
vite build && collector upload ./dist --release "$GIT_SHA" --delete
El SDK del navegador lee __COLLECTOR_RELEASE__ si no le pasas release en init. Con webpack: new DefinePlugin({ __COLLECTOR_RELEASE__: JSON.stringify(sha) }).
Con Next.js
El código del servidor de Next.js también va empaquetado:
collector upload .next/server --url-prefix /.next/server --release "$GIT_SHA"
Ver Node.
Cómo se aplican
Cuando llega un evento, cada marco con línea y columna se busca por la versión del evento y la ruta del archivo. Solo cuenta la ruta: de una URL completa se descartan el origen, la query y el fragmento, así https://cdn.example.com/assets/app.js?v=2 coincide con /assets/app.js. Los mismos mapas sirven para todos los entornos de una versión.
Un marco traducido muestra el archivo, la línea y la columna originales, con su código, y cuenta como tuyo salvo que esté bajo node_modules o deps.
Los mapas no se aplican a los eventos que llegaron antes que ellos, pero Collector vuelve a agrupar esos eventos por el código original, y si eso hace coincidir dos problemas, los une. La página de un problema avisa cuando faltan los mapas de su versión.
Los detalles del formato de subida están en el protocolo.