> ## 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.

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

> نطاق واحد لكل طلب في FastAPI وFlask وDjango، ونطاقات psycopg وhttpx/requests، وأخذ العينات، والتتبّع خلف كل خطأ.

## مقدمة

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

## التفعيل

```python theme={"dark"}
import lerix

lerix.init(api_key="...", project_id="...", tracing={"enabled": True})
```

التتبّع معطَّل افتراضياً؛ وعندما يكون معطَّلاً لا تُستورد حزمة
`lerix.tracing` ولا يُثبَّت أي خطاف. يأتي نطاق الطلب نفسه من تكامل إطار
العمل الذي سجّلته مسبقاً:

| إطار العمل | التكامل | قالب المسار |
| - | - | - |
| FastAPI / Starlette | `LerixMiddleware` | `GET /users/{user_id}` |
| Flask | `LerixFlask(app)` | `GET /items/<int:item_id>` |
| Django | `lerix.integrations.django.LerixMiddleware` | `GET /things/<int:pk>/` |

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

* **نطاق خادم واحد لكل طلب**، يُسمّى بحسب قالب المسار لا المسار الخام.
  تُواصَل ترويسة `traceparent` الواردة وفق معيار W3C.
* **PostgreSQL** — `psycopg` (الإصدار 3) و`psycopg2`، وبالتالي Django
  وSQLAlchemy على Postgres أيضاً. يصبح كل استعلام نطاق `client` باسم قالب
  SQL ‏(`SELECT * FROM users WHERE id = ?`)؛ لا تُسجَّل المعاملات ولا الصفوف.
* **HTTP الخارجي** — `httpx` (المتزامن وغير المتزامن) و`requests`. يصبح كل
  استدعاء نطاق `client` باسم `METHOD host` ويحمل ترويسة `traceparent`
  لتواصل الخدمة اللاحقة التتبّع. تُتجاهل الاستدعاءات إلى Lerix API نفسها.

يمكن تعطيل كل خطاف على حدة:

```python theme={"dark"}
lerix.init(tracing={"enabled": True, "instrumentations": {"psycopg": True, "httpx": True, "requests": False}})
```

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

```python theme={"dark"}
tracer = lerix.get_client().tracing.tracer

with tracer.child("cache get", "client", {"server.address": "redis"}):
    cache.get(key)
```

تُنهي الكتلة النطاق بحالة `error` إذا رفعت استثناءً. خارج الطلب المتتبَّع
لا يفعل `tracer.child(...)` شيئاً.

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

```python theme={"dark"}
ctx = lerix.current()
log.info("handling order, trace %s", ctx.trace_id if ctx else None)
```

يتبع السياق عمليات `await` وتبديل المهام (فهو متغيّر `contextvars`)؛ أما
الخيط الذي تبدؤه بنفسك فلا يرثه.

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

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

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

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

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

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

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

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

| الخيار | الافتراضي | الوصف |
| - | - | - |
| `flush_interval` | `5.0` | الثواني بين عمليات التصدير عندما لا تكتمل الدفعة |
| `max_queue_size` | `2048` | النطاقات المحتفَظ بها في الذاكرة قبل إسقاط الجديدة |
| `max_batch_size` | `512` | النطاقات لكل طلب تصدير |
| `request_timeout` | `10.0` | مهلة طلب التصدير الواحد بالثواني |

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


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