قابلية المراقبة

لماذا قابلية المراقبة مدمجة

يصعب تصحيح أخطاء الوكلاء بقراءة السجلات وحدها: فالسلوك المهم يكمن في استدعاءات LLM المتداخلة، واستدعاءات الأدوات، والرحلات ذهاباً وإياباً إلى قاعدة البيانات. يتعامل Agent-Lab مع قابلية المراقبة بوصفها ميزة أساسية في الإطار، لا إضافة لاحقة — فكل طلب HTTP، واستدعاء نموذج، واستعلام SQL، وقفزة HTTP صادرة يتحول إلى span، ويُصدَّر عبر المعيار الصناعي OpenTelemetry (مع الاصطلاحات الدلالية لـ OpenLLMetry وOpenInference).

ولأنه يعتمد OTLP من طرف إلى طرف، فإن أي واجهة خلفية متوافقة مع المُجمِّع تعمل — حزمة Grafana، أو Elastic، أو Langfuse، أو LangWatch، أو نظام APM الحالي في مؤسستك.

ما الذي يُرصد

يوجد الإعداد في agent_lab/infrastructure/metrics/tracer.py. عند ضبط OTEL_EXPORTER_OTLP_ENDPOINT، يجري تتبّع ما يلي تلقائياً:

تأتي هوية المورد من SERVICE_NAME (القيمة الافتراضية Agent-Lab) و SERVICE_VERSION (القيمة الافتراضية snapshot). ويستبعد أخذ عيّنات (sampler) مخصّص المسارات غير المهمة (/status/*، و/docs، و/openapi.json، وأيقونات favicon).

تفعيلها

دون أي تغييرات في الشيفرة — فقط نقطة نهاية. عند ضبط OTEL_EXPORTER_OTLP_ENDPOINT، تتدفق الـ spans إلى <endpoint>/v1/traces و/v1/metrics و/v1/logs عبر OTLP/HTTP. وعند عدم ضبطه، يكون التتبّع متوقفاً.

# Point the app at any OTLP/HTTP collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 uvicorn agent_lab.main:app --reload

للتطوير المحلي، تتولى حزمتان مُعدّتان مسبقاً كل عمليات الربط نيابة عنك (من مستودع الإطار):

docker compose -f compose-grafana.yml up --build      # collector + Prometheus + Tempo + Loki + Grafana
docker compose -f compose-opensearch.yml up --build   # collector + Data Prepper + OpenSearch + Dashboards

تتضمن كل حزمة إعدادات OpenTelemetry Collector الخاصة بها ضمن otel/grafana/ وotel/opensearch/ على التوالي — وهذه الملفات هي المرجع لكيفية توجيه التتبّعات والمقاييس والسجلات. راجع دليل النشر للاطلاع على هيكليات بيئة الإنتاج.

منصات قابلية مراقبة LLM

إلى جانب OTel الخام، يتكامل Agent-Lab مع منصات قابلية مراقبة LLM المتخصصة عبر تجريد TracingBackend (المربوط بوصفه مزوّدات DI في agent_lab/core/container.py). وتُفعَّل الواجهتان الخلفيتان المضمّنتان بالكامل عبر متغيرات البيئة، وتُعطّلان نفسيهما بصمت عند غياب متغيراتهما، وبذلك يقلع التطبيق دائماً.

Langfuse

اضبط المتغيرات الثلاثة من مشروعك في Langfuse، وسيُنسخ كل تتبّع إلى نقطة نهاية OTLP في Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) مع سمات langfuse.trace.* — الموجّهات، والإكمالات، واستهلاك الرموز والتكاليف، جاهزة لـ تجارب المحاكاة:

LangWatch

يسجّل LangWatch لكل رسالة span عبر langwatch.trace()، وبهذه الطريقة تسجّل حزم المحاكاة درجات المُحكِّم مقابل التجارب.

لوحات المعلومات المرجعية

يتضمن كلا الدليلين تسجيلات توضيحية للوحات المعلومات أثناء عملها.

التوسعة: واجهتك الخلفية الخاصة

يُعدّ TracingBackend جزءاً من الواجهة البرمجية العامة. أنشئ فئة فرعية منه لتمرير الـ spans إلى منصتك الخاصة، وسجّلها في Container الخاص بك:

from agent_lab import Container, TracingBackend


class MyBackend(TracingBackend):
    ...  # export spans wherever your platform needs them


class MyContainer(Container):
    # replace or extend the shipped tracing_backends provider list
    ...

يسرد مرجع الإعدادات كل المتغيرات المتعلقة بقابلية المراقبة في جدول واحد.