Installation par plateforme
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.
1Installation
npm install @blipit/node2Obtenir 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.
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.
BLIPIT_SECRET_KEY=blipit_sk_your_secret_keynode --env-file=.env --import ./instrument.mjs server.mjs4Gardez 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.
.env
.env.local
.env.*.local5Initialiser en premier
Placez ceci dans un fichier qui s'exécute avant votre application, et importez-le en premier.
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.
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 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).
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)) };8Capture manuelle, logs et tentatives de connexion
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.
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.

