Observability

Waarom observability ingebouwd is

Agents zijn lastig te debuggen door logs te lezen: het interessante gedrag zit in geneste LLM-aanroepen, toolaanroepen en round-trips naar de database. Agent-Lab behandelt observability als een functie van het framework, niet als een losse toevoeging — elk HTTP-request, elke modelaanroep, elke SQL-query en elke uitgaande HTTP-hop wordt een span, geëxporteerd via de industriestandaard OpenTelemetry (met de semantische conventies van OpenLLMetry en OpenInference).

Omdat alles van begin tot eind OTLP is, werkt elke collector-compatibele backend — de Grafana-stack, Elastic, Langfuse, LangWatch of de bestaande APM van je bedrijf.

Wat er wordt geïnstrumenteerd

De setup staat in agent_lab/infrastructure/metrics/tracer.py. Als OTEL_EXPORTER_OTLP_ENDPOINT is ingesteld, wordt het volgende automatisch getraced:

De identiteit van de resource komt uit SERVICE_NAME (standaard Agent-Lab) en SERVICE_VERSION (standaard snapshot). Ruispaden (/status/*, /docs, /openapi.json, favicons) worden door een aangepaste sampler weggefilterd.

Inschakelen

Geen codewijzigingen — alleen een endpoint. Als OTEL_EXPORTER_OTLP_ENDPOINT is ingesteld, gaan spans via OTLP/HTTP naar <endpoint>/v1/traces, /v1/metrics en /v1/logs. Als de variabele niet is ingesteld, staat tracing uit.

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

Voor lokale ontwikkeling regelen twee vooraf geconfigureerde stacks alle koppelingen voor je (vanuit de repository van het framework):

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

Elke stack bevat een eigen configuratie voor de OpenTelemetry Collector, respectievelijk onder otel/grafana/ en otel/opensearch/ — die bestanden zijn de referentie voor hoe traces, metrics en logs worden gerouteerd. Zie de Deploymenthandleiding voor productietopologieën.

Backends voor LLM-observability

Naast pure OTel sluit Agent-Lab aan op speciaal ontwikkelde platforms voor LLM-observability via een TracingBackend-abstractie (gekoppeld als DI-providers in agent_lab/core/container.py). Beide meegeleverde backends worden uitsluitend via omgevingsvariabelen ingeschakeld en schakelen zichzelf stilzwijgend uit als hun variabelen ontbreken, zodat de app altijd opstart.

Langfuse

Stel de drie variabelen uit je Langfuse-project in en elke trace wordt gespiegeld naar het OTLP-endpoint van Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) met langfuse.trace.*-attributen — prompts, completions, tokengebruik en kosten, klaar voor de simulatie-experimenten:

LangWatch

LangWatch legt per bericht een langwatch.trace()-span vast; zo loggen de simulatiesuites de scores van de judge bij experimenten.

Referentiedashboards

Beide handleidingen bevatten demo-opnames van de dashboards in actie.

Uitbreiden: je eigen backend

TracingBackend maakt deel uit van de publieke API. Maak er een subklasse van om spans door te sturen naar je eigen platform, en registreer die op je 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
    ...

De Configuratiereferentie toont alle observability-gerelateerde variabelen in één tabel.