Configuración - Nuxt
Opciones del módulo
Todo se define bajo la clave ray en nuxt.config.ts; las credenciales normalmente se sobrescriben con variables NUXT_RAY_*.
| Opción | Por defecto | Significado |
|---|---|---|
token, privateKey | - | credenciales del proyecto; sin ambas el módulo permanece en silencio |
url | https://dockray.io | instancia de DockRay |
environment | NODE_ENV | columna de entorno en el panel |
release | - | versión desplegada |
sampleRate | 1 | proporción de eventos de error enviados |
tracesSampleRate | 0 | proporción de transacciones enviadas; 0 desactiva la medición |
sendDefaultPii | false | adjunta la IP y el user agent |
ignorePaths | /_nuxt, /__nuxt, /health, /metrics | rutas nunca medidas |
browser.enabled | false | recoger errores de JavaScript |
browser.endpoint | /api/_ray/browser | ruta que los recibe |
browser.sampleRate | 1 | proporción de errores de navegador notificados |
Entornos
Cada entorno debería informar con un nombre inequívoco: production, staging, preview. El nombre es una columna del panel y un filtro de la lista de errores, así que sin él una caída de producción se ve igual que un error provocado en una prueba. Deja el entorno local sin credenciales: sin token ni clave la integración se carga y permanece en silencio, de modo que no necesitas desactivarla con una condición aparte.
Qué notifica el servidor
El módulo registra un plugin de Nitro en cuatro hooks:
| Hook | Hace |
|---|---|
request | marca la hora de inicio |
error | notifica errores del servidor no gestionados, etiquetados con la ruta encontrada |
afterResponse | cierra la transacción con el estado de la respuesta |
close | envía los informes pendientes antes de que termine el proceso |
Las transacciones salen en afterResponse, es decir, cuando la respuesta ya ha llegado al visitante - no se envía nada mientras espera. createError({ statusCode: 404 }) y cualquier otro 4xx es un error de quien llama, no una avería de la aplicación, así que solo se notifican los códigos 5xx.
Nombres de transacción
Una transacción toma su nombre de la ruta encontrada (GET /orders/:id, no GET /orders/8123), así que una ruta se queda en una sola fila del panel sin importar cuántos identificadores hayan pasado por ella.
Node, workers y edge
El mismo código funciona en Node y en workers: el evento se lee tanto a través de event.node.req como de la forma Request de Fetch, así que un despliegue en Cloudflare o Vercel Edge no necesita una segunda ruta de código.
Errores de Vue y JavaScript desde el navegador
Desactivado por defecto:
ray: {
browser: {
enabled: true,
},
}Eso registra la ruta de Nitro y el plugin de cliente. El navegador notifica a tu aplicación, nunca al panel: no tiene clave de proyecto, y dársela sería publicarla. El servidor reenvía cada aviso con su propia clave y rellena el sobre - entorno, versión, marca de tiempo -, así que el navegador nunca elige en qué entorno caen sus errores.
Vue traga los errores de los componentes en su propio manejador, así que window.onerror nunca los ve. Por eso el plugin conecta los dos hooks de Nuxt: vue:error para fallos de renderizado y ciclo de vida, app:error para un arranque fatal.
La ruta responde 202 a todo - un aviso válido, uno mal formado, uno rechazado por el límite - así que quien llama no aprende nada sobre las barreras. Descarta cuerpos de más de 16 KB y permite veinte avisos por dirección y minuto. El colector del navegador también se autolimita: un aviso por error distinto y vista de página, como máximo diez por vista de página por defecto, filtrando ResizeObserver loop y Script error. de origen cruzado.
Notificar a mano
window.DockRay?.captureException(error);
window.DockRay?.captureMessage('Checkout step skipped');Proteger la clave privada
La clave privada es un secreto del proyecto, no un identificador. Guárdala en variables de entorno, en un gestor de secretos o en la configuración del servidor: nunca en el repositorio, en los registros, en una captura de pantalla ni en código que llegue al navegador. Un proyecto puede tener varias claves, así que producción y preproducción deberían tener la suya: cada una se revoca por separado sin interrumpir a las demás. La sospecha de que una clave se ha filtrado ya es motivo suficiente para revocarla y generar otra.