Configuración - Node.js

Opciones que conviene conocer

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.

Cuándo salen los eventos

Un visitante nunca espera al servicio de monitorización. report() encola un envío sin esperarlo, manteniendo una referencia a la promesa para que el proceso no termine a mitad de vuelo:

ray.report(ray.captureException(error));

Los adaptadores de framework llaman a esto en un evento que solo se dispara después de enviar la respuesta. La cola guarda como máximo 50 informes simultáneos para todo el proceso; lo que exceda eso se descarta en silencio, sin entrada en el registro. sampleRate y tracesSampleRate deciden qué fracción de eventos llega siquiera hasta ahí: 1 envía siempre, 0 nunca, cualquier valor intermedio se sortea de forma independiente en cada llamada. Por defecto los errores salen completos y las transacciones no salen en absoluto.

Los adaptadores de Express y Fastify

Ambos adaptadores nombran las transacciones según el patrón de la ruta, no la dirección concreta - GET /orders/:id, no GET /orders/8123. Por defecto omiten /health y /metrics (ignorePaths), reportan solo las respuestas 5xx (shouldReport), eliminan Authorization, Cookie y X-Api-Key de las cabeceras y leen la IP de X-Forwarded-For o X-Real-IP.

import express from 'express';
import { rayRequestHandler, rayErrorHandler } from '@dockcodes/dock-ray/express';

const app = express();

app.use(rayRequestHandler(ray));      // antes de las rutas
// ... rutas ...
app.use(rayErrorHandler(ray));        // después de las rutas

rayRequestHandler abre una transacción y la reporta en el evento finish. rayErrorHandler reporta el error y lo pasa adelante: tu propia página de error se sigue renderizando.

import { rayPlugin } from '@dockcodes/dock-ray/fastify';

await fastify.register(rayPlugin, { client: ray });

El equivalente de finish en Fastify es onResponse: transacciones desde ahí, errores desde onError.

Errores del navegador

Un navegador no puede autenticarse directamente ante DockRay. Un informe que llegó a una de tus rutas se reenvía así:

app.post('/api/ray/browser', async (req, res) => {
    ray.report(ray.captureBrowserReport(req.body, {
        pageUrl: req.headers.referer,
        userAgent: req.headers['user-agent'],
    }));

    res.status(202).json({ success: true });
});

La carga no es de confianza: los campos no reconocidos se descartan, cada cadena se recorta a 1 KB, la pila a 50 frames, y lo que no se puede convertir en un evento devuelve false. El sobre - id, marca de tiempo, entorno, versión - se rellena aquí, en el servidor, así que un navegador nunca elige en qué entorno caen sus errores. El recolector del lado de la página es un punto de entrada aparte, @dockcodes/dock-ray/browser; las barreras del endpoint las escribes tú, igual que las integraciones de CMS ya incluidas.

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.