使用 Litefuse 实现 Mastra 的可观测性
本指南演示如何将 Litefuse 与 Mastra 集成，实现可观测性与 tracing。按这些步骤操作，你将能在 Litefuse 控制台中监控并调试你的 Mastra Agent。
什么是 Mastra？ Mastra 是一个 TypeScript Agent 框架，旨在为构建 AI 应用提供必需的基础组件。它让开发者能够创建具备记忆和工具调用能力的 AI Agent，实现确定性的 LLM 工作流，并利用 RAG 进行知识集成。
什么是 Litefuse？ Litefuse 是一个开源的 AI Agent 可观测性与评估平台。它为 AI 应用提供 tracing 与监控能力。
集成
创建 Mastra 项目
如果你还没有 Mastra 项目，可以使用 Mastra CLI 创建一个：
npx create-mastra进入项目目录：
cd your-mastra-project完整的 Mastra 安装说明请查看 这里
设置 Litefuse 项目
在 Litefuse 中创建一个项目，并在项目设置页面获取你的 API Key。
添加环境变量
创建或更新你的 .env.development（或 .env）文件，添加以下变量：
# Your LLM API key
OPENAI_API_KEY=your-api-key
# Langfuse credentials
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_BASE_URL=https://litefuse.cloud # Optional. Defaults to https://litefuse.cloud安装 @mastra/langfuse 包
向你的项目中添加 @mastra/langfuse 包：
npm install @mastra/langfuse设置 Agent
在你的项目中创建一个 Agent。例如，新建一个文件 agents/chefAgent.ts：
import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
export const chefAgent = new Agent({
name: "chef-agent",
instructions:
"You are Michel, a practical and experienced home chef " +
"You help people cook with whatever ingredients they have available.",
model: openai("gpt-4o-mini"),
});ai-sdk 中的任何模型提供方。注册 Agent 并配置 Litefuse
创建或更新你的 Mastra 实例配置，注册 Agent 并配置 Litefuse 集成。例如，新建一个文件 mastra.ts：
import { Mastra } from "@mastra/core";
import { LangfuseExporter } from "@mastra/langfuse";
import { chefAgent } from "./agents/chefAgent";
export const mastra = new Mastra({
agents: { chefAgent },
observability: {
configs: {
langfuse: {
serviceName: "my-service",
exporters: [
new LangfuseExporter({
publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
secretKey: process.env.LANGFUSE_SECRET_KEY!,
baseUrl: process.env.LANGFUSE_BASE_URL,
options: {
environment: process.env.NODE_ENV,
},
}),
],
},
},
},
});运行 mastra dev 服务器
启动 Mastra 开发服务器：
npm run dev打开提供的 URL 进入开发者 playground，开始与你的 Agent 聊天。
在 Litefuse 中查看 Trace
进入你的 Litefuse 控制台，你将看到来自 Agent 交互的 trace。你可以分析 prompt、completion 以及 AI 交互中的其他细节。
下面是一个 trace 的示例：
配置选项
实时 vs 批处理模式
Litefuse exporter 支持两种发送 trace 的模式：
- 实时（开发）：每个事件后立即刷新，便于实时观察。
new LangfuseExporter({
publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
secretKey: process.env.LANGFUSE_SECRET_KEY!,
realtime: true, // Flush after each event
})- 批处理（生产，默认）：缓冲并批量发送，吞吐量更佳。
new LangfuseExporter({
publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
secretKey: process.env.LANGFUSE_SECRET_KEY!,
realtime: false, // Default behavior
})完整配置
new LangfuseExporter({
// Required credentials
publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
secretKey: process.env.LANGFUSE_SECRET_KEY!,
// Optional settings
baseUrl: process.env.LANGFUSE_BASE_URL, // Defaults to https://litefuse.cloud
realtime: process.env.NODE_ENV === "development",
logLevel: "info", // debug | info | warn | error
// Langfuse-specific options
options: {
environment: process.env.NODE_ENV,
version: process.env.APP_VERSION,
release: process.env.GIT_COMMIT,
},
})排错
- NextJS 集成问题：如果你在 NextJS 应用中将 Mastra 与 Litefuse 一起使用时遇到问题，请参考 Mastra NextJS tracing 文档 获取 NextJS 专用的配置与设置说明。
- Litefuse 中没有 trace：确认你的凭证正确，并参考此 排错指南
参考
- Mastra Litefuse Exporter：文档、npm
- Mastra 文档
- Litefuse 文档