Node.js

Installation npm install @blipit/node

@blipit/node erfasst nicht abgefangene Exceptions und unbehandelte Promise-Rejections von selbst, ergänzt Handler für Express und Fastify und sendet Logs und Anmeldeversuche mit demselben Schlüssel. Verwenden Sie den geheimen Schlüssel; er bleibt auf dem Server. Ab 0.3 gibt es außerdem eine Einrichtung in einer Zeile für Koa, Hono und NestJS und einen Wrapper für Handler im Stil von AWS Lambda.

Fügen Sie ihn in Claude Code, Cursor oder einen anderen KI-Programmierassistenten ein. Er enthält die Schritte und den Code. In app.blipit.io unter API-Schlüssel steht derselbe Prompt mit Ihrem Schlüssel bereits eingetragen.
Video: Blipit in jedem Stack installieren, ab 1:07

1Installation

sh
npm install @blipit/node

2Schlüssel abrufen

Melden Sie sich bei app.blipit.io an und öffnen Sie API-Schlüssel in der Seitenleiste, dann Ihr Projekt. Jedes Projekt hat zwei Schlüssel. Der öffentliche Schlüssel beginnt mit blipit_pk_: Er gehört in Browser- und App-Code, kann nur Events senden und darf von jedem gesehen werden. Der geheime Schlüssel beginnt mit blipit_sk_: Er bleibt auf Ihrem Server oder in Odoo, nie in einem Browser, weil er auch Issues lesen und ändern kann. Der geheime Schlüssel wird nur einmal angezeigt, direkt nach der Erstellung, kopieren Sie ihn also dann; geht er verloren, klicken Sie auf Neuen geheimen Schlüssel erstellen, und der alte funktioniert sofort nicht mehr. Manche SDKs brauchen zusätzlich die Projekt-ID, die auf derselben Seite steht.

API-Schlüssel in app.blipit.io: der öffentliche Schlüssel (blipit_pk_) für Browser-Code und der geheime Schlüssel (blipit_sk_) für Server und Odoo.
API-Schlüssel in app.blipit.io: der öffentliche Schlüssel (blipit_pk_) für Browser-Code und der geheime Schlüssel (blipit_sk_) für Server und Odoo.
Ein neuer geheimer Schlüssel wird einmal angezeigt. Kopieren Sie ihn sofort: Er wird gehasht gespeichert und kann nicht erneut angezeigt werden.
Ein neuer geheimer Schlüssel wird einmal angezeigt. Kopieren Sie ihn sofort: Er wird gehasht gespeichert und kann nicht erneut angezeigt werden.

3Den Schlüssel in der Umgebung ablegen

Node verwendet den geheimen Schlüssel. Legen Sie ihn in eine Umgebungsvariable, nie in den Code: lokal in eine .env-Datei, die Node 20.6 und neuer mit --env-file lädt, in der Produktion in die Umgebungs- oder Secret-Einstellungen Ihres Hosters (Fly secrets, Docker, systemd, Render, Vercel). Starten Sie den Prozess nach einer Änderung neu.

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

4Schlüssel aus Git heraushalten

Bewahren Sie Schlüssel in Umgebungsvariablen oder den Secret-Einstellungen Ihres Hosters auf, nie in Code, den Sie committen, und tragen Sie Ihre .env-Dateien in .gitignore ein. Ein öffentlicher Schlüssel in einer Webseite ist normal. Landet ein geheimer Schlüssel je in Git, auf einer öffentlichen Seite, in einem Screenshot oder einem Chat, öffnen Sie API-Schlüssel, klicken Sie auf Neuen geheimen Schlüssel erstellen und fügen Sie den neuen Schlüssel überall ein, wo der alte verwendet wurde: Der alte Schlüssel funktioniert sofort nicht mehr.

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

5Zuerst initialisieren

Legen Sie dies in eine Datei, die vor Ihrer App läuft, und importieren Sie sie zuerst.

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

Fügen Sie den Handler nach Ihren Routen hinzu, damit behandelte und unbehandelte Fehler beide Blipit erreichen, mit Methode, URL und User Agent des Requests. Koa, Hono und NestJS brauchen je eine Zeile: die Koa-Middleware zuerst, die von Hono vor den Routen. Sie melden Fehler mit einem Status ab 500. Anfragen erscheinen dann auf der Seite Pulse nach Route, etwa GET /users/:id, statt einer Zeile pro 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 und Vercel

Serverless-Hosts pausieren die Funktion, sobald sie antwortet, und Lambda startet den HTTP-Server von Node nicht. Umschließen Sie deshalb den Handler. wrapHandler erfasst die Anfrage (API-Gateway-, Function-URL- und Load-Balancer-Ereignisse nach Methode und Route, andere Ereignisse nach Funktionsname), meldet Fehler und sendet alles, bevor der Handler zurückkehrt; er wartet nur, wenn es etwas zu senden gibt, höchstens 2 Sekunden. traceRequest macht dasselbe für jeden Handler, der einen Request erhält. Auf Vercel gehen die Daten nach der Antwort über waitUntil hinaus, nichts wird verzögert. In Next.js nutzen Sie withBlipit (siehe Next.js-Anleitung).

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

8Manuelles Erfassen, Logs und Anmeldeversuche

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

9Abhängigkeiten und Serverzustand

Ab 0.2 erfasst das SDK auch deine Datenbank- und externen Aufrufe sowie CPU, Speicher und Event-Loop deines Servers. Siehe die Anleitungen Abhängigkeiten und Serverzustand; gesteuert wird es mit tracesSampleRate, tracing: false und metrics: false.

10Prüfen, ob es funktioniert

Öffnen Sie Issues in app.blipit.io. Das erste Event erscheint innerhalb weniger Sekunden, gruppiert zu einem Issue, und die verantwortlichen Personen erhalten eine E-Mail.

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

Gut zu wissen

  • Bei einer nicht abgefangenen Exception sendet das SDK ausstehende Events und beendet dann mit Code 1; überschreiben Sie das mit onFatal.
  • captureConsole: true macht aus console.log und Co. Log-Zeilen, die an die Logs-Seite gesendet werden.
  • Prüfen Sie die installierte Version mit npm ls @blipit/node (oder pnpm list @blipit/node). pnpm 11 wartet einen Tag, bevor es eine neue Version installiert (minimum-release-age), daher installiert pnpm add am Veröffentlichungstag stillschweigend die vorherige Version; für die neue sofort führen Sie pnpm add @blipit/node@<version> --config.minimum-release-age=0 aus.
  • Blipit aktuell halten: Die Anleitung „Blipit auf dem neuesten Stand halten“ (docs.blipit.io/updates) erklärt das Update-Banner, die E-Mails zu wichtigen Releases, den Hinweis in deiner Entwicklungskonsole und den Update-Befehl für diese Plattform.
  • Ein Projekt pro App und Plattform: Jedes Projekt legt beim Anlegen seine Plattform fest (Android, iOS, React Native, Flutter, Web, Backend oder Odoo), und Blipit lehnt Daten von jeder anderen Plattform mit einer klaren Fehlermeldung ab. Eine iOS-App und eine Android-App brauchen also zwei Projekte mit zwei Schlüsseln. Releases, Versionen, Absturzraten und Store-Builds sind je Plattform verschieden, und gemischt in einem Projekt stimmt keiner dieser Werte mehr. Ein Web-Projekt nimmt auch die Serverseite derselben Web-App an (den Next.js-Server oder Node), und ein React-Native- oder Flutter-Projekt auch seine eigenen nativen Android- und iOS-Absturzberichte.

Kommen Sie nicht weiter? Schreiben Sie an support@blipit.io. Schlüssel und die Projekt-ID jedes Projekts finden Sie unter API-Schlüssel in app.blipit.io.