Node.js

インストール npm install @blipit/node

@blipit/node は捕捉されなかった例外と未処理の Promise の拒否を自動で捕捉し、Express と Fastify 用のハンドラーを追加し、同じキーでログとログイン試行を送信します。シークレットキーを使い、サーバー上に保管してください。 0.3 からは Koa、Hono、NestJS を 1 行で設定でき、AWS Lambda 形式のハンドラー用のラッパーもあります。

Claude Code、Cursor などのAIコーディングアシスタントに貼り付けてください。手順とコードが含まれています。app.blipit.io の「APIキー」では、キーが入力済みの同じプロンプトをコピーできます。
動画:どのスタックにも Blipit を導入(1:07 から)

1インストール

sh
npm install @blipit/node

2キーを取得

app.blipit.io にサインインし、サイドバーの「APIキー」を開いてプロジェクトを選びます。各プロジェクトには2つのキーがあります。公開キーは blipit_pk_ で始まり、ブラウザやアプリのコードに置くものです。イベントの送信しかできないため、誰に見られても安全です。シークレットキーは blipit_sk_ で始まり、サーバーまたは Odoo に置き、ブラウザには決して置きません。イシューの読み取りや変更もできるためです。シークレットキーは作成直後に一度だけ表示されるので、そのときにコピーしてください。紛失した場合は「新しいシークレットキーを作成」を押すと、古いキーは即座に無効になります。一部の SDK では、同じページに表示されるプロジェクト ID も必要です。

app.blipit.io の API キー:ブラウザコード用の公開キー(blipit_pk_)と、サーバーおよび Odoo 用のシークレットキー(blipit_sk_)。
app.blipit.io の API キー:ブラウザコード用の公開キー(blipit_pk_)と、サーバーおよび Odoo 用のシークレットキー(blipit_sk_)。
新しいシークレットキーは一度だけ表示されます。今すぐコピーしてください。ハッシュ化して保存されるため、再表示はできません。
新しいシークレットキーは一度だけ表示されます。今すぐコピーしてください。ハッシュ化して保存されるため、再表示はできません。

3キーを環境変数に保管する

Node ではシークレットキーを使います。キーはコードではなく環境変数に置いてください。ローカルでは Node 20.6 以降が --env-file で読み込む .env ファイルに、本番環境ではホスティング先の環境変数またはシークレット設定(Fly secrets、Docker、systemd、Render、Vercel)に置きます。変更後はプロセスを再起動してください。

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

4キーを git に含めない

キーは環境変数またはホスティング先のシークレット設定に保管し、コミットするコードには決して書かないでください。また、.env ファイルを .gitignore に追加してください。Web ページに公開キーがあるのは通常のことです。シークレットキーが git、公開ページ、スクリーンショット、チャットなどに漏れた場合は、「APIキー」を開いて「新しいシークレットキーを作成」を押し、古いキーを使っていた箇所すべてに新しいキーを貼り付けてください。古いキーは即座に無効になります。

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

5最初に初期化

アプリより先に実行されるファイルにこれを置き、最初にインポートしてください。

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

ルートの後にハンドラーを追加すると、処理済み・未処理のエラーの両方が、リクエストのメソッド、URL、ユーザーエージェント付きで Blipit に届きます。 Koa、Hono、NestJS はそれぞれ 1 行です。Koa のミドルウェアは最初に、Hono のものはルートの前に置きます。ステータス 500 以上のエラーを報告します。これにより、リクエストは Pulse ページで URL ごとではなく GET /users/:id のようにルート単位で表示されます。

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

7サーバーレス: AWS Lambda と Vercel

サーバーレス環境は応答した直後に関数を一時停止し、Lambda は Node の HTTP サーバーを動かしません。そのためハンドラーをラップします。wrapHandler はリクエストを記録し (API Gateway、関数 URL、ロードバランサーのイベントはメソッドとルートで、その他のイベントは関数名で)、エラーを報告し、ハンドラーが戻る前にすべてを送信します。待つのは送るものがあるときだけで、最大 2 秒です。traceRequest は Request を受け取るあらゆるハンドラーで同じことを行います。Vercel ではデータは応答の後に waitUntil で送られるため、何も遅れません。Next.js では withBlipit を使います (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)) };

8手動キャプチャ、ログ、ログイン試行

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

9依存サービスとサーバーの状態

0.2 からは、データベースや外部サービスへの呼び出しと、サーバーの CPU、メモリ、イベントループも記録します。依存サービスとサーバーの状態のガイドを参照してください。tracesSampleRate、tracing: false、metrics: false で制御できます。

10動作確認

app.blipit.io で「イシュー」を開きます。数秒以内に最初のイベントがイシューにまとめられて表示され、担当者にメールが届きます。

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

知っておくと便利

  • 捕捉されなかった例外が発生すると、SDK は保留中のイベントをフラッシュしてから終了コード 1 で終了します。onFatal で上書きできます。
  • captureConsole: true にすると、console.log などがログ行としてログページに送信されます。
  • インストールされているバージョンを npm ls @blipit/node(または pnpm list @blipit/node)で確認してください。pnpm 11 は新しいリリースをインストールする前に 1 日待つ(minimum-release-age)ため、リリース当日の pnpm add は何も知らせずに前のバージョンをインストールします。すぐに新しいバージョンを入れるには pnpm add @blipit/node@<version> --config.minimum-release-age=0 を実行します。
  • Blipit を最新に保つ:「Blipit を最新に保つ」ガイド(docs.blipit.io/updates)で、更新バナー、重要なリリースのメール、開発コンソールのお知らせ、このプラットフォームの更新コマンドを説明しています。
  • アプリとプラットフォームごとに 1 つのプロジェクト:各プロジェクトは作成時にプラットフォーム(Android、iOS、React Native、Flutter、Web、Backend、Odoo)を選び、Blipit はほかのプラットフォームからのデータをわかりやすいエラーで拒否します。そのため iOS アプリと Android アプリには、キーが別々の 2 つのプロジェクトが必要です。リリース、バージョン、クラッシュ率、ストア向けビルドはプラットフォームごとに異なり、1 つのプロジェクトに混ぜるとすべての数字が正しくなくなります。Web プロジェクトは同じ Web アプリのサーバー側(Next.js サーバーや Node)も受け付け、React Native と Flutter のプロジェクトは自身の Android と iOS のネイティブクラッシュレポートも受け付けます。

お困りですか?support@blipit.io までメールしてください。各プロジェクトのキーとプロジェクト ID は app.blipit.io の「APIキー」にあります。