Node
El paquete @chrom-ar/collector-node reporta los errores de tu servidor Node. Está pensado para Express y Next.js (runtime de Node) y funciona con cualquier servidor Node. Necesita Node 24 o más nuevo y no tiene dependencias. Esta página describe la versión 0.2.1.
Instalación
npm install @chrom-ar/collector-node
Dale a la aplicación desplegada el DSN del proyecto en la variable COLLECTOR_DSN y llama a init() antes de que arranque:
import * as Collector from "@chrom-ar/collector-node";
Collector.init(); // lee COLLECTOR_DSN, COLLECTOR_ENVIRONMENT, COLLECTOR_RELEASE
Eso es todo. Desde ahora, las excepciones no atrapadas y las promesas rechazadas sin manejar se reportan solas, con la solicitud en la que ocurrieron y lo que pasó justo antes: mensajes de consola y pedidos salientes.
Sin DSN no se manda nada, así que desarrollo y pruebas quedan en silencio si no defines COLLECTOR_DSN ahí. Las opciones de init() ganan sobre las variables de entorno:
Collector.init({ dsn: process.env.MI_DSN, release: "api@1.4.2" });
El entorno es COLLECTOR_ENVIRONMENT, o si no NODE_ENV tal cual. También manda una señal al arrancar y cada hora.
Express
Agrega el manejador de errores después de tus rutas:
const app = express();
// … tus rutas …
app.use(Collector.expressErrorHandler());
Reporta los errores que terminan en un 5xx (un error sin estado cuenta como 500) y después pasa el error, así tus propios manejadores siguen corriendo. Los errores con estado 4xx, como un "no encontrado", no son errores de tu código y no se reportan.
Next.js
En instrumentation.ts, en la raíz del proyecto (o en src/):
export async function register() {
if (process.env.NEXT_RUNTIME === "nodejs") {
const Collector = await import("@chrom-ar/collector-node");
Collector.init();
}
}
export { onRequestError } from "@chrom-ar/collector-node/next";
Reporta los errores de páginas, route handlers, server actions y middleware en el runtime de Node, con la ruta (next.route) y su tipo (next.route_type) como etiquetas. redirect(), notFound(), forbidden() y los demás errores que Next lanza a propósito no se reportan. Los errores del runtime Edge todavía no se reportan; ahí el paquete carga una versión que no hace nada.
Para el lado del navegador, instala también el SDK del navegador.
Comprobar que funciona
const result = await Collector.test();
// { ok: true, id: "…" } o { ok: false, reason: "Collector rejected the key (HTTP 401)…" }
O desde una terminal, con el mismo DSN: COLLECTOR_DSN=https://clt_…@app.clt.chrom.ar collector test.
Reportar a mano
try {
await charge(order);
} catch (error) {
Collector.captureException(error, { tags: { step: "payment" } });
return res.status(502).send("Falló el pago");
}
Collector.captureMessage("La pasarela de pagos está lenta", "warning");
Usuarios y etiquetas
Collector.setUser({ id: req.user.id }); // un identificador, no datos personales
Collector.setTag("plan", "pro");
Dentro de una solicitud, valen solo para esa solicitud: cada una tiene su propio usuario, sus etiquetas y su "lo que pasó antes", sin middleware que agregar. Fuera de una solicitud (al arrancar, en un trabajo), valen para todo lo que sigue.
Registros, solicitudes e inicios de sesión
El SDK también puede mandar lo que registra tu servidor, cada solicitud que atiende y sus intentos de inicio de sesión, para detectar ataques. Está apagado hasta que creas una clave de servidor y se la das al servidor como COLLECTOR_SERVER_KEY, junto a COLLECTOR_DSN. La clave solo se lee de esa variable.
Desde ahí, sin agregar nada:
- Solicitudes: una por cada solicitud que atienden los servidores HTTP de la aplicación, incluidos 404 y 500: método, ruta (sin query), estado, tiempo, IP del cliente, agente de usuario, tamaño. El patrón de ruta de Express (
/users/:id) se lee solo. Un segmento que coincide con un parámetro llamadotoken,passwordosecretse manda como:token,:passwordo:secret. - Líneas de
consoledesdeinfo.
pino y winston necesitan una línea cada uno:
const logger = pino(opts, pino.multistream([{ stream: process.stdout }, { stream: Collector.pinoStream() }]));
const logger = winston.createLogger({
transports: [new winston.transports.Console(), Collector.winstonTransport()],
});
(pino necesita su argumento de opciones, aunque sea {}, antes del stream). Las líneas por solicitud de pino-http y morgan no se mandan: las solicitudes ya las cubren.
Los inicios de sesión los reporta tu código de login:
Collector.signIn("failed", req.body.email, { req, method: "password", reason: "bad_password" });
Collector.signIn("succeeded", req.body.email, { req, method: "password", user: user.id });
method es password, magic_link, passkey, token u other; reason, unknown_account, bad_password, locked, expired_token u other. Dentro de una solicitud, req se puede omitir.
Collector.init({
logs: {
lines: true, // console, pino, winston
requests: true,
signIns: true,
level: "info",
skipPaths: ["/health", "/internal/*"], // exacta, o un prefijo terminado en /*
trustedProxies: ["10.0.0.0/8"],
},
});
logs: false lo apaga todo.
Un error atrapado mientras se atiende una solicitud lleva el identificador de esa solicitud, el mismo que mandan sus registros, así Collector enlaza el error con ellos.
- La IP del cliente: por defecto es la dirección conectada al servidor. Detrás de un balanceador o proxy, enumera sus direcciones en
trustedProxies:X-Forwarded-Forsolo se lee cuando la conexión viene de una de ellas, porque cualquiera puede mandar ese encabezado. - Límites: las solicitudes de Next.js no tienen patrón de ruta (Next no lo expone).
Caídas
El SDK nunca cambia si tu proceso vive o muere:
- Después de una excepción no atrapada, si tu aplicación no tiene su propio listener de
uncaughtException, imprime el error como lo haría Node, lo manda (esperando como mucho 2 segundos) y termina con código 1. Si tu aplicación tiene un listener, solo reporta y tu listener decide. - Una caída que termina el proceso se reporta con nivel
fatal; una que tu listener maneja, comoerror. - Las promesas rechazadas sin manejar siguen el modo
--unhandled-rejectionsde Node. exitOnUncaught: falsemantiene el proceso vivo después de una excepción no atrapada. Úsalo solo si sabes que el proceso puede seguir.
Al apagarse
El SDK manda lo que tiene en cola antes de que el proceso termine solo, pero no agrega listeners de SIGTERM ni SIGINT (cambiaría cómo se detiene tu aplicación). Si tienes tu propio hook de apagado, vacía ahí:
process.on("SIGTERM", async () => {
await server.close();
await Collector.flush(2000);
process.exit(0);
});
En funciones serverless, llama a await Collector.flush() antes de que el handler devuelva.
Líneas de código y mapas de código fuente
Cuando tu servidor ejecuta sus propios archivos (Node sin empaquetar, la mayoría de las aplicaciones Express), el SDK los lee del disco y manda las líneas: no hay nada que hacer.
Cuando el código del servidor está empaquetado (.next/server de Next.js, esbuild, tsup), sube sus mapas antes de desplegar, con la misma versión que reporta la aplicación:
collector upload .next/server --url-prefix /.next/server --release "$GIT_SHA"
Las rutas de archivo se mandan relativas a la raíz de la aplicación, así los mapas coinciden dondequiera que se despliegue. Si Node ya traduce las pilas (--enable-source-maps, o experimental.serverSourceMaps de Next), no hace falta subir nada. Ver Mapas de código fuente.
Opciones
| Opción | Valor de entrada | |
|---|---|---|
dsn | COLLECTOR_DSN | El DSN del proyecto. Sin él no se manda nada. |
environment | COLLECTOR_ENVIRONMENT, si no NODE_ENV | "production", "staging", … |
release | COLLECTOR_RELEASE | La versión de tu aplicación o el sha de git. |
debug | false | Escribe 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 | ninguno | Textos (que coinciden en cualquier parte de "Tipo: mensaje") o expresiones regulares. |
inAppPaths | fuera de node_modules | Textos o expresiones regulares de las rutas que son tu código; decide cómo se agrupan los errores. |
root | process.cwd() | La raíz de la aplicación; las rutas de archivo se mandan relativas a ella. |
stripQuery | true | Quita ?query y #hash de las URL de las solicitudes. |
breadcrumbs | todo encendido | { console, http }, cada uno true o false. |
maxBreadcrumbs | 50 | Cuántas cosas de "lo que pasó antes" guardar por solicitud. |
heartbeat | true | false apaga las señales. |
exitOnUncaught | true | Ver Caídas. |
logs | encendido con COLLECTOR_SERVER_KEY | Ver Registros, solicitudes e inicios de sesión. |
Otras funciones: setTags(tags), addBreadcrumb({ message, category?, level? }), signIn(outcome, account, opts?), pinoStream(), winstonTransport(), flush(timeoutMs?) y close(timeoutMs?).