signoz 2天前 · 2026-11-07 22:34:30 · 0 阅读

使用 OpenTelemetry 实现 Vercel AI SDK 的可观测性与监控

Vercel AI SDK 的可观测性功能让你能够查看 Next.js 应用中 AI 函数调用、请求耗时、输入输出以及自定义元数据。本指南介绍如何配置 OpenTelemetry 埋点，捕获 Vercel AI SDK 生成的 traces 和 spans，并将数据发送到 SigNoz。在 SigNoz 中获得完整的 Vercel AI SDK 可观测性后，你可以端到端追踪 AI 交互、排查延迟问题、在性能劣化时设置告警，并提升 AI 功能的可靠性。对于生产级的 Vercel 可观测性场景尤为实用，因为了解模型行为和用户交互至关重要。可以查看 SigNoz Vercel AI SDK 示例聊天机器人，其中已包含基于 OpenTelemetry 的可观测性与监控。提示

如果你也在使用 Vercel？可以通过 SigNoz 的 Vercel 集成转发部署日志和 traces。如果你的 Agent 在沙箱中运行生成的代码，请参阅 Vercel Sandbox 可观测性。

前置条件

Next.js 应用
已集成 Vercel AI SDK
SigNoz 环境（二选一）：
- SigNoz Cloud 账户，并持有有效的 ingestion key
- 自托管的 SigNoz 实例
应用可访问所选的 SigNoz 端点

用 OpenTelemetry 埋点 Next.js 应用

关于 Next.js 的详细 OpenTelemetry 埋点说明，请参阅 Next.js OpenTelemetry 埋点指南。

基于 OpenTelemetry 配置 Vercel AI SDK 可观测性

步骤 1. 安装 OpenTelemetry 依赖包

Copy

npm install @vercel/otel @opentelemetry/api

步骤 2. 更新 next.config.mjs，启用 instrumentationHook

仅在使用 Next.js 14 及以下版本时需要此步骤

Copy

/** @type {import('next').NextConfig} */
const nextConfig = {
  // include instrumentationHook experimental feature
  experimental: {
    instrumentationHook: true,
  },
}
export default nextConfig

步骤 3. 创建 instrumentation.ts 文件（位于项目根目录）

Copy

import { registerOTel, OTLPHttpJsonTraceExporter } from '@vercel/otel'
// 添加 otel 日志记录
import { diag, DiagConsoleLogger, DiagLogLevel } from '@opentelemetry/api'
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR) // 调试时将 diag 日志级别设置为 DEBUG
export function register() {
  registerOTel({
    serviceName: '<service_name>',
    traceExporter: new OTLPHttpJsonTraceExporter({
      url: 'https://ingest.<region>.signoz.cloud:443/v1/traces',
      headers: { 'signoz-ingestion-key': '<your-ingestion-key>' },
    }),
  })
}

<service_name> 是你的服务名称
<region>：你的 SigNoz Cloud 区域
<your-ingestion-key>：你的 SigNoz 摄入密钥

instrumentation 文件应放在项目根目录，而不是 app 或 pages 目录内。如果使用了 src 文件夹，请将文件放在 src 内，与 pages 和 app 同级。

Info

使用自托管的 SigNoz？大多数步骤相同。如需适配此指南，请更新端点并移除摄入密钥头部，具体操作请参考云端到自托管。

你的 Next.js 应用现在已经正确插桩。

步骤 4. 在本地验证插桩

以开发模式运行你的 Next.js 应用：

Copy

npm run dev

应用启动时，终端会出现 OpenTelemetry 输出，确认 instrumentation.ts 文件已正确加载。

显示 OpenTelemetry 初始化的终端输出 — 运行应用时显示 OpenTelemetry 初始化的输出

若需查看详细的追踪导出日志，可临时将 instrumentation.ts 中的 DiagLogLevel 设置为 DEBUG：

Copy

diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.DEBUG)

启用 Vercel AI SDK 遥测

Vercel AI SDK 使用 OpenTelemetry 收集遥测数据。OpenTelemetry 是一个开源可观测性框架，旨在为遥测数据的采集提供标准化的插桩方案。

开启遥测

关于可用遥测选项的更多细节，请参考 Vercel AI SDK 遥测文档。

在该功能还处于实验阶段时，你可以通过 experimental_telemetry 选项为特定的函数调用开启遥测：

Copy

const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'Write a short story about a cat.',
  experimental_telemetry: { isEnabled: true },
})

开启遥测后，你还可以控制是否记录函数的输入值和输出值。默认情况下两者都会记录，若要关闭，只需将 recordInputs 和 recordOutputs 选项设为 false。

Copy

experimental_telemetry: { isEnabled: true, recordInputs: false, recordOutputs: false}

出于隐私、数据传输量或性能方面的考虑，关闭输入和输出的记录可能会很有用。比如，当输入包含敏感信息时，你可能就不希望记录它们。

遥测元数据

你可以提供 functionId 来标识遥测数据对应的函数，并通过 metadata 在遥测数据中附加额外信息。

Copy

const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'Write a short story about a cat.',
  experimental_telemetry: {
    isEnabled: true,
    functionId: 'my-awesome-function',
    metadata: {
      something: 'custom',
      someOtherThing: 'other-value',
    },
  },
})

自定义 Tracer

你可以传入一个 tracer，它必须返回一个 OpenTelemetry 的 Tracer。当你希望 trace 使用 @opentelemetry/api 单例之外的 TracerProvider 时，这个选项会很有用。

Copy

const tracerProvider = new NodeTracerProvider()
const result = await generateText({
  model: openai('gpt-4-turbo'),
  prompt: 'Write a short story about a cat.',
  experimental_telemetry: {
    isEnabled: true,
    tracer: tracerProvider.getTracer('ai'),
  },
})

完成配置后，Vercel AI SDK 的指令会自动产生 traces、spans 和 events。关于生成的 span 和 event 类型，请参阅 Vercel AI SDK 采集数据参考。

在 SigNoz 的 Traces 标签页中，可以查看到 Vercel AI SDK 的 traces：

点击任意一个 span，即可查看其所属的详细 trace。

Detailed Traces View — 你的 Vercel AI 应用的详细 Trace 视图

在 AI Observability 中查看

AI Observability 展示了你的 Vercel AI SDK 调用的成本、token 用量、延迟和错误。在 SigNoz 中，打开 AI Observability，并在 service_name 过滤器中选择你的服务。

Token 和成本总和翻倍

外层 span（例如 ai.generateText）及其内层的 doGenerate 或 doStream span 都携带了模型和 token 计数信息。由于 AI Observability 对每次调用都计算了两次，因此 Overview 和 Trace View 中的 token 和成本总和是实际值的两倍。要获取正确总和，请打开 Explorer，选择 Table，添加聚合 sum(gen_ai.usage.input_tokens)、sum(gen_ai.usage.output_tokens) 和 sum(signoz.gen_ai.usage.tokens.cost)，并使用 name LIKE 'ai.%.do%' 进行过滤。

AI Observability Overview dashboard with the cost, token, and latency panels for LLM calls — AI Observability Overview 仪表盘

要查询单条 trace，请打开 Explorer 标签页。Trace View 中每条 trace 占一行，显示 tokens、成本、调用次数等汇总数据。你可以按这些汇总字段进行筛选、聚合和排序，例如 trace.total_tokens > 1000。详情请参阅 AI Observability Explorer。

如果面板一直为空，请检查你的 span 是否包含 Telemetry Requirements 中列出的属性。如需映射其他属性名，可以使用 Attribute Mapping。

Vercel AI SDK 可观测性仪表盘

Vercel AI SDK Observability Dashboard 提供了专门用于监控 AI 应用的可视化面板，其中包含专为 Vercel AI SDK 遥测数据定制的预置图表和指标，并附有导入说明，帮助你快速上手。

使用 OpenTelemetry 实现 Vercel AI SDK 的可观测性与监控

前置条件

用 OpenTelemetry 埋点 Next.js 应用

基于 OpenTelemetry 配置 Vercel AI SDK 可观测性

启用 Vercel AI SDK 遥测

开启遥测

遥测元数据

自定义 Tracer

在 AI Observability 中查看

Vercel AI SDK 可观测性仪表盘

相关集成

评论 (0)