Observabilidade

Por que a observabilidade é nativa

Agentes são difíceis de depurar lendo logs: o comportamento interessante está em chamadas de LLM aninhadas, invocações de ferramentas e idas e vindas ao banco de dados. O Agent-Lab trata a observabilidade como um recurso do framework, e não como um acessório — cada requisição HTTP, chamada de modelo, consulta SQL e chamada HTTP de saída vira um span, exportado via OpenTelemetry, o padrão da indústria (com as convenções semânticas do OpenLLMetry e do OpenInference).

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

O que é instrumentado

A configuração fica em agent_lab/infrastructure/metrics/tracer.py. Com OTEL_EXPORTER_OTLP_ENDPOINT definida, os itens a seguir são rastreados automaticamente:

A identidade do recurso vem de SERVICE_NAME (padrão Agent-Lab) e SERVICE_VERSION (padrão snapshot). Caminhos de ruído (/status/*, /docs, /openapi.json, favicons) são descartados por um sampler personalizado.

Como ativar

Nenhuma mudança de código — apenas um endpoint. Quando OTEL_EXPORTER_OTLP_ENDPOINT está definida, os spans são enviados para <endpoint>/v1/traces, /v1/metrics e /v1/logs via OTLP/HTTP. Quando não está definida, 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 fazem todas as conexões para você (a partir do repositório do 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 sua própria configuração do OpenTelemetry Collector em otel/grafana/ e otel/opensearch/, respectivamente — esses arquivos são a referência de como traces, métricas e logs são roteados. Consulte o guia de implantação para topologias de produção.

Backends de observabilidade de LLM

Além do OTel puro, o Agent-Lab se integra a plataformas de observabilidade de LLM especializadas por meio de uma abstração TracingBackend (conectada como providers de DI em agent_lab/core/container.py). Os dois backends incluídos são ativados apenas por variáveis de ambiente e se desativam silenciosamente quando suas variáveis estão ausentes, de modo que a aplicação sempre inicializa.

Langfuse

Defina as três variáveis do seu projeto Langfuse e todo trace será espelhado no endpoint OTLP do Langfuse ({LANGFUSE_HOST}/api/public/otel/v1/traces) com atributos langfuse.trace.* — prompts, completions, uso de tokens e custos, prontos para os experimentos de simulação:

LangWatch

O LangWatch registra um span langwatch.trace() por mensagem, que é como as suítes de simulação registram as pontuações do juiz nos experimentos.

Dashboards de referência

Os dois guias incluem gravações de demonstração dos dashboards em ação.

Extensã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 registre-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 à observabilidade em uma única tabela.