Node.js

Installazione npm install @blipit/node

@blipit/node cattura da solo eccezioni non catturate e promise rejection non gestite, aggiunge handler per Express e Fastify, e invia log e tentativi di accesso con la stessa chiave. Usa la chiave segreta; resta sul server. Dalla 0.3 offre anche la configurazione in una riga per Koa, Hono e NestJS, e un wrapper per gli handler in stile AWS Lambda.

Incollalo in Claude Code, Cursor o in qualsiasi assistente di programmazione IA. Contiene i passaggi e il codice. In app.blipit.io, in Chiavi API, lo stesso prompt ha già la tua chiave inserita.
Video: installare Blipit in qualsiasi stack, da 1:07

1Installazione

sh
npm install @blipit/node

2Ottieni le chiavi

Accedi su app.blipit.io e apri Chiavi API nella barra laterale, poi il tuo progetto. Ogni progetto ha due chiavi. La chiave pubblica inizia con blipit_pk_: va nel codice del browser e delle app, può solo inviare eventi e chiunque può vederla senza rischi. La chiave segreta inizia con blipit_sk_: resta sul tuo server o in Odoo, mai in un browser, perché può anche leggere e modificare le issue. La chiave segreta viene mostrata una sola volta, subito dopo la creazione, quindi copiala in quel momento; se la perdi, premi Crea una nuova chiave segreta e quella vecchia smette subito di funzionare. Alcuni SDK richiedono anche l'id del progetto, mostrato nella stessa pagina.

Chiavi API su app.blipit.io: la chiave pubblica (blipit_pk_) per il codice del browser e la chiave segreta (blipit_sk_) per i server e Odoo.
Chiavi API su app.blipit.io: la chiave pubblica (blipit_pk_) per il codice del browser e la chiave segreta (blipit_sk_) per i server e Odoo.
Una nuova chiave segreta viene mostrata una sola volta. Copiala subito: viene salvata come hash e non può essere mostrata di nuovo.
Una nuova chiave segreta viene mostrata una sola volta. Copiala subito: viene salvata come hash e non può essere mostrata di nuovo.

3Tieni la chiave nell'ambiente

Node usa la chiave segreta. Mettila in una variabile d'ambiente, mai nel codice: in locale in un file .env che Node 20.6 e versioni successive caricano con --env-file, in produzione nelle impostazioni dell'ambiente o dei secret del tuo host (Fly secrets, Docker, systemd, Render, Vercel). Riavvia il processo dopo averla cambiata.

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

4Tieni le chiavi fuori da git

Tieni le chiavi in variabili d'ambiente o nelle impostazioni dei secret del tuo host, mai nel codice che fai commit, e aggiungi i tuoi file .env a .gitignore. Una chiave pubblica in una pagina web è normale. Se una chiave segreta finisce in git, in una pagina pubblica, in uno screenshot o in una chat, apri Chiavi API, premi Crea una nuova chiave segreta e incolla la nuova chiave ovunque usavi quella vecchia: la vecchia chiave smette di funzionare subito.

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

5Inizializza per primo

Mettilo in un file che viene eseguito prima della tua app, e importalo per primo.

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 o NestJS

Aggiungi l'handler dopo le tue route così sia gli errori gestiti che quelli non gestiti raggiungono Blipit, con metodo, URL e user agent della richiesta. Koa, Hono e NestJS richiedono una riga ciascuno: il middleware di Koa va per primo, quello di Hono prima delle rotte. Segnalano gli errori con stato 500 o superiore. Le richieste compaiono poi nella pagina Pulse per rotta, come GET /users/:id, invece di una riga per 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 e Vercel

Gli host serverless sospendono la funzione appena risponde, e Lambda non avvia il server HTTP di Node, quindi avvolgi l'handler. wrapHandler registra la richiesta (eventi di API Gateway, URL di funzione e load balancer per metodo e rotta, gli altri eventi per nome della funzione), segnala gli errori e invia tutto prima che l'handler restituisca; attende solo quando c'è qualcosa da inviare, al massimo 2 secondi. traceRequest fa lo stesso per qualsiasi handler che riceve una Request. Su Vercel i dati partono dopo la risposta tramite waitUntil, quindi nulla viene rallentato. In Next.js usa withBlipit (vedi la guida 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)) };

8Cattura manuale, log e tentativi di accesso

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

9Dipendenze e stato dei server

Dalla 0.2 l'SDK registra anche le chiamate al database e ai servizi esterni, e CPU, memoria ed event loop del tuo server. Vedi le guide Dipendenze e Stato dei server; si controlla con tracesSampleRate, tracing: false e metrics: false.

10Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

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

Buono a sapersi

  • In caso di eccezione non catturata l'SDK invia gli eventi in sospeso, poi esce con codice 1; puoi sovrascriverlo con onFatal.
  • captureConsole: true trasforma console.log e simili in righe di log inviate alla pagina Log.
  • Controlla la versione installata con npm ls @blipit/node (o pnpm list @blipit/node). pnpm 11 aspetta un giorno prima di installare una nuova versione (minimum-release-age), quindi il giorno del rilascio pnpm add installa in silenzio la versione precedente; per avere subito quella nuova esegui pnpm add @blipit/node@<version> --config.minimum-release-age=0.
  • Tenere Blipit aggiornato: la guida Tenere Blipit aggiornato (docs.blipit.io/updates) spiega il banner di aggiornamento, le email per le versioni importanti, l'avviso nella console di sviluppo e il comando di aggiornamento per questa piattaforma.
  • Un progetto per app e piattaforma: ogni progetto sceglie la sua piattaforma quando viene creato (Android, iOS, React Native, Flutter, Web, Backend o Odoo) e Blipit rifiuta con un errore chiaro i dati di qualsiasi altra piattaforma, quindi un'app iOS e un'app Android hanno bisogno di due progetti con due chiavi. Release, versioni, tassi di crash e build per gli store sono diversi per ogni piattaforma, e mescolarli in un progetto li rende tutti sbagliati. Un progetto Web accetta anche la parte server della stessa app web (il server Next.js o Node), e un progetto React Native o Flutter accetta anche i propri crash nativi Android e iOS.

Bloccato? Scrivi a support@blipit.io. Le chiavi e l'id di ogni progetto sono sotto Chiavi API in app.blipit.io.