Node.js

Installation npm install @blipit/node

@blipit/node capture de lui-même les exceptions non interceptées et les rejets de promesses non gérés, ajoute des handlers pour Express et Fastify, et envoie logs et tentatives de connexion avec la même clé. Utilisez la clé secrète ; elle reste sur le serveur. Depuis la 0.3, il propose aussi une installation en une ligne pour Koa, Hono et NestJS, et un wrapper pour les handlers de type AWS Lambda.

Collez-le dans Claude Code, Cursor ou tout autre assistant de code IA. Il contient les étapes et le code. Dans app.blipit.io, sous Clés API, le même prompt est fourni avec votre clé déjà renseignée.
Vidéo : installer Blipit dans n'importe quel stack, à partir de 1:07

1Installation

sh
npm install @blipit/node

2Obtenir vos clés

Connectez-vous sur app.blipit.io et ouvrez Clés API dans la barre latérale, puis votre projet. Chaque projet a deux clés. La clé publique commence par blipit_pk_ : elle va dans le code navigateur et applicatif, ne peut qu'envoyer des événements et peut être vue par n'importe qui sans risque. La clé secrète commence par blipit_sk_ : elle reste sur votre serveur ou dans Odoo, jamais dans un navigateur, car elle peut aussi lire et modifier les problèmes. La clé secrète n'est affichée qu'une fois, juste après sa création, alors copiez-la à ce moment-là ; si vous la perdez, appuyez sur Créer une nouvelle clé secrète, et l'ancienne cesse aussitôt de fonctionner. Certains SDK ont aussi besoin de l'identifiant de projet, affiché sur la même page.

Clés API dans app.blipit.io : la clé publique (blipit_pk_) pour le code navigateur et la clé secrète (blipit_sk_) pour les serveurs et Odoo.
Clés API dans app.blipit.io : la clé publique (blipit_pk_) pour le code navigateur et la clé secrète (blipit_sk_) pour les serveurs et Odoo.
Une nouvelle clé secrète n'est affichée qu'une fois. Copiez-la maintenant : elle est stockée sous forme de hash et ne peut plus être affichée.
Une nouvelle clé secrète n'est affichée qu'une fois. Copiez-la maintenant : elle est stockée sous forme de hash et ne peut plus être affichée.

3Gardez la clé dans l'environnement

Node utilise la clé secrète. Placez-la dans une variable d'environnement, jamais dans le code : en local dans un fichier .env que Node 20.6 et versions ultérieures chargent avec --env-file, en production dans l'environnement ou les réglages de secrets de votre hébergeur (secrets Fly, Docker, systemd, Render, Vercel). Redémarrez le processus après l'avoir modifiée.

.env
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key
sh
node --env-file=.env --import ./instrument.mjs server.mjs

4Gardez les clés hors de git

Gardez les clés dans des variables d'environnement ou dans les réglages de secrets de votre hébergeur, jamais dans du code que vous committez, et ajoutez vos fichiers .env à .gitignore. Une clé publique dans une page web est normale. Si une clé secrète se retrouve un jour dans git, sur une page publique, dans une capture d'écran ou dans un chat, ouvrez Clés API, appuyez sur Créer une nouvelle clé secrète, et collez la nouvelle clé partout où l'ancienne était utilisée : l'ancienne clé cesse immédiatement de fonctionner.

.gitignore
.env
.env.local
.env.*.local

5Initialiser en premier

Placez ceci dans un fichier qui s'exécute avant votre application, et importez-le en premier.

instrument.mjs
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 ou NestJS

Ajoutez le handler après vos routes pour que les erreurs gérées et non gérées atteignent toutes Blipit, avec la méthode, l'URL et le user agent de la requête. Koa, Hono et NestJS demandent une ligne chacun : le middleware Koa en premier, celui de Hono avant les routes. Ils signalent les erreurs avec un statut de 500 ou plus. Les requêtes apparaissent alors sur la page Pulse par route, comme GET /users/:id, au lieu d'une ligne par URL.

js
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);
Fastify
await app.register(Blipit.fastifyPlugin());
Koa
app.use(Blipit.koaMiddleware());
Hono
app.use(Blipit.honoMiddleware());
NestJS
app.useGlobalInterceptors(Blipit.nestInterceptor());

7Serverless : AWS Lambda et Vercel

Les hébergements serverless mettent la fonction en pause dès qu'elle répond, et Lambda ne lance pas le serveur HTTP de Node : enveloppez donc le handler. wrapHandler enregistre la requête (événements API Gateway, URL de fonction et load balancer par méthode et route, les autres par nom de fonction), signale les erreurs et envoie tout avant que le handler ne rende la main ; il n'attend que s'il y a quelque chose à envoyer, 2 secondes au plus. traceRequest fait de même pour tout handler qui reçoit une Request. Sur Vercel, les données partent après la réponse via waitUntil, donc rien n'est retardé. Dans Next.js, utilisez withBlipit (voir le guide Next.js).

js
import * as Blipit from "@blipit/node";

export const handler = Blipit.wrapHandler(async (event, context) => {
  return { statusCode: 200, body: "ok" };
});
traceRequest
export default { fetch: (request) => Blipit.traceRequest(request, () => app.fetch(request)) };

8Capture manuelle, logs et tentatives de connexion

js
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();

9Dépendances et santé des serveurs

Depuis la 0.2, le SDK enregistre aussi vos appels à la base de données et aux services externes, ainsi que le CPU, la mémoire et la boucle d'événements de votre serveur. Voir les guides Dépendances et Santé des serveurs ; tracesSampleRate, tracing: false et metrics: false le contrôlent.

10Vérifier que ça fonctionne

Ouvrez Problèmes dans app.blipit.io. Le premier événement apparaît en quelques secondes, regroupé en un problème, et les responsables reçoivent un e-mail.

js
Blipit.captureMessage("Hello from Node");

Bon à savoir

  • Sur une exception non interceptée, le SDK vide les événements en attente puis quitte avec le code 1 ; remplacez ce comportement avec onFatal.
  • captureConsole: true transforme console.log et consorts en lignes de log envoyées à la page Logs.
  • Vérifiez la version installée avec npm ls @blipit/node (ou pnpm list @blipit/node). pnpm 11 attend un jour avant d'installer une nouvelle version (minimum-release-age) : le jour de la sortie, pnpm add installe donc sans prévenir la version précédente ; pour obtenir la nouvelle tout de suite, lancez pnpm add @blipit/node@<version> --config.minimum-release-age=0.
  • Garder Blipit à jour : le guide Garder Blipit à jour (docs.blipit.io/updates) explique la bannière de mise à jour, les e-mails pour les versions importantes, l'avis dans votre console de développement et la commande de mise à jour pour cette plateforme.
  • Un projet par application et par plateforme : chaque projet choisit sa plateforme à sa création (Android, iOS, React Native, Flutter, Web, Backend ou Odoo), et Blipit refuse avec une erreur claire les données de toute autre plateforme. Une app iOS et une app Android ont donc besoin de deux projets avec deux clés. Les releases, les versions, les taux de plantage et les builds des stores diffèrent selon la plateforme, et les mélanger dans un projet les rend tous faux. Un projet Web accepte aussi la partie serveur de la même app web (le serveur Next.js ou Node), et un projet React Native ou Flutter accepte aussi ses propres rapports de plantage natifs Android et iOS.

Bloqué ? Écrivez à support@blipit.io. Les clés et l'identifiant de chaque projet sont sous Clés API dans app.blipit.io.