NestJS — التثبيت

مقدمة

@lerix-dev/lerix-nestjs هو SDK الخاص بـ Lerix من جانب الخادم لإطار NestJS. بعد تسجيل الوحدة، يُبلَّغ عن كل استثناء غير معالَج في واجهتك البرمجية إلى لوحة التحكم مع تتبّع المكدس واسم المضيف والإصدار وسياق الطلب، وتحصل خدماتك على عميل مُهيكل لواجهة REST الخاصة بالإشعارات.

أنشئ مشروعاً بإطار NestJS في لوحة التحكم وانسخ مفتاح API ومعرّف المشروع من إعدادات المشروع.

المتطلبات

	الحد الأدنى
Node.js	18
NestJS	10
TypeScript	5

لا توجد للحزمة أي اعتماديات وقت التشغيل، وتعمل مع محوّلي Express وFastify.

1. ثبّت الحزمة

npm install @lerix-dev/lerix-nestjs

2. سجّل الوحدة

استورد LerixModule مرة واحدة في الوحدة الجذرية:

app.module.ts

import { Module } from '@nestjs/common';
import { LerixModule } from '@lerix-dev/lerix-nestjs';

@Module({
  imports: [
    LerixModule.forRoot({
      apiKey: process.env.LERIX_API_KEY!,
      projectId: process.env.LERIX_PROJECT_ID!,
      environment: process.env.NODE_ENV,
    }),
  ],
})
export class AppModule {}

فعّل خطافات الإيقاف حتى تُرسَل التقارير العالقة عند إيقاف العملية:

main.ts

const app = await NestFactory.create(AppModule);
app.enableShutdownHooks();
await app.listen(3000);

هذا كل الإعداد. تسجّل الوحدة مرشّح استثناءات عاماً ومعالجات على مستوى العملية، فيُبلَّغ عن الأخطاء غير المعالَجة من الآن. راجع تتبع الأخطاء لمعرفة ما يُلتقط وكيفية الإبلاغ عن الأخطاء بنفسك.

تحميل الخيارات من `ConfigService`

تقبل forRootAsync الخيارات نفسها إضافة إلى imports وinject:

app.module.ts

LerixModule.forRootAsync({
  imports: [ConfigModule],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    apiKey: config.getOrThrow('LERIX_API_KEY'),
    projectId: config.getOrThrow('LERIX_PROJECT_ID'),
    environment: config.get('NODE_ENV'),
  }),
});

3. تحقّق من التكامل

أضف مساراً يُلقي خطأً واستدعِه مرة واحدة:

app.controller.ts

@Get('lerix-test')
lerixTest() {
  throw new Error('Lerix test error');
}

يتلقى العميل استجابة 500 المعتادة من Nest، ويظهر الخطأ في لوحة التحكم خلال ثوانٍ. احذف المسار بعد ذلك.

الخيارات

الخيار	الافتراضي	الوصف
`apiKey`	مطلوب	مفتاح API للمشروع
`projectId`	مطلوب	معرّف المشروع
`url`	`https://api.lerix.dev/v1`	عنوان API الأساسي
`environment`	`NODE_ENV`	يُرسَل كبيانات وصفية مع كل تقرير
`app`	من `package.json`	`{ id, name, version, buildNumber }` لتعريف هذه الخدمة
`enabled`	`true`	`false` يعطّل الحزمة بالكامل، مفيد في الاختبارات
`debug`	`false`	تسجيل الطلبات والتقارير عبر مسجّل Nest
`captureHttpExceptions`	`true`	تسجيل مرشّح الاستثناءات العام
`shouldCapture`	5xx وغير HTTP	`(exception, context) => boolean` لتحديد ما يُبلَّغ عنه
`captureUnhandled`	`true`	الإبلاغ عن `uncaughtException` و`unhandledRejection`
`exitOnUnhandled`	`true`	الخروج برمز 1 بعد الإبلاغ عنها كما يفعل Node
`statePath`	`.lerix/state.json`	مكان حفظ معرّف المستخدم المجهول؛ `false` يبقيه في الذاكرة
`userId`		تثبيت معرّف المستخدم المجهول بدل تسجيل واحد
`notifications`		`{ projectId, apiKey }` لتفعيل عميل الإشعارات
`flushTimeoutMs`	`2000`	مدة انتظار التقارير العالقة عند الإيقاف

كيف تظهر خدمتك في لوحة التحكم

يسجّل SDK خدمتك كتطبيق من نوع server. يأتي معرّف التطبيق افتراضياً من name في package.json والإصدار من version، فتُجمَّع التقارير لكل خدمة ولكل إصدار. عدّلهما عبر الخيار app عند نشر عدة نسخ من الكود نفسه أو عندما تريد استخدام git SHA كرقم بناء:

LerixModule.forRoot({
  apiKey, projectId,
  app: { id: 'orders-api', version: process.env.APP_VERSION, buildNumber: process.env.GIT_SHA },
});

يُسجَّل مستخدم مجهول عند أول تشغيل ويُحفظ في .lerix/state.json داخل مجلد العمل حتى تعيد عمليات التشغيل استخدامه. أضف هذا المجلد إلى .gitignore أو اربطه في الحاويات. مرّر statePath: false لتخطي الحفظ، أو userId للتحكم بالمعرّف بنفسك.

الخطوات التالية

تتبع الأخطاء

ما الذي يبلّغ عنه المرشّح، وكيف تغيّر السياسة، والإبلاغ اليدوي.

الإشعارات

أرسل وجدوِل وحدّث وألغِ الإشعارات من خادمك.

البدء

أطر العمل

الوحدات

المطورون

NestJS — التثبيت

مقدمة

المتطلبات

1. ثبّت الحزمة

2. سجّل الوحدة

تحميل الخيارات من `ConfigService`

3. تحقّق من التكامل

الخيارات

كيف تظهر خدمتك في لوحة التحكم

الخطوات التالية

تتبع الأخطاء

الإشعارات

​مقدمة

​المتطلبات

​1. ثبّت الحزمة

​2. سجّل الوحدة

​تحميل الخيارات من ConfigService

​3. تحقّق من التكامل

​الخيارات

​كيف تظهر خدمتك في لوحة التحكم

​الخطوات التالية

تتبع الأخطاء

الإشعارات

مقدمة

المتطلبات

1. ثبّت الحزمة

2. سجّل الوحدة

تحميل الخيارات من `ConfigService`

3. تحقّق من التكامل

الخيارات

كيف تظهر خدمتك في لوحة التحكم

الخطوات التالية