AI 2026年6月24日 2 分钟阅读

Latitude 实战指南：用 Issue-centric 开源 AI 监控平台给 Agent 装上故障预警系统

tinyash 0 条评论

你有没有遇到过这种场景：AI Agent 在开发环境跑得好好的，一上线就开始间歇性抽风——某个 tool call 今天成功明天失败，用户投诉了才发现问题，而你只能靠翻 JSONL trace 日志逐行排查？

这不是你的 Agent 写得不好，而是 AI Agent 的生产调试方式还停留在「出事了翻日志」的阶段，和当年的后端服务没有 Sentry 之前一模一样。

Latitude 是什么

Latitude 是一个开源的 AI Agent 可观测性和监控平台，定位就是 Sentry for AI Agents。它把 LLM 调用、tool call、多轮对话的 trace 数据自动采集、聚类成结构化 Issues，并提供基于语义搜索的 trace 检索能力。

项目地址：github.com/latitude-dev/latitude-llm（4221 ⭐，LGPL-3.0 开源协议，也提供商业许可）

核心能力四句话：

  • Issue-centric：失败的 trace 自动聚类成问题，标注状态、规模和趋势
  • Human-aligned evals：基于团队人工判断自动生成评估指标，追踪与人工判断的一致性漂移
  • Agent-native traces：支持多轮会话、tool call 调用链、全执行路径的一体化视图
  • Semantic search：按语义搜索任意 trace，不做采样，100% trace 数据可检索

快速上手

安装 & 接入

npm install @latitude-data/telemetry

在你的 Agent 入口文件中初始化：

import { Latitude } from "@latitude-data/telemetry";

new Latitude({
  apiKey: process.env.LATITUDE_API_KEY!,
  projectSlug: process.env.LATITUDE_PROJECT_SLUG!,
  instrumentations: ["openai"],
});

instrumentations 参数指定要自动接入的 LLM 提供商。目前支持 OpenAI、Anthropic、Bedrock、Vercel AI SDK、LangChain 等主流方案，也兼容任何 OTLP 后端。

配置好后，每次 LLM 调用都会自动出现在 Latitude 的 trace 列表中——你现在能看到每个请求的耗时、token 消耗和完整响应。

获取 API Key

去 latitude.so 注册账号，创建一个 Project 就能拿到 LATITUDE_API_KEY 和 LATITUDE_PROJECT_SLUG。也支持自托管部署（LGPL-3.0 协议），详细指南在文档中。

实战场景 1：用 Claude Code 配合 Latitude 自动捕获会话轨迹

如果你是 Claude Code 用户，Latitude 提供了专用的 Telemetry 包：

npx -y @latitude-data/claude-code-telemetry install

这个命令会在 Claude Code 中注入 trace 采集层。之后每次你在终端里用 Claude Code 写代码、调 API、修 bug，完整的会话轨迹（包括每一步的 tool call、每次 LLM 请求、最终输出）都会自动发送到 Latitude。

实际效果：你写了一个小程序，Claude Code 调用了 3 次文件读写 + 2 次 shell 命令。如果其中有一步失败（比如文件路径写错了），Latitude 不会只显示「错误」两个字，而是把整条 trace 链路展开——哪一步失败的、当时的 prompt 是什么、返回了什么错误信息、后续步骤有没有产生级联影响。

实战场景 2：用 Issue-centric 视图定位生产环境的高频故障

这是 Latitude 最核心的价值。当你的 AI Agent 在生产环境运行一段时间后，Latitude 会自动做两件事：

  1. Trace 聚类：将所有失败的 trace 按根因自动分组。同一个 prompt 模板在不同时间返回不同结果、同一个 tool call 因为超时而失败多次——这些不会分散在日志里，而是聚合到一个 Issue 条目中。
  2. Issue 跟踪：每个 Issue 有 status（open / investigating / resolved）、size（影响范围）、trend（恶化还是改善）。

比如你的 AI Agent 的 search_knowledge_base 工具在过去一小时内失败了 47 次，Latitude 会创建一个 Issue：「search_knowledge_base — 超时异常（47 次，呈上升趋势）」。点击进去能看到所有相关 trace 的时间线、每次的输入参数和错误信息、以及最近的触发模式变化。

这种聚合方式的好处是：你不必一条条翻 trace——问题已经被归类和优先级排序了，从最高频的 Issue 开始修就行了。

实战场景 3：用 Human-aligned Evals 持续追踪 Agent 行为质量

传统的 eval 方法是定义一组测试用例，在 CI 中跑完就算通过。但问题在于：你定义的 eval 和真实用户的实际判断之间可能存在偏差，而且这种偏差会随时间扩大（因为 LLM 行为在变）。

Latitude 的 Human-aligned evals 解决的是这个问题：

  1. 你的团队在日常使用中通过 Latitude UI 给 trace 打标记（「这个回答很好」「这个 tool call 不该发生」）
  2. Latitude 自动从这些人工标记中学习，生成一组 eval 指标
  3. 持续追踪这些 eval 指标与最新人工判断之间的一致性（alignment score）
  4. 当 alignment score 下降时，说明 Agent 行为已经开始偏离团队期望了——在人发现之前就能预警

实际操作：团队每周花 10 分钟在 Latitude 上标注 20-30 条 trace，系统就能生成可靠的 eval 基准。这比写 200 个固定测试用例更接近真实场景，而且随着业务变化会自动适应。

最佳实践

  1. 先接 trace，再谈观察：不要等出了问题再配置。在 Agent 开发阶段就接入 Latitude，积累基线数据——这样生产环境出异常时，你才有「正常时的 trace」做对比。
  2. 善用语义搜索：Latitude 的语义搜索支持按含义查找 trace，不需要精确匹配关键词。比如搜「用户说价格不对」，能返回所有与价格计算相关的 Agent 对话。这对于处理模糊的用户投诉特别有用。
  3. Eval 覆盖关键路径：优先为你 Agent 中最核心的 3-5 个 tool call 或决策点设置 eval 标注。不需要全量标注，关键路径的覆盖率比总量更重要。
  4. 结合 CI/CD：利用 Latitude 的 Issue 跟踪能力，可以在 CI 流程中加入 trace 健康检查——如果最近一轮 trace 中新增了高优 Issue，先排查再部署。
  5. 自托管部署：如果数据隐私要求高，Latitude 支持自托管。LGPL-3.0 协议下可以自由部署在自有基础设施上（注意商业使用可能需要商业许可）。

总结

Latitude 定位精准——它不是另一个「LLM 调用日志查看器」，而是一个 面向 AI Agent 生产环境的故障管理系统。Issue-centric 的设计让团队从「被动翻日志」转向「主动修复高影响问题」，Human-aligned evals 则解决了传统 eval 与真实用户判断脱节的核心矛盾。

如果你正在维护一个已经上线的 AI Agent 服务，或者计划在下一个项目中引入 Agent 架构，Latitude 值得在你的 observability 栈中占一个位置。

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

发表评论

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