Observabilidade

Porque é que a observabilidade vem integrada

Os agentes são difíceis de depurar através da leitura de registos: o comportamento relevante está em chamadas LLM aninhadas, invocações de ferramentas e idas e voltas à base de dados. O Agent-Lab trata a observabilidade como uma funcionalidade da framework, e não como um acrescento — cada pedido HTTP, chamada a um modelo, consulta SQL e salto HTTP de saída torna-se um span, exportado através do standard da indústria OpenTelemetry (com as convenções semânticas do OpenLLMetry e do OpenInference).

Como é OTLP de ponta a ponta, qualquer backend compatível com o collector funciona — stack Grafana, Elastic, Langfuse, LangWatch ou o APM já existente na sua empresa.

O que é instrumentado

A configuração encontra-se em agent_lab/infrastructure/metrics/tracer.py. Com OTEL_EXPORTER_OTLP_ENDPOINT definido, os seguintes elementos são rastreados automaticamente:

A identidade do recurso provém de SERVICE_NAME (predefinição Agent-Lab) e de SERVICE_VERSION (predefinição snapshot). Os caminhos de ruído (/status/*, /docs, /openapi.json, favicons) são descartados por um sampler personalizado.

Ativar a observabilidade

Sem alterações ao código — apenas um endpoint. Quando OTEL_EXPORTER_OTLP_ENDPOINT está definido, os spans são enviados para <endpoint>/v1/traces, /v1/metrics e /v1/logs por OTLP/HTTP. Quando não está definido, o tracing fica desativado.

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

Para desenvolvimento local, duas stacks pré-configuradas tratam de toda a ligação (a partir do repositório da 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

Cada stack inclui a sua própria configuração do OpenTelemetry Collector em otel/grafana/ e otel/opensearch/, respetivamente — esses ficheiros são a referência sobre a forma como traces, métricas e registos são encaminhados. Consulte o guia de deployment para topologias de produção.

Backends de observabilidade de LLM

Para além do OTel puro, o Agent-Lab liga-se a plataformas de observabilidade de LLM dedicadas através de uma abstração TracingBackend (registada como providers de DI em agent_lab/core/container.py). Ambos os backends incluídos são ativados apenas através de variáveis de ambiente e desativam-se silenciosamente quando as respetivas variáveis estão em falta, pelo que a aplicação arranca sempre.

Langfuse

Defina as três variáveis do seu projeto Langfuse e todos os traces são replicados para o endpoint OTLP do Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) com atributos langfuse.trace.* — prompts, respostas, utilização de tokens e custos, prontos para as experiências de simulação:

LangWatch

O LangWatch regista um span langwatch.trace() por mensagem, que é a forma como as suites de simulação registam as pontuações do juiz associadas às experiências.

Dashboards de referência

Ambos os guias incluem gravações de demonstração dos dashboards em funcionamento.

Extensão: o seu próprio backend

TracingBackend faz parte da API pública. Crie uma subclasse para encaminhar spans para a sua própria plataforma e registe-a no seu 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
    ...

A Referência de configuração lista todas as variáveis relacionadas com observabilidade numa única tabela.