Saltar al contenido principal

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 llamado token, password o secret se manda como :token, :password o :secret.
  • Líneas de console desde info.

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-For solo 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, como error.
  • Las promesas rechazadas sin manejar siguen el modo --unhandled-rejections de Node.
  • exitOnUncaught: false mantiene 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ónValor de entrada
dsnCOLLECTOR_DSNEl DSN del proyecto. Sin él no se manda nada.
environmentCOLLECTOR_ENVIRONMENT, si no NODE_ENV"production", "staging", …
releaseCOLLECTOR_RELEASELa versión de tu aplicación o el sha de git.
debugfalseEscribe lo que hace el SDK, con el prefijo [collector].
enabledtruefalse lo apaga todo.
beforeSendninguno(event) => event | null, para cambiar o descartar eventos.
ignoreErrorsningunoTextos (que coinciden en cualquier parte de "Tipo: mensaje") o expresiones regulares.
inAppPathsfuera de node_modulesTextos o expresiones regulares de las rutas que son tu código; decide cómo se agrupan los errores.
rootprocess.cwd()La raíz de la aplicación; las rutas de archivo se mandan relativas a ella.
stripQuerytrueQuita ?query y #hash de las URL de las solicitudes.
breadcrumbstodo encendido{ console, http }, cada uno true o false.
maxBreadcrumbs50Cuántas cosas de "lo que pasó antes" guardar por solicitud.
heartbeattruefalse apaga las señales.
exitOnUncaughttrueVer Caídas.
logsencendido con COLLECTOR_SERVER_KEYVer 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?).