Saltar al contenido principal

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 como COLLECTOR_UPLOAD_TOKEN.
  • El DSN del proyecto en COLLECTOR_DSN, para saber dónde está Collector.
  • La CLI collector en tu integración continua.
  • La misma versión en la subida y en tu aplicación: el release que 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ónValor de entrada
--releaseCOLLECTOR_RELEASEObligatoria. La versión que reporta tu aplicación.
--dsnCOLLECTOR_DSNEl DSN del proyecto.
--url-prefix/La ruta URL en la que se sirve el directorio, como /static/.
--deleteapagadaBorra los .map (y los comentarios que apuntan a ellos) después de subirlos.
--dry-runapagadaLista 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.