> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerix.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# NestJS — تتبّع الطلبات

> نطاق واحد لكل طلب، ونطاقات PostgreSQL وfetch الخارجية، وأخذ العينات، والتتبّع خلف كل خطأ — لخدمات NestJS.

## مقدمة

بعد [التثبيت](/ar/frameworks/nestjs/installation)، فعّل تتبّع الطلبات لترى
ضمن **الطلبات** في لوحة التحكم كل طلب عالجته خدمتك مع مساره ومدته
واستعلاماته واستدعاءاته الخارجية — ولتفتح الطلب الذي تسبّب في أي خطأ.
راجع [تتبّع الطلبات](/ar/modules/request-tracing) لما تعرضه لوحة التحكم.

## التفعيل

```ts app.module.ts theme={"dark"}
LerixModule.forRoot({
  apiKey: process.env.LERIX_API_KEY!,
  projectId: process.env.LERIX_PROJECT_ID!,
  tracing: { enabled: true },
})
```

مع `forRootAsync` مرّر أيضاً العلامة الثابتة ليُسجَّل المعترض عند بناء
الوحدة:

```ts theme={"dark"}
LerixModule.forRootAsync({
  tracing: true,
  useFactory: (config: ConfigService) => ({ ...config.get('lerix'), tracing: { enabled: true } }),
  inject: [ConfigService],
})
```

التتبّع معطَّل افتراضياً؛ وعندما يكون معطَّلاً لا يُحمَّل كود التتبّع أصلاً
(يقع في جزء منفصل من الحزمة).

## ما الذي يُسجَّل

* **نطاق خادم واحد لكل طلب**، ينشئه معترض عام ويُسمّى بحسب **قالب المسار**
  من مسارَي المتحكّم والمعالج (`GET /users/:id`) لا بحسب الرابط. البادئة
  العامة للتطبيق ليست جزءاً من الاسم. تُواصَل ترويسة `traceparent` الواردة.
* **PostgreSQL** — يُعدَّل مشغّل `pg` الخاص بالتطبيق (يُعثر عليه من مجلد
  العمل؛ لا يُضاف شيء إلى اعتمادياتك)، وهو ما يغطي Drizzle وTypeORM وKnex
  و`pg` المباشر. يصبح كل استعلام نطاق `client` باسم قالب SQL؛ لا تُسجَّل
  المعاملات ولا الصفوف أبداً.
* **`fetch` الخارجي** — يصبح كل استدعاء نطاق `client` باسم `METHOD host`
  ويحمل ترويسة `traceparent`. تُتجاهل الاستدعاءات إلى Lerix API نفسها.

يمكن تعطيل أي من الخطافين:

```ts theme={"dark"}
tracing: { enabled: true, instrumentations: { pg: true, fetch: false } }
```

ويمكن تتبّع أي شيء آخر يدوياً عبر `LerixService`:

```ts theme={"dark"}
const handle = this.lerix.tracing?.tracer.startChild('cache get', 'client', { 'server.address': 'redis' });
try {
  await cache.get(key);
  handle?.end('ok');
} catch (error) {
  handle?.end('error', { 'error.type': (error as Error).name });
  throw error;
}
```

يحتاج النطاق الفرعي إلى طلب ينتمي إليه: خارج الطلب المتتبَّع لا تفعل
الخطافات شيئاً.

## التتبّع الحالي

معرّف التتبّع متاح في أي مكان داخل الطلب عبر `current()`، مثلاً لوضعه في
سجلاتك:

```ts theme={"dark"}
import { current } from '@lerix-dev/lerix-nestjs';

this.logger.log(`handling order, trace ${current()?.traceId}`);
```

## أخذ العينات

| الخيار | الافتراضي | الوصف |
| - | - | - |
| `sampleRate` | `0.1` | نسبة الطلبات الناجحة المحفوظة كاملةً. تُقرَّر مرة عند الجذر وتُورَّث لاحقاً. |
| `slowThresholdMs` | `2000` | الطلب الأبطأ من هذا يُحفظ كاملاً دائماً. |
| `maxSpansPerRequest` | `1000` | النطاقات الفرعية المحتفَظ بها لكل طلب حتى ينتهي. |

الطلبات الفاشلة والطلبات التي أبلغت عن خطأ تُحفظ كاملةً دائماً. ويُرسل
النطاق الجذر لكل طلب مهما كان، فتغطي أعداد المسارات ونسبها المئوية في لوحة
التحكم 100% من الحركة.

## الأخطاء والتتبّعات

كل تقرير خطأ يُرسل داخل طلب — تقارير المرشّح التلقائي وكذلك استدعاءاتك
لـ `captureException` / `captureMessage` — يحمل تتبّع ذلك الطلب، فتعرض
صفحة المشكلة الشلال مضمَّناً مع تمييز الاستعلام الفاشل. أما الخطأ المُبلَّغ
عنه خارج أي طلب (مهمة، فحص عند الإقلاع) فيُسجَّل كالسابق دون تتبّع مرفق.

## عناوين العملاء

يحمل كل نطاق طلب عنوان عميله، مُحدَّداً وفق ما يطلبه المشروع ضمن **إعدادات
المشروع ← التتبّع**: في الوضع الافتراضي `masked` تصفّر حزمة SDK آخر خانة من
IPv4 أو تقتطع IPv6 إلى /64 قبل إرسال أي شيء؛ وفي وضعَي `hashed` و`full`
يُعالَج العنوان في جانب Lerix. يحدد عدد الوكلاء الموثوقين والترويسة كيفية
قراءته من `X-Forwarded-For`؛ ولا تُوثَق السلسلة كاملةً أبداً.

## خيارات المصدّر

| الخيار | الافتراضي | الوصف |
| - | - | - |
| `flushIntervalMs` | `5000` | كم مرة تُرسل النطاقات المصفوفة عندما لا تكتمل الدفعة |
| `maxQueueSize` | `2048` | النطاقات المحتفَظ بها في الذاكرة قبل إسقاط الجديدة |
| `maxBatchSize` | `512` | النطاقات لكل طلب تصدير |
| `requestTimeoutMs` | `10000` | مهلة طلب التصدير الواحد |

تغادر النطاقات بصيغة OTLP/HTTP JSON. إذا تعذّر الوصول إلى Lerix API تُحسب
الدفعة وتُسقط؛ لا إعادة محاولة، ولا حجب لأي طلب، ولا استثناء يصل إلى كودك.
العدّادات في `LerixService.tracing?.stats()`.

## الحِمل الإضافي

بالقياس على مسار بسيط بـ 20,000 طلب متتابع: نحو **+30 ميكروثانية في المتوسط
لكل طلب** (p50 ‏+20 ميكروثانية)، إضافة إلى نحو 5 ميكروثانية لكل استعلام
و8 ميكروثانية لكل استدعاء خارجي للخطافات.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.