Installazione per piattaforma
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.
1Installazione
npm install @blipit/node2Ottieni 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.
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.
BLIPIT_SECRET_KEY=blipit_sk_your_secret_keynode --env-file=.env --import ./instrument.mjs server.mjs4Tieni 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.
.env
.env.local
.env.*.local5Inizializza per primo
Mettilo in un file che viene eseguito prima della tua app, e importalo per primo.
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.
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 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).
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)) };8Cattura manuale, log e tentativi di accesso
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.
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.

