ניטור

למה הניטור מובנה

קשה לנפות באגים בסוכנים באמצעות קריאת לוגים: ההתנהגות המעניינת נמצאת בקריאות LLM מקוננות, בהפעלות של כלים ובסבבים מול מסד הנתונים. Agent-Lab מתייחס לניטור כיכולת של הפריימוורק ולא כתוספת חיצונית — כל בקשת HTTP, קריאה למודל, שאילתת SQL וקריאת HTTP יוצאת הופכות ל-span, שמיוצא באמצעות התקן התעשייתי OpenTelemetry (עם המוסכמות הסמנטיות של OpenLLMetry ו-OpenInference).

מכיוון שהכול מבוסס OTLP מקצה לקצה, כל backend התואם ל-collector עובד — סביבת Grafana, Elastic, Langfuse, LangWatch או ה-APM הקיים בארגון שלך.

מה מנוטר

ההגדרה נמצאת ב-agent_lab/infrastructure/metrics/tracer.py. כאשר OTEL_EXPORTER_OTLP_ENDPOINT מוגדר, הרכיבים הבאים מנוטרים אוטומטית:

זהות המשאב נקבעת לפי SERVICE_NAME (ברירת מחדל Agent-Lab) ו- SERVICE_VERSION (ברירת מחדל snapshot). נתיבי רעש (/status/*, /docs, /openapi.json, favicons) מסוננים על ידי sampler מותאם.

הפעלה

בלי שינויי קוד — רק נקודת קצה. כאשר OTEL_EXPORTER_OTLP_ENDPOINT מוגדר, ה-spans זורמים אל <endpoint>/v1/traces, /v1/metrics ו-/v1/logs באמצעות OTLP/HTTP. כשהוא אינו מוגדר, ה-tracing כבוי.

# 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/ בהתאמה — קבצים אלה הם המקור המוסמך לאופן הניתוב של traces, מדדים ולוגים. לטופולוגיות של סביבת ייצור, ראו את מדריך הפריסה.

backends לניטור LLM

מעבר ל-OTel הגולמי, Agent-Lab מתחבר לפלטפורמות ייעודיות לניטור LLM דרך הפשטה בשם TracingBackend (המחווטת כ-providers של DI ב-agent_lab/core/container.py). שני ה-backends המצורפים מופעלים אך ורק באמצעות משתני סביבה, ומשביתים את עצמם בשקט כשהמשתנים שלהם חסרים, כך שהאפליקציה תמיד עולה.

Langfuse

מגדירים את שלושת המשתנים מפרויקט ה-Langfuse שלך, וכל trace משוכפל לנקודת הקצה של OTLP ב-Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) עם מאפייני langfuse.trace.* — פרומפטים, השלמות, צריכת טוקנים ועלויות, מוכנים לניסויי הסימולציה:

LangWatch

LangWatch רושם span של langwatch.trace() לכל הודעה, וכך חבילות הסימולציה מתעדות את ציוני השופט מול הניסויים.

דשבורדים לדוגמה

שני המדריכים כוללים הקלטות הדגמה של הדשבורדים בפעולה.

הרחבה: backend משלך

TracingBackend הוא חלק מה-API הציבורי. יורשים ממנו כדי להעביר 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
    ...

חומר העזר לתצורה מרכז את כל המשתנים הקשורים לניטור בטבלה אחת.