Instalar por plataforma
Node.js
Instalar npm install @blipit/node
@blipit/node captura por sí solo las excepciones no controladas y los rechazos de promesas no gestionados, añade handlers para Express y Fastify, y envía logs e intentos de inicio de sesión con la misma clave. Usa la clave secreta; se queda en el servidor. Desde la 0.3 también ofrece configuración en una línea para Koa, Hono y NestJS, y un envoltorio para handlers al estilo de AWS Lambda.
1Instalar
npm install @blipit/node2Obtén tus claves
Inicia sesión en app.blipit.io y abre Claves API en la barra lateral y luego tu proyecto. Cada proyecto tiene dos claves. La clave pública empieza por blipit_pk_: va en el código del navegador y de las apps, solo puede enviar eventos y cualquiera puede verla sin riesgo. La clave secreta empieza por blipit_sk_: se queda en tu servidor o en Odoo, nunca en un navegador, porque también puede leer y cambiar incidencias. La clave secreta solo se muestra una vez, justo al crearla, así que cópiala entonces; si la pierdes, pulsa Crear una nueva clave secreta y la anterior deja de funcionar al instante. Algunos SDKs también necesitan el id del proyecto, que aparece en la misma página.
3Guarda la clave en el entorno
Node usa la clave secreta. Ponla en una variable de entorno, nunca en el código: en local, en un archivo .env que Node 20.6 y posteriores cargan con --env-file; en producción, en las variables de entorno o los ajustes de secretos de tu hosting (Fly secrets, Docker, systemd, Render, Vercel). Reinicia el proceso después de cambiarla.
BLIPIT_SECRET_KEY=blipit_sk_your_secret_keynode --env-file=.env --import ./instrument.mjs server.mjs4Mantén las claves fuera de git
Guarda las claves en variables de entorno o en los ajustes de secretos de tu hosting, nunca en código que subas con commit, y añade tus archivos .env a .gitignore. Una clave pública en una página web es normal. Si alguna vez una clave secreta acaba en git, en una página pública, en una captura o en un chat, abre Claves API, pulsa Crear una nueva clave secreta y pega la nueva clave donde se usaba la anterior: la clave anterior deja de funcionar al instante.
.env
.env.local
.env.*.local5Inicializa primero
Pon esto en un archivo que se ejecute antes que tu app, e impórtalo primero.
import * as Blipit from "@blipit/node";
Blipit.init({
key: process.env.BLIPIT_SECRET_KEY,
environment: process.env.NODE_ENV,
release: process.env.RELEASE,
serverName: "api",
});6Express, Fastify, Koa, Hono o NestJS
Añade el handler después de tus rutas para que tanto los errores controlados como los no controlados lleguen a Blipit, con el método, la URL y el user agent de la petición. Koa, Hono y NestJS necesitan una línea cada uno: el middleware de Koa va primero y el de Hono antes de las rutas. Informan de los errores con estado 500 o superior. Las peticiones aparecen entonces en la página Pulse por ruta, como GET /users/:id, en lugar de una línea por URL.
import "./instrument.mjs";
import * as Blipit from "@blipit/node";
import express from "express";
const app = express();
app.get("/", (req, res) => res.send("ok"));
app.use(Blipit.expressErrorHandler());
app.listen(3000);await app.register(Blipit.fastifyPlugin());app.use(Blipit.koaMiddleware());app.use(Blipit.honoMiddleware());app.useGlobalInterceptors(Blipit.nestInterceptor());7Serverless: AWS Lambda y Vercel
Los hosts serverless pausan la función en cuanto responde, y Lambda no ejecuta el servidor HTTP de Node, así que envuelve el handler. wrapHandler registra la petición (eventos de API Gateway, URL de función y balanceador por método y ruta, otros eventos por nombre de función), informa de los errores y lo envía todo antes de que el handler devuelva; solo espera cuando hay algo que enviar, 2 segundos como máximo. traceRequest hace lo mismo con cualquier handler que reciba una Request. En Vercel los datos salen después de la respuesta mediante waitUntil, así que nada se retrasa. En Next.js usa withBlipit (consulta la guía de Next.js).
import * as Blipit from "@blipit/node";
export const handler = Blipit.wrapHandler(async (event, context) => {
return { statusCode: 200, body: "ok" };
});export default { fetch: (request) => Blipit.traceRequest(request, () => app.fetch(request)) };8Captura manual, logs e intentos de inicio de sesión
Blipit.captureException(err);
Blipit.captureMessage("cache miss rate above 50%", "warning");
Blipit.setUser({ id: "user-42" });
Blipit.log.info("order placed", { order_id: 42 });
Blipit.captureSecurity({ kind: "login_failed", actor: email, ip, userAgent, outcome: "bad_password" });
await Blipit.flush();9Dependencias y salud del servidor
Desde la 0.2 el SDK también registra tus llamadas a la base de datos y a servicios externos, y la CPU, memoria y bucle de eventos de tu servidor. Consulta las guías Dependencias y Salud del servidor; se controla con tracesSampleRate, tracing: false y metrics: false.
10Comprueba que funciona
Abre Incidencias en app.blipit.io. El primer evento aparece en unos segundos, agrupado en una incidencia, y los responsables reciben un correo.
Blipit.captureMessage("Hello from Node");Conviene saber
- Ante una excepción no controlada el SDK vacía los eventos pendientes y luego sale con código 1; puedes cambiarlo con onFatal.
- captureConsole: true convierte console.log y compañía en líneas de log enviadas a la página de Logs.
- Comprueba la versión instalada con npm ls @blipit/node (o pnpm list @blipit/node). pnpm 11 espera un día antes de instalar una versión nueva (minimum-release-age), así que el día del lanzamiento pnpm add instala sin avisar la versión anterior; para obtener la nueva enseguida, ejecuta pnpm add @blipit/node@<version> --config.minimum-release-age=0.
- Mantener Blipit actualizado: la guía Mantener Blipit actualizado (docs.blipit.io/updates) explica el banner de actualización, los correos para versiones importantes, el aviso en tu consola de desarrollo y el comando de actualización para esta plataforma.
- Un proyecto por app y plataforma: cada proyecto elige su plataforma al crearse (Android, iOS, React Native, Flutter, Web, Backend u Odoo) y Blipit rechaza con un error claro los datos de cualquier otra plataforma, así que una app de iOS y una de Android necesitan dos proyectos con dos claves. Las versiones, las compilaciones, las tasas de fallos y las builds de tienda son distintas en cada plataforma, y mezclarlas en un proyecto hace que todas sean incorrectas. Un proyecto Web también acepta la parte de servidor de la misma app web (el servidor de Next.js o Node), y un proyecto de React Native o Flutter también acepta sus propios informes de fallos nativos de Android e iOS.
¿Atascado? Escribe a support@blipit.io. Las claves y el id de cada proyecto están en Claves API en app.blipit.io.

