AI SDK Next.js OpenAI Sentry构建带 OpenTelemetry 可观测性的 AI 聊天应用完整示例【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读本文围绕当前仓库中的 next-openai-telemetry-sentry 示例展开它是 AI SDKThe AI Toolkit for TypeScript官方示例中AI 应用 × 错误监控 × 链路追踪三合一的实战模板使用 Next.js 搭建服务端 API 与前端界面、通过ai-sdk/openai调用 OpenAI 模型生成文本并接入 Sentry 完成错误捕获与 OpenTelemetry 可观测性数据采集。读完本文你将掌握该示例从零启动的完整流程环境变量、依赖安装、开发服务器、核心代码的逐段解读以及 AI SDK Telemetry 体系functionId、runtimeContext、recordInputs/recordOutputs与 Sentry 集成在源码层面的工作原理。示例概览一个最小可观测的 AI 聊天应用该示例构建了一个 ChatGPT 风格的 AI 流式聊天机器人雏形但技术栈上有意叠加了两层可观测能力层次技术选型作用AI 生成AI SDKai包ai-sdk/openai调用 OpenAI 模型完成文本生成Web 框架Next.jsApp Router提供 API 路由Node.js Runtime与前端页面错误监控sentry/nextjs捕获服务端/客户端异常并上报 Sentry链路追踪OpenTelemetryvercel/otel与opentelemetry/*系列采集 AI 调用的 span、token 用量与延迟数据从仓库中该示例的目录结构可以看出其职责划分完整结构见 examples/next-openai-telemetry-sentryexamples/next-openai-telemetry-sentry/ ├── app/ │ ├── api/text/route.ts # AI 生成 API核心业务逻辑 │ ├── global-error.tsx # 全局错误边界异常上报 Sentry │ ├── layout.tsx / page.tsx # 前端页面与布局 │ └── globals.css ├── instrumentation.ts # 按运行时nodejs/edge加载 Sentry 配置 ├── instrumentation-client.ts # 浏览器端 Sentry 初始化 ├── sentry.server.config.ts # 服务端 Sentry 初始化 ├── sentry.edge.config.ts # Edge 运行时 Sentry 初始化 ├── next.config.ts # 通过 withSentryConfig 包装 Next 配置 └── package.json # 依赖与脚本package.json 中的依赖与示例的定位完全对应ai与ai-sdk/openai负责 AI 能力sentry/nextjs示例锁定的版本为^10.53.1与sentry/opentelemetry负责错误与追踪vercel/otel、opentelemetry/api-logs、opentelemetry/instrumentation、opentelemetry/sdk-logs组成 OpenTelemetry 基础设施next^15.5.21与react^18.3.1提供运行时zod用于后续扩展结构化输出时的模式校验。脚本提供dev、build、start、lint四个常用命令。环境准备OpenAI 与 Sentry 的前置条件在本地运行示例前需要完成两类账号与密钥的准备1. OpenAI 侧在 OpenAI 开发者平台注册账号进入 API Keys 管理页面创建 API Key将 Key 设置为环境变量OPENAI_API_KEY示例代码中通过openai(gpt-5-mini)指定模型实际调用时依赖该变量注入凭证。2. Sentry 侧在 Sentry 创建一个新项目后需要从项目设置中复制四个值并配置为环境变量环境变量来源用途SENTRY_ORG项目设置中的 Organization Slug构建期用于上传 Source Map 的 org 标识SENTRY_PROJECT项目设置中的 Project Slug构建期用于上传 Source Map 的项目标识SENTRY_AUTH_TOKEN项目设置中的 Auth Token构建期认证凭据NEXT_PUBLIC_SENTRY_DSN项目设置中的 DSN运行时上报错误/追踪的接入地址NEXT_PUBLIC_前缀使其可被浏览器端读取这四个变量的消费点分别位于 next.config.tsorg、project与三个 Sentry 初始化文件dsn。其中SENTRY_ORG、SENTRY_PROJECT、SENTRY_AUTH_TOKEN仅在构建上传 Source Map 时使用而 DSN 是运行时数据上报的入口二者缺一不可。快速开始引导示例并本地运行方式一使用 create-next-app 引导推荐该示例作为 AI SDK 官方示例可以通过create-next-app的--example参数直接从仓库引导。在仓库根目录执行三种包管理器任选其一# npm npx create-next-app --example ./examples/next-openai-telemetry-sentry next-openai-telemetry-sentry-app # Yarn yarn create next-app --example ./examples/next-openai-telemetry-sentry next-openai-telemetry-sentry-app # pnpm pnpm create next-app --example ./examples/next-openai-telemetry-sentry next-openai-telemetry-sentry-app方式二直接在示例目录中运行也可以直接进入 examples/next-openai-telemetry-sentry 目录操作但需注意该仓库采用 pnpm workspace 管理见根目录 pnpm-workspace.yaml依赖ai、ai-sdk/openai等均以workspace:*形式链接因此统一使用 pnpm 安装才能正确解析工作区依赖pnpm install # 安装依赖 pnpm dev # 启动开发服务器默认 3000 端口无论采用哪种方式本地启动前都要完成上一节的环境变量配置参照示例说明中.env.local.example的格式创建.env.local文件。启动后访问页面点击Generate按钮前端会向后端/api/text发起 POST 请求得到生成结果后展示在页面上。同时在 Sentry 后台可以看到本次请求的 trace 与 span 数据。核心代码解读前端页面一次请求的完整生命周期app/page.tsx 是一个use client客户端组件状态管理包含三部分generation生成结果文本、isLoading请求中标识、error异常对象。点击按钮后通过fetch(/api/text, { method: POST, body: JSON.stringify({ prompt: Why is the sky blue? }) })调用后端解析返回 JSON 中的text字段并渲染任何异常都会进入error状态并以红色文本展示。这个页面刻意保持了最小化设计——它演示的是如何把一次 AI 生成请求完整地放进可观测体系这一主题而非复杂的聊天交互。API 路由AI 生成 Telemetry 元数据核心业务逻辑在 app/api/text/route.tsimport { openai } from ai-sdk/openai; import { generateText } from ai; export async function POST(req: Request) { const { prompt } await req.json(); const { text } await generateText({ model: openai(gpt-5-mini), maxOutputTokens: 100, prompt, runtimeContext: { example: value, }, telemetry: { functionId: example-function-id, }, }); return new Response(JSON.stringify({ text }), { headers: { Content-Type: application/json }, }); }这段代码集中展示了 AI SDK 生成文本 API 的四个关键参数参数示例值作用modelopenai(gpt-5-mini)选择 OpenAI 模型ai-sdk/openai提供该工厂函数maxOutputTokens100限制输出最大 token 数控制生成成本与长度runtimeContext{ example: value }传入运行期上下文供应用逻辑使用telemetry.functionIdexample-function-id为本次调用打上业务标识便于在 Sentry / 追踪平台中分组与检索其中functionId是 AI SDK Telemetry 体系的核心字段下文会结合 Telemetry 官方文档深入展开。Sentry 集成三层运行时 构建期配置该示例对 Sentry 的接入覆盖了 Next.js 的全部运行时与构建期是理解Next.js 项目如何正确接入 Sentry的完整范本。1. instrumentation.ts按运行时动态加载instrumentation.ts 是 Next.js 的插桩入口import * as Sentry from sentry/nextjs; export async function register() { if (process.env.NEXT_RUNTIME nodejs) { await import(./sentry.server.config); } if (process.env.NEXT_RUNTIME edge) { await import(./sentry.edge.config); } } export const onRequestError Sentry.captureRequestError;通过process.env.NEXT_RUNTIME判断当前是 Node.js 还是 Edge 运行时分别加载对应的初始化配置导出onRequestError Sentry.captureRequestError让 Next.js 在请求处理出错时自动交给 Sentry 捕获。2. sentry.server.config.ts 与 sentry.edge.config.ts服务端/边缘配置服务端配置与 边缘配置内容一致均执行import * as Sentry from sentry/nextjs; Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, tracesSampleRate: 1, enableLogs: true, debug: false, });关键选项tracesSampleRate: 1以 100% 采样率开启链路追踪生产环境建议调低或改用tracesSampler做精细采样控制enableLogs: true启用日志上报debug: false关闭初始化调试输出。3. instrumentation-client.ts浏览器端初始化客户端配置面向浏览器场景init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, integrations: [replayIntegration()], tracesSampleRate: 1, enableLogs: true, replaysSessionSampleRate: 0.1, replaysOnErrorSampleRate: 1.0, debug: false, }); export const onRouterTransitionStart captureRouterTransitionStart;除常规项外它还启用了Session Replay会话回放并导出了onRouterTransitionStart将 Next.js 的路由切换也纳入 Sentry 追踪。采样策略上普通会话以 10% 采样replaysSessionSampleRate: 0.1出错会话则 100% 录制replaysOnErrorSampleRate: 1.0兼顾成本与排障价值。4. next.config.ts构建期 Source Map 上传next.config.ts 使用withSentryConfig包装配置export default withSentryConfig( {}, { org: process.env.SENTRY_ORG, project: process.env.SENTRY_PROJECT, silent: !process.env.CI, widenClientFileUpload: true, disableLogger: true, }, );org/project上传 Source Map 时标识组织与项目对应前文两个环境变量silent: !process.env.CI仅在 CI 环境打印上传日志widenClientFileUpload: true上传更完整的客户端文件集以换取更清晰的堆栈会增加构建时间disableLogger: true自动摇树移除 Sentry 日志语句以减小打包体积。5. global-error.tsx全局错误边界app/global-error.tsx 是客户端组件形式的全局错误边界在useEffect中调用Sentry.captureException(error)主动上报未被捕获的异常并渲染通用的NextError页面App Router 不暴露 HTTP 状态码故传入statusCode{0}。深入原理AI SDK Telemetry 与 Sentry 的配合OpenTelemetry 是 AI SDK 的可观测性底座AI SDK 使用 OpenTelemetry 采集遥测数据。标准做法是在应用启动时安装ai-sdk/otel并注册集成官方文档见 content/docs/03-ai-sdk-core/60-telemetry.mdxpnpm install ai-sdk/otelimport { registerTelemetry } from ai; import { OpenTelemetry } from ai-sdk/otel; registerTelemetry(new OpenTelemetry());Next.js 项目则通常把注册动作放在instrumentation.ts中与vercel/otel的registerOTel一起完成import { registerOTel } from vercel/otel; import { registerTelemetry } from ai; import { OpenTelemetry } from ai-sdk/otel; export function register() { registerOTel({ serviceName: my-ai-app }); registerTelemetry(new OpenTelemetry()); }注册后所有 AI SDK 调用默认都会产出 telemetry 事件ai-sdk/otel的OpenTelemetry集成按OpenTelemetry GenAI Semantic Conventions输出 span——例如generateText会产生invoke_agent {modelId}根 span覆盖整个操作与全部工具调用、chat {modelId}步骤 span每次模型调用一个与execute_tool {toolName}工具 span属性统一使用gen_ai.*前缀包含输入输出消息、token 用量、finish reasons 与耗时等。本示例中的 Telemetry 配置意味着什么回到 route.ts其中两处配置对应官方文档中的两个概念telemetry.functionId为调用赋予业务级标识会被写入 span 的resource.name与gen_ai.agent.name等属性是跨请求检索某个业务函数的所有 AI 调用的关键维度runtimeContext携带运行期上下文。官方文档特别强调runtimeContext可能包含不应外泄到遥测平台的值如用户 ID、租户 ID、凭证因此提供了telemetry.includeRuntimeContext白名单机制——只有被标记为true的顶层属性才会进入 telemetry 数据telemetry: { includeRuntimeContext: { requestId: true, // 只有 requestId 会被送入遥测 }, },此外还有两个按调用粒度的开关值得在生产中使用telemetry: { isEnabled: false, // 对敏感调用整体退出遥测 recordInputs: false, // 不记录输入含敏感信息时常用 recordOutputs: false, // 不记录输出 }recordInputs/recordOutputs默认为true出于隐私、传输与性能考虑可按需关闭isEnabled提供调用级 opt-out遥测整体是 opt-out 制全局禁用只需不调用registerTelemetry。Sentry通过原生 telemetry channel 无侵入采集 AI 调用本示例之所以能在不显式调用registerTelemetry(new OpenTelemetry())的情况下让 Sentry 看到 AI 调用链路原因记录在仓库的 Sentry 可观测性文档中Sentry 的 Next.js / Node.js SDK 通过 Node.js 原生 telemetry channel 直接采集 AI SDK v7 的调用数据因此无需安装ai-sdk/otel或调用registerTelemetry。从源码结构看这一机制的前提是Sentry 服务端 SDK 版本需在10.62.0及以上示例的^10.53.1属于较新基线升级即可满足原生 telemetry channel 仅在 Node.js 运行时可用因此 AI 生成路由需运行在 Node.js Runtime而非 Edge这与本示例app/api/text/route.ts的默认运行方式一致。Sentry 会自动捕获generateText、streamText、模型调用、工具调用、嵌入、重排、token 用量与错误等 span在 Sentry 界面中可以看到gen_ai.invoke_agent、gen_ai.generate_content、gen_ai.execute_tool等 span。配合functionId即可在 Sentry 中快速定位与分组特定业务函数的 AI 调用。关于提示词与响应内容的记录Sentry 默认只采集模型、供应商、延迟、token 用量与错误等元数据输入输出内容需要显式开启。两种开启方式全局开启初始化时Sentry.init({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 1.0, dataCollection: { genAI: { inputs: true, outputs: true, }, }, });或按单次 AI 调用开启const result await generateText({ model: openai(gpt-5-mini), prompt: Summarize this support ticket., telemetry: { functionId: support-summary, recordInputs: true, recordOutputs: true, }, });对于包含敏感信息的调用将telemetry.isEnabled设为false即可退出 Sentry 的 AI 遥测。部署到 Vercel该示例同样支持一键部署到 Vercel详见 示例 README 的 Deploy your own 一节从本示例仓库创建新项目配置环境变量OPENAI_API_KEY必须设置用于运行时调用 OpenAISENTRY_ORG、SENTRY_PROJECT、SENTRY_AUTH_TOKEN、NEXT_PUBLIC_SENTRY_DSN四个 Sentry 变量也需一并填入部署后即可在线上环境验证错误监控与链路追踪。延伸阅读与下一步如果你希望把该示例的观测能力迁移到自己的项目推荐顺序是阅读 AI SDK Telemetry 官方文档掌握 span 结构、functionId/runtimeContext/includeRuntimeContext/includeToolsContext、自定义 Tracernew OpenTelemetry({ tracer })与enrichSpan自定义属性等进阶能力阅读 Sentry 可观测性文档了解 Next.js 与纯 Node.js 两种接入方式、vercelAIIntegration()的手动开启方式以及dataCollection.genAI的内容采集策略参考 AI SDK Observability Integrations 索引对比其他可观测性后端选择与 Sentry 能力互补的监控平台。掌握本示例后你就拥有了一套开箱即用的 AI 应用可观测性脚手架前端发起请求、后端调用模型、Sentry 同时收集错误与 trace而这一切都建立在 AI SDK 标准的 Telemetry 抽象之上可平滑迁移到任何支持 OpenTelemetry 的观测后端。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考