Node.js

التثبيت npm install @blipit/node

تلتقط @blipit/node الاستثناءات غير الملتقطة ورفض الـ promise غير المعالج تلقائيًا، وتضيف معالجات لـ Express وFastify، وترسل السجلات ومحاولات تسجيل الدخول بالمفتاح نفسه. استخدم المفتاح السري؛ فهو يبقى على الخادم. ومنذ الإصدار 0.3 يوفّر أيضاً إعداداً بسطر واحد لـ Koa وHono وNestJS، وغلافاً للمعالجات بأسلوب AWS Lambda.

الصقها في Claude Code أو Cursor أو أي مساعد برمجة بالذكاء الاصطناعي. تحتوي على الخطوات والشيفرة. في app.blipit.io ضمن مفاتيح API تجد التعليمات نفسها مع مفتاحك مكتوباً فيها.
فيديو: ثبّت Blipit في أي تقنية، من 1:07

1التثبيت

sh
npm install @blipit/node

2احصل على مفاتيحك

سجّل الدخول في app.blipit.io وافتح «مفاتيح API» في الشريط الجانبي، ثم مشروعك. لكل مشروع مفتاحان. يبدأ المفتاح العام بـ blipit_pk_: يوضع في كود المتصفح والتطبيقات، ولا يستطيع سوى إرسال الأحداث، ومن الآمن أن يراه أي شخص. يبدأ المفتاح السري بـ blipit_sk_: يبقى على خادمك أو في Odoo، وليس في متصفح أبدًا، لأنه يستطيع أيضًا قراءة المشكلات وتغييرها. يُعرض المفتاح السري مرة واحدة فقط، فور إنشائه، لذا انسخه حينها؛ وإذا فقدته، فاضغط «إنشاء مفتاح سري جديد»، فيتوقف القديم عن العمل فورًا. تحتاج بعض حزم SDK أيضًا إلى معرّف المشروع، المعروض في الصفحة نفسها.

مفاتيح API في app.blipit.io: المفتاح العام (blipit_pk_) لكود المتصفح، والمفتاح السري (blipit_sk_) للخوادم وOdoo.
مفاتيح API في app.blipit.io: المفتاح العام (blipit_pk_) لكود المتصفح، والمفتاح السري (blipit_sk_) للخوادم وOdoo.
يُعرض المفتاح السري الجديد مرة واحدة. انسخه الآن: يُخزّن مجزّأً (hashed) ولا يمكن عرضه مرة أخرى.
يُعرض المفتاح السري الجديد مرة واحدة. انسخه الآن: يُخزّن مجزّأً (hashed) ولا يمكن عرضه مرة أخرى.

3احتفظ بالمفتاح في البيئة

يستخدم Node المفتاح السري. ضعه في متغير بيئة، وليس في الكود أبدًا: محليًا في ملف .env يحمّله Node 20.6 وما بعده عبر --env-file، وفي الإنتاج في بيئة منصة الاستضافة أو إعداداتها السرية (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. وجود مفتاح عام في صفحة ويب أمر طبيعي. إذا انتهى مفتاح سري يومًا في 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

أضف المعالج بعد مساراتك لتصل الأخطاء المعالجة وغير المعالجة معًا إلى Blipit، مع طريقة الطلب وعنوانه ووكيل المستخدم. تحتاج Koa وHono وNestJS إلى سطر واحد لكل منها: وسيط Koa يأتي أولاً، ووسيط Hono قبل المسارات. وتبلّغ عن الأخطاء ذات الحالة 500 أو أعلى. وتظهر الطلبات بعدها في صفحة Pulse حسب المسار، مثل 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 خادم HTTP الخاص بـ Node، لذا غلّف المعالج. يسجّل wrapHandler الطلب (أحداث API Gateway وروابط الدوال وموازن الأحمال حسب الطريقة والمسار، والأحداث الأخرى حسب اسم الدالة)، ويبلّغ عن الأخطاء ويرسل كل شيء قبل أن يعود المعالج؛ ولا ينتظر إلا عند وجود ما يُرسل، ثانيتين على الأكثر. ويفعل 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 يسجل SDK أيضًا طلبات قاعدة البيانات والخدمات الخارجية، والمعالج والذاكرة وحلقة الأحداث لخادمك. راجع دليلي الخدمات المرتبطة وصحة الخوادم؛ ويتحكم في ذلك 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 يومًا قبل أن يثبّت إصدارًا جديدًا (minimum-release-age)، لذلك يثبّت pnpm add في يوم الإصدار الإصدار السابق دون أي تنبيه؛ للحصول على الإصدار الجديد فورًا شغّل pnpm add @blipit/node@<version> --config.minimum-release-age=0.
  • إبقاء Blipit محدّثًا: يشرح دليل إبقاء Blipit محدّثًا (docs.blipit.io/updates) لافتة التحديث، ورسائل البريد للإصدارات المهمة، والتنبيه في وحدة تحكم التطوير، وأمر التحديث لهذه المنصة.
  • مشروع واحد لكل تطبيق ومنصة: يختار كل مشروع منصته عند إنشائه (Android أو iOS أو React Native أو Flutter أو Web أو Backend أو Odoo)، ويرفض Blipit البيانات القادمة من أي منصة أخرى مع رسالة خطأ واضحة، لذلك يحتاج تطبيق iOS وتطبيق Android إلى مشروعين بمفتاحين. الإصدارات والنسخ ومعدلات الأعطال وإصدارات المتاجر تختلف من منصة لأخرى، وخلطها في مشروع واحد يجعلها كلها خاطئة. يقبل مشروع Web أيضًا جانب الخادم من تطبيق الويب نفسه (خادم Next.js أو Node)، ويقبل مشروع React Native أو Flutter أيضًا تقارير الأعطال الأصلية الخاصة به على Android وiOS.

هل واجهتك مشكلة؟ راسل support@blipit.io. المفاتيح ومعرّف كل مشروع موجودة تحت مفاتيح API في app.blipit.io.