Obserwowalność

Dlaczego obserwowalność jest wbudowana

Agentów trudno debugować, czytając logi: najciekawsze zachowanie kryje się w zagnieżdżonych wywołaniach LLM, wywołaniach narzędzi i zapytaniach do bazy danych. Agent-Lab traktuje obserwowalność jako funkcję frameworka, a nie dodatek — każde żądanie HTTP, wywołanie modelu, zapytanie SQL i wychodzące połączenie HTTP staje się spanem eksportowanym przez standardowy w branży OpenTelemetry (z konwencjami semantycznymi OpenLLMetry i OpenInference).

Ponieważ od początku do końca jest to OTLP, działa każdy backend zgodny z kolektorem — stos Grafana, Elastic, Langfuse, LangWatch lub istniejące w twojej firmie APM.

Co jest instrumentowane

Konfiguracja znajduje się w agent_lab/infrastructure/metrics/tracer.py. Gdy ustawiono OTEL_EXPORTER_OTLP_ENDPOINT, automatycznie śledzone są:

Tożsamość zasobu pochodzi z SERVICE_NAME (domyślnie Agent-Lab) i SERVICE_VERSION (domyślnie snapshot). Ścieżki generujące szum (/status/*, /docs, /openapi.json, favicony) są odrzucane przez niestandardowy sampler.

Włączanie

Bez zmian w kodzie — wystarczy endpoint. Gdy ustawiono OTEL_EXPORTER_OTLP_ENDPOINT, spany trafiają do <endpoint>/v1/traces, /v1/metrics i /v1/logs przez OTLP/HTTP. Gdy zmienna nie jest ustawiona, śledzenie jest wyłączone.

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

Na potrzeby lokalnego programowania dwa wstępnie skonfigurowane stosy wykonują za ciebie całe łączenie (z repozytorium frameworka):

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

Każdy stos zawiera własną konfigurację OpenTelemetry Collector, odpowiednio w otel/grafana/ i otel/opensearch/ — te pliki są wzorcem tego, jak kierowane są ślady, metryki i logi. Topologie produkcyjne opisuje Przewodnik wdrażania.

Backendy obserwowalności LLM

Poza samym OTel Agent-Lab integruje się z wyspecjalizowanymi platformami obserwowalności LLM przez abstrakcję TracingBackend (podpiętą jako providery DI w agent_lab/core/container.py). Oba dostarczane backendy są włączane wyłącznie przez zmienne środowiskowe i po cichu się wyłączają, gdy brakuje ich zmiennych, dzięki czemu aplikacja zawsze się uruchamia.

Langfuse

Ustaw trzy zmienne ze swojego projektu Langfuse, a każdy ślad będzie powielany do endpointu OTLP Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) z atrybutami langfuse.trace.* — prompty, odpowiedzi, zużycie tokenów i koszty, gotowe do użycia w eksperymentach symulacyjnych:

LangWatch

LangWatch rejestruje span langwatch.trace() dla każdej wiadomości — w ten sposób zestawy symulacji zapisują oceny sędziego w powiązaniu z eksperymentami.

Referencyjne dashboardy

Oba przewodniki zawierają nagrania demonstracyjne dashboardów w działaniu.

Rozszerzanie: własny backend

TracingBackend jest częścią publicznego API. Utwórz jego podklasę, aby przekazywać spany do własnej platformy, i zarejestruj ją w swoim 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
    ...

Dokumentacja konfiguracji zawiera w jednej tabeli wszystkie zmienne związane z obserwowalnością.