AI 2026年6月6日 3 分钟阅读

如何用 Lookspan 监控 AI Agent：本地优先的可观测性实战指南

tinyash 0 条评论

问题：AI Agent 出问题时，你看不到全过程

AI Agent 在生产中跑着。突然它做出了一个错误的数据库删除操作，或者在一个循环里反复调用 API 烧掉了 $50。你知道它出错了，但你没法回答一个最基本的问题：Agent 每一步做了什么？

现有的可观测性工具几乎都是云优先的——它们要你注册账号、提供 API Key，还要把你的 Agent 数据发送到别人的服务器上。对于开发者来说，为了调试一个 Agent 就搭建 Datadog 或去注册另一个 SaaS 是件很重的事情。

Lookspan 是一个本地优先的 AI Agent 可观测性仪表盘，一条命令启动，所有数据存在本地 SQLite，无需注册任何云服务。它支持 OpenAI、Anthropic SDK 的零侵入接入、MCP 工具调用追踪、OpenTelemetry 集成，以及完整的成本和性能监控。

一条命令启动

npx lookspan

打开 http://127.0.0.1:3100，你就拥有了一个完整的可观测性仪表盘。不需要安装，不需要配置，不需要注册——Lookspan 全局安装为零。

如果希望持久化安装：

npm install -g lookspan
lookspan --port 3200 --retention 30

--retention 30 指定保留最近 30 天的追踪数据，自动清理旧记录。

核心概念：Span

Agent 的每次操作——一次 LLM 调用、一次工具执行、一次 MCP 请求——都是一个 Span（跨度）。多个 Span 通过 traceId 和 parentSpanId 组成一个完整的调用链（Trace）。

一个典型的 Agent 执行流程会生成这样的调用链：

User prompt                ← trace 起点
├── tool: search_docs      ← 搜索文档
├── llm_call: gpt-4o       ← LLM 推理
│   └── tool: create_file  ← 执行写入
└── llm_call: claude       ← 再次调用 LLM

Lookspan 的仪表盘会以瀑布图（waterfall）的形式展示这个调用链，每个 Span 显示耗时、Token 消耗、费用和状态。

直接发送 HTTP 追踪数据

最简单的方式是直接 POST JSON 数据到 Lookspan 的 /api/ingest 端点。这种方法适用于任何语言和框架：

curl -X POST http://127.0.0.1:3100/api/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "spans": [{
      "traceId": "trace-001",
      "spanId": "span-001",
      "parentSpanId": null,
      "type": "llm_call",
      "name": "agent.plan",
      "startedAt": "2026-06-05T10:00:00Z",
      "endedAt": "2026-06-05T10:00:03Z",
      "status": "ok",
      "model": "claude-sonnet-4-6",
      "provider": "anthropic",
      "usage": {
        "inputTokens": 2000,
        "outputTokens": 800,
        "costUsd": 0.042
      }
    }]
  }'

对于 Python 应用，也用同样的方式发送：

import requests, time, uuid

def report_span(name, span_type, model, input_tokens, output_tokens):
    span = {
        "traceId": str(uuid.uuid4()),
        "spanId": str(uuid.uuid4()),
        "parentSpanId": None,
        "type": span_type,
        "name": name,
        "startedAt": "2026-06-05T10:00:00Z",
        "endedAt": "2026-06-05T10:00:05Z",
        "status": "ok",
        "model": model,
        "provider": "openai",
        "usage": {
            "inputTokens": input_tokens,
            "outputTokens": output_tokens,
            "costUsd": round(input_tokens * 0.00001 + output_tokens * 0.00003, 6)
        }
    }
    requests.post("http://127.0.0.1:3100/api/ingest",
                  json={"spans": [span]}, timeout=5)

零侵入接入 OpenAI 和 Anthropic SDK

Lookspan 提供了专门的 SDK 封装，一行代码接入，不需要修改已有的 Agent 代码：

OpenAI

npm install @lookspan/openai
import OpenAI from 'openai';
import { observeOpenAI } from '@lookspan/openai';

const openai = observeOpenAI(new OpenAI());
await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: '分析这份日志文件' }]
});
// Lookspan 自动追踪这次调用的 token、耗时、费用

Anthropic

npm install @lookspan/anthropic
import Anthropic from '@anthropic-ai/sdk';
import { observeAnthropic } from '@lookspan/anthropic';

const anthropic = observeAnthropic(new Anthropic());
await anthropic.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: '帮我重构这个函数' }]
});

所有 LLM 调用的输入/输出 Token 数、模型名称、耗时和费用都会被自动记录到 Lookspan 并实时显示。

MCP 工具调用追踪

如果你在用 MCP（Model Context Protocol）连接工具，Lookspan 的 @lookspan/mcp SDK 可以自动包裹 MCP 客户端，让每次工具调用都生成一个 Span：

npm install @lookspan/mcp
import { wrapMcpClient, HttpSpanExporter } from '@lookspan/mcp';

const exporter = new HttpSpanExporter({
  endpoint: 'http://127.0.0.1:3100/api/ingest'
});

const { client } = wrapMcpClient(mcpClient, {
  exporter,
  agentId: 'my-coding-agent'
});

// 用法不变——每次 callTool 自动生成 tool_call Span
const result = await client.callTool({
  name: 'read_file',
  arguments: { path: '/tmp/log.txt' }
});

OpenTelemetry 集成

如果你已经在用 OpenTelemetry 做基础设施监控，无需额外 SDK。Lookspan 在 POST /v1/traces 上监听 OTLP/HTTP 协议。只需配置 OTel SDK 的导出器指向 Lookspan 地址即可。

import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const exporter = new OTLPTraceExporter({
  url: 'http://127.0.0.1:3100/v1/traces'
});

Lookspan 会自动将 gen_ai.* 属性映射为 provider、model 和 token 消耗数据，在仪表盘上呈现统一的视图。

仪表盘核心功能

打开 http://127.0.0.1:3100，你会看到：

概览页：最近追踪列表，每行显示耗时和费用的迷你柱状图，以及运行状态（成功/失败）。

Trace 详情页：

  • 瀑布图（Waterfall）：每个 Span 在时间轴上的位置和父子关系，一眼看出哪个步骤耗时最长
  • 对话记录（Transcript）：完整记录每次 LLM 调用的 Prompt 和 Response
  • 对比回放：同一个 Trace 用不同模型重新执行，对比耗时和费用差异
  • A/B 对比：两个 Trace 的并排比较

成本页：

  • 按天显示总花费
  • 每个 Span 自动计算费用（基于内置模型定价表）
  • 自定义定价覆盖 --pricing pricing.json

告警：

  • Trace 失败时弹出桌面通知
  • 费用/Token/耗时超过阈值自动告警
  • 告警历史持久化

评估：对 Trace 进行人工或 LLM-as-Judge 评分，支持批量运行实验集。

在 CI 中集成 Lookspan

Lookspan 可以作为 CI 流程的一部分来验证 Agent 行为。例如，在 CI 中启动 Lookspan，运行 Agent 测试用例，然后检查 Trace 数据验证没有意外操作：

npx lookspan &
LOOKSPAN_PID=$!
sleep 2

npm run test:agent

curl -s http://127.0.0.1:3100/api/traces | \
  python3 -c "import json,sys; data=json.load(sys.stdin); \
  errors=[t for t in data if t['status']=='error']; \
  print(f'Errors: {len(errors)}'); \
  exit(1 if errors else 0)"

kill $LOOKSPAN_PID

与云方案对比

特性LookspanDatadogLangSmith
本地运行✅ 纯本地❌ 需要注册❌ 需要注册
安装npx lookspan代理安装 + 配置SDK + 平台
数据安全数据永不离开本机上传到 Datadog上传到 LangChain
费用免费按量计费免费层有限
SQLite 持久化✅❌❌
OpenAI SDK 封装✅❌✅
MCP 追踪✅❌❌
告警✅ 桌面通知✅❌
A/B 对比✅❌✅

最佳实践总结

  1. 开发阶段：直接 npx lookspan 启动，用 HTTP ingest 发送数据，查看瀑布图定位性能瓶颈
  2. 集成测试：在 CI 中启动 Lookspan，验证 Agent 不会产生意外的高消耗调用
  3. 生产部署：使用 --retention 30 和 --token your-token 保护端点，数据持久化到 ~/.lookspan/
  4. 多 Agent 场景：不同 Agent 发送不同的 traceId，Lookspan 自动按 Trace 分组展示

总结

Lookspan 解决了一个实际的问题：Agent 代码写好了，但出问题时你看不到中间过程。它用最简单的方式（npx lookspan + 一条 POST 请求）就能建立起完整的可观测性。对于个人开发者和中小团队来说，这比搭建一套 Datadog 或付费使用 LangSmith 要轻量得多。如果你在调试 Agent 行为或只是想了解 Agent 在实际运行中到底做了什么，Lookspan 是一个值得加入工具箱的工具。

AI AI 工具 开发教程 开源 教程

发表评论

你的邮箱地址不会被公开，带 * 的为必填项。