Instalación - Node.js

Antes de empezar, crea un proyecto en el panel de DockRay. En sus ajustes encontrarás el token del proyecto - el identificador público que forma parte de la URL de ingesta - y en la pestaña Claves de API generarás una clave privada. La clave se muestra una sola vez, al generarla: DockRay guarda únicamente su hash. Si todavía no tienes un proyecto, empieza por Primeros pasos.

Requisitos

• Node.js 18 o posterior - el paquete usa el fetch incorporado y no tiene dependencias,
• conexiones HTTPS salientes permitidas.

El paquete es una integración de servidor. No hay una versión para el navegador y no la habrá: autenticarse ante el panel requiere la clave privada del proyecto, y esa clave debe quedarse en el servidor. Los errores del navegador viajan a través de tu propia aplicación, no directamente a través de este paquete.

Instalación

npm install @dockcodes/dock-ray

Runtimes edge

El punto de entrada principal del paquete importa node:fs, node:os y node:zlib, que un bundle edge - middleware de Next.js, Cloudflare Workers, Vercel Edge - no puede resolver. Donde el código corre fuera de un proceso Node completo, importa el punto de entrada aparte:

import { DockRayClient } from '@dockcodes/dock-ray/edge';

La API es idéntica. Los eventos de este punto de entrada pierden el contexto de código fuente en la pila y la compresión gzip, porque el runtime no tiene sistema de archivos ni zlib; nada más cambia.

Creación del cliente

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

const ray = new DockRayClient({
    token: process.env.RAY_TOKEN,
    privateKey: process.env.RAY_PRIVATE_KEY,
    environment: process.env.NODE_ENV,
    release: process.env.APP_VERSION,
});

Sin token ni clave el constructor no lanza nada: ray.enabled devuelve false y cada llamada de reporte se resuelve en false sin intentar conectarse a la red. El paquete no lee ninguna variable de entorno por sí mismo: es tu propio código, como en el ejemplo anterior, el que decide de dónde vienen el token y la clave, así que el cliente puede crearse incondicionalmente y las credenciales quedan fuera del entorno local.

Reportar

try {
    await settle(order);
} catch (error) {
    await ray.captureException(error);
}

La primera prueba

await ray.captureMessage('Mensaje de control DockRay');

El mensaje debería aparecer en el panel, en la sección Errores del proyecto al que apunta el token.