Verificación y problemas habituales - Node.js
Un evento controlado
await ray.captureMessage('Mensaje de control DockRay');Los métodos de reporte devuelven una promesa: en un script que termina justo después de la llamada, antepón await o envuélvela en ray.report(), o el proceso podría cerrarse antes de que la petición salga.
Problemas habituales
ray.enabled es false aunque las variables estén definidas
El cliente nunca lee process.env por sí mismo: las credenciales siempre llegan al constructor de forma explícita, como en los ejemplos de este apartado. Comprueba que token y privateKey realmente llegaron como cadenas no vacías; una cadena vacía cuenta igual que la ausencia de valor.
El build no compila en un runtime edge o en Cloudflare Workers
El síntoma suele ser un error del bundler del tipo «Module not found: Can't resolve 'node:fs'». El punto de entrada principal del paquete importa node:fs, node:os y node:zlib, que un bundle así no puede resolver. Importa @dockcodes/dock-ray/edge en lugar del punto de entrada principal: la API se mantiene igual, solo desaparecen el contexto de código fuente en la pila y la compresión gzip.
installGlobalHandlers() no hace nada hasta que lo llamas
Capturar fallos de proceso no atrapados está desactivado por defecto: hay que activarlo de forma consciente, porque cambia cómo termina el proceso ante un error fatal. Tras llamar a ray.installGlobalHandlers(), una uncaughtException reportada termina con una llamada a process.exit(1), a menos que pases { exitOnUncaught: false }. Una unhandledRejection solo se reporta y no termina el proceso.
Algunos eventos desaparecen con mucha carga
La cola de report() guarda como máximo 50 informes simultáneos para todo el proceso; lo que exceda eso se descarta sin rastro en el registro. Revisa también sampleRate si se ha bajado: por defecto vale 1 y envía todo.
Las transacciones se fragmentan en miles de filas distintas
El nombre de una transacción proviene del patrón de ruta registrado en el enrutador (req.route.path en Express, routerPath en Fastify). Si el adaptador actúa sobre una petición que nunca llegó a un manejador registrado - una respuesta 404, un middleware colocado antes del enrutador -, no hay patrón que usar y el nombre cae a la ruta en crudo de la dirección, así que cada dirección distinta se convierte en su propia fila.
Los códigos 4xx no llegan al panel como errores
Es el comportamiento esperado del shouldReport por defecto: solo se reportan las respuestas 5xx, porque un 4xx suele ser un error de quien llama, no un fallo de la aplicación. Pasa tu propia función shouldReport al adaptador para cambiar esto.
El panel responde 200 pero no aparece el evento
Una respuesta 200 {"success": false} significa que la cuenta ha agotado su cupo mensual de errores. La integración no lo trata como una avería, y hace bien. El cupo se ve en el panel de la cuenta; hasta fin de mes se calcula a partir del consumo registrado, así que borrar errores no lo reinicia.
Sigue sin funcionar
Repasa la lista de comprobación de falta de datos y, si no ayuda, escríbenos. Indica el nombre del proyecto, la versión de la integración y la hora aproximada de la prueba: acorta el camino a la respuesta.