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

مقدمة

بعد التثبيت، فعّل تتبّع الطلبات لترى ضمن الطلبات في لوحة التحكم كل طلب عالجته خدمتك مع مساره ومدته واستعلاماته واستدعاءاته الخارجية — ولتفتح الطلب الذي تسبّب في أي خطأ. راجع تتبّع الطلبات لما تعرضه لوحة التحكم.

التفعيل

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 نفسها.

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

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

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

tracer = lerix.get_client().tracing.tracer

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

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

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

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

البدء

أطر العمل

الوحدات

المطورون

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

مقدمة

التفعيل

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

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

أخذ العينات

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

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

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

​مقدمة

​التفعيل

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

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

​أخذ العينات

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

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

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

مقدمة

التفعيل

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

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

أخذ العينات

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

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

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