可观测性 · Agent-Lab

为什么内置可观测性

仅靠阅读日志很难调试智能体：真正值得关注的行为发生在嵌套的 LLM 调用、工具调用和数据库往返之中。Agent-Lab 将可观测性视为框架自身的功能，而不是事后附加的组件——每个 HTTP 请求、模型调用、SQL 查询和出站 HTTP 跳转都会成为一个 span，并通过业界标准的 OpenTelemetry 导出（采用 OpenLLMetry 和 OpenInference 语义约定）。

由于端到端都基于 OTLP，任何兼容 Collector 的后端都可以使用——Grafana 技术栈、Elastic、Langfuse、LangWatch，或者你公司现有的 APM。

哪些内容会被插桩

相关设置位于 agent_lab/infrastructure/metrics/tracer.py。设置 OTEL_EXPORTER_OTLP_ENDPOINT 后，以下内容会被自动追踪：

插桩器	你能看到的内容
FastAPI	每个请求对应一个服务端 span，包含路由、状态码和耗时
HTTPX	智能体或服务发出的每一次出站 HTTP 调用
LangChain	每一次 LLM/链调用及其 token 用量——智能体追踪的核心
OpenAI	OpenAI 原生调用（OpenInference 约定）
SQLAlchemy	每一条数据库语句（关系型、向量搜索、检查点）

资源标识来自 SERVICE_NAME（默认为 Agent-Lab）和 SERVICE_VERSION（默认为 snapshot）。噪声路径（/status/*、/docs、/openapi.json、favicon）会被自定义采样器丢弃。

启用可观测性

无需修改代码——只需提供一个端点。 设置 OTEL_EXPORTER_OTLP_ENDPOINT 后，span 会通过 OTLP/HTTP 发送到 <endpoint>/v1/traces、/v1/metrics 和 /v1/logs。未设置时，追踪处于关闭状态。

# 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

每套技术栈分别在 otel/grafana/ 和 otel/opensearch/ 下附带各自的 OpenTelemetry Collector 配置——这些文件就是追踪、指标和日志如何路由的参考。生产环境的拓扑结构请参阅部署指南。

LLM 可观测性后端

除了原生 OTel 之外，Agent-Lab 还通过 TracingBackend 抽象（在 agent_lab/core/container.py 中作为 DI provider 装配）接入专门构建的 LLM 可观测性平台。两个内置后端都完全通过环境变量启用，并会在缺少相应变量时静默禁用自身，因此应用总能正常启动。

Langfuse

设置 Langfuse 项目中的三个变量后，每条追踪都会被镜像到 Langfuse 的 OTLP 端点（{LANGFUSE_HOST}/api/public/otel/v1/traces），并带有 langfuse.trace.* 属性——提示词、补全结果、token 用量和成本，可直接用于模拟实验：

变量	用途
`LANGFUSE_HOST`	Langfuse 基础 URL
`LANGFUSE_PUBLIC_KEY`	`pk-lf-…`
`LANGFUSE_SECRET_KEY`	`sk-lf-…`

LangWatch

变量	用途
`LANGWATCH_ENDPOINT`	LangWatch 端点
`LANGWATCH_API_KEY`	LangWatch API 密钥

LangWatch 会为每条消息记录一个 langwatch.trace() span，模拟测试套件正是借此将评审（judge）分数与实验关联记录。

参考仪表盘

技术栈	指南	UI
Grafana + Prometheus + Tempo + Loki	otel/GRAFANA.md	http://localhost:3000
OpenSearch Dashboards	otel/OPENSEARCH.md	http://localhost:5601

两份指南都包含仪表盘实际运行的演示录屏。

扩展：接入你自己的后端

TracingBackend 是公共 API 的一部分。继承它即可将 span 转发到你自己的平台，然后在你的 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
    ...

配置参考在一张表中列出了所有与可观测性相关的变量。