Navegador
El paquete @chrom-ar/collector reporta los errores de tu aplicación en el navegador. Funciona con cualquier framework (React, Vue, Svelte, Angular, páginas sin framework), no tiene dependencias y pesa unos 6 KB comprimido. Esta página describe la versión 0.4.0.
Instalación
npm install @chrom-ar/collector
Lo antes posible en el punto de entrada de tu aplicación (main.ts, index.js, …), antes de que se dibuje:
import * as Collector from "@chrom-ar/collector";
Collector.init({
dsn: "https://clt_…@app.clt.chrom.ar", // de la puesta en marcha del proyecto
environment: "production",
release: "web@1.4.2",
});
Eso es todo. Desde ahora, los errores no atrapados y las promesas rechazadas sin manejar se reportan solos, con lo que pasó justo antes: clics, navegación, pedidos de red y mensajes de consola.
El DSN es público: solo puede mandar eventos, así que puede ir en el código del navegador. Sin DSN no se captura ni se manda nada, así que desarrollo y pruebas quedan en silencio si lo dejas afuera:
Collector.init({ dsn: import.meta.env.VITE_COLLECTOR_DSN });
environment y release son opcionales. Los problemas se cuentan por entorno, y release dice de qué despliegue vino un error.
Dominios nuevos
La primera vez que llegan eventos desde un dominio nuevo, Collector los guarda y pregunta a los administradores del proyecto si ese dominio es suyo. Si lo bloquean, las páginas de ese dominio dejan de mandar, y en la consola del navegador aparece una vez un aviso de [collector] diciendo que el dominio está bloqueado. Ver Dominios permitidos.
Política de seguridad de contenido
Si tu sitio manda una Content Security Policy, agrega el origen de tu DSN (esquema, host y puerto) a connect-src, junto a los que ya permites:
Content-Security-Policy: connect-src 'self' https://app.clt.chrom.ar
No hace falta nada más, con o sin medición de velocidad: todo sale con fetch o navigator.sendBeacon, que cubre connect-src, y no hace falta nada en script-src, porque el paquete va empaquetado con tu código y no carga scripts ni usa eval. Si connect-src no lo incluye, el navegador bloquea los pedidos y nada llega a Collector; Collector.test() lo dice.
Notas por framework
-
Next.js, Nuxt, SvelteKit y otros con renderizado en el servidor: importar el paquete en el servidor es seguro, e
initno hace nada ahí. Llámalo desde código que corre solo en el cliente (el efecto de un componente"use client", oinstrumentation-client.tsen Next.js). -
React: los errores que atrapa un error boundary no son "no atrapados", así que repórtalos tú desde
componentDidCatch, o desdeonCaughtErroren elcreateRootde React 19:createRoot(el, { onCaughtError: (error) => Collector.captureException(error) }); -
Vue: agrega
app.config.errorHandler = (error) => Collector.captureException(error);
Comprobar que funciona
const result = await Collector.test();
// { ok: true, id: "…" } o { ok: false, reason: "Collector rejected the key (HTTP 401)…" }
También escribe una línea en la consola. El evento es un error CollectorTest con la etiqueta collector.test: "true", y todas las pruebas se agrupan en un mismo problema. Con debug: true, también está en window.__collector.test(), para ejecutarlo desde la consola sin importar nada.
Reportar a mano
try {
await checkout(cart);
} catch (error) {
Collector.captureException(error, { tags: { step: "payment" } });
showRetry();
}
Collector.captureMessage("La pasarela de pagos está lenta", "warning");
Las dos devuelven el identificador del evento, o undefined si no se mandó nada.
Usuarios y etiquetas
Di quién tuvo el error, por su identificador (no datos personales), y agrega etiquetas para filtrar:
Collector.setUser({ id: currentUser.id });
Collector.setTag("plan", "pro");
setUser(null) borra el usuario al cerrar sesión. También están setTags(tags), addBreadcrumb({ message, category?, level? }), flush(timeoutMs?) (espera a que salgan los eventos en cola) y close() (quita todo lo que instaló el SDK).
Privacidad
Qué manda y qué deja afuera el SDK está en Seguridad y privacidad. beforeSend ve cada evento al final y puede cambiarlo o descartarlo:
Collector.init({
dsn: "…",
beforeSend(event) {
if (event.request) event.request.url = event.request.url.replace(/\/users\/\d+/, "/users/:id");
return event; // o null para descartarlo
},
});
Opciones
| Opción | Valor de entrada | |
|---|---|---|
dsn | ninguno | El DSN del proyecto. Sin él no se manda nada. |
environment | ninguno | "production", "staging", … |
release | ninguno | La versión de tu aplicación o el sha de git. |
debug | false | Escribe en la consola lo que hace el SDK, con el prefijo [collector]. |
enabled | true | false lo apaga todo. |
beforeSend | ninguno | (event) => event | null, para cambiar o descartar eventos. |
ignoreErrors | ruido del navegador | Textos (que coinciden en cualquier parte de "Tipo: mensaje") o expresiones regulares. Se suman a la lista incluida (ResizeObserver loop…, Script error.). |
inAppUrls | el mismo origen | Textos o expresiones regulares de las URL de scripts que son tu código. Ver abajo. |
stripQuery | true | Quita ?query y #hash de las URL. |
breadcrumbs | todo encendido | { console, dom, fetch, xhr, history }, cada uno true o false. |
maxBreadcrumbs | 50 | Cuántas cosas de "lo que pasó antes" guardar. |
autoCapture | los dos | { onerror, onunhandledrejection }, o false para ninguno. |
heartbeat | true | false apaga la señal diaria. |
rum | apagada | La medición de velocidad. Ver abajo. |
Velocidad de las páginas
La medición de velocidad muestra qué tan rápidas son tus páginas para quienes las usan: Web Vitals por página, los pedidos lentos y las visitas una por una, en la pestaña Velocidad. Viene apagada y es una importación aparte, así que las aplicaciones que no la usan no la descargan (unos 4,5 KB comprimido):
import * as Collector from "@chrom-ar/collector";
import { rum } from "@chrom-ar/collector/rum";
Collector.init({ dsn: "…", rum: rum({ sampleRate: 0.1 }) });
- Muestreo:
sampleRatees la parte de las pestañas que se miden, decidida una vez por pestaña. Una pestaña medida manda todas sus visitas a páginas. - Qué se mide: en las cargas de página, LCP, INP, CLS, TTFB y FCP; en las navegaciones dentro de la aplicación hacia una ruta nueva (pushState, LiveView), INP, CLS y un tiempo de navegación, desde el clic hasta que terminaron los pedidos de la página y el DOM quedó quieto medio segundo (hasta 10 s). Un cambio solo de query, como un filtro, sigue siendo la misma visita a la página. Además, los
fetchy XHR de la página, y para las páginas lentas, los recursos que más tardaron. - Cuándo manda: en lotes, cuando la pestaña se oculta o se cierra, y cada 10 visitas a páginas o 5 minutos mientras sigue abierta. Si Collector está caído o lento, se descartan sin reintentar.
- Privacidad: sin cookies, sin usuario, sin query ni fragmentos. Un identificador al azar de la visita y la decisión de muestreo se guardan en
sessionStorage(collector:rum) y terminan con la pestaña. Los errores de una pestaña medida llevan el identificador de la visita, así un problema enlaza a su visita. Si necesitas consentimiento para analítica es tu decisión. - Rutas: Collector agrupa las páginas adivinando qué segmentos son identificadores (
/orders/81→/orders/:id). Si tu router conoce la ruta, dísela después de cada navegación conCollector.setRoute("/orders/:id"), o pasaroute: (location) => …arum(). Las aplicaciones que enrutan con#hashlo necesitan: los fragmentos nunca se mandan, así que si no toda página sería/. - Cambiar o descartar visitas a páginas:
rum({ sampleRate, beforeSendPageview(pv) { … return pv; } }); devuelvenullpara descartar una.
Qué cuenta como tu código
El SDK marca un marco de la pila como tu código cuando su script está en el mismo origen que la página (o es un módulo de desarrollo de webpack) y no es un paquete de dependencias (node_modules, .vite/deps, chunks vendor, los chunks del framework de Next.js). Los hashes en los nombres de archivo se ignoran, así que un despliegue nuevo no abre problemas nuevos. Si tus scripts vienen de un CDN, dilo:
Collector.init({ dsn: "…", inAppUrls: ["https://cdn.example.com/app/"] });
Ver Cómo se agrupan los eventos.
Mapas de código fuente
Sube los mapas de cada build y Collector muestra tus archivos, líneas y funciones originales, y agrupa por ellos. Ver Mapas de código fuente.
Cómo se comporta
Nunca lanza errores dentro de tu aplicación, nunca la bloquea y no escribe en la consola salvo que algo esté mal configurado (o uses debug: true). Cuando un error se repite en un bucle, lo manda una vez; y manda como mucho 30 eventos cada 10 segundos por página.
Safari a veces omite marcos, así que el mismo error puede agruparse por separado en ese navegador. Para servidores, usa Node o Elixir.