observability

assistant-ui 可观测性

请始终查阅 assistant-ui.com/llms.txt，获取最新 API。

可观测性分为两个独立层。Langfuse、LangSmith 和 Helicone 用于检测后端模型调用。@assistant-ui/react-o11y 用于呈现应用已收集的 span 数据。它不会向服务提供方发送追踪数据，也不会从助手运行时派生 span。

参考资料

• ./references/langfuse.md -- Langfuse 的 OpenTelemetry 设置、追踪属性和无服务器刷新。
• ./references/langsmith.md -- LangSmith 的 wrapAISDK、元数据和无服务器刷新。
• ./references/helicone.md -- AI SDK 和 OpenAI SDK 路由的 Helicone 代理设置。
• ./references/react-o11y.md -- SpanResource、所有导出的 span 原语部分、span 契约、时间线属性，以及带样式的 TraceWaterfall 选项。

选择后端集成

根据所需的数据模型选择一个服务提供方。

• Langfuse 接收启用 experimental_telemetry 后由 AI SDK 发出的 OpenTelemetry span。适用于跨越 Agent 回合、工具调用和模型调用的分层追踪。
• LangSmith 通过 wrapAISDK(ai) 封装 AI SDK 函数。适用于需要将追踪、评估和提示词管理与 LangChain 或 LangGraph 工具链结合使用的场景。
• Helicone 代理服务提供方请求。适用于记录请求日志、成本、延迟和提示词差异，且无需更改 AI SDK 调用形式的场景。

Langfuse 和 Helicone 可以同时运行，因为前者使用 OpenTelemetry span，后者代理服务提供方流量。LangSmith 使用独立的封装路径，因此应使用其封装后的 AI SDK 函数，而不是原始函数。

实现顺序

1. 选择负责遥测数据目标位置的服务提供方集成。
2. 添加其服务器环境变量，并配置启动检测或服务提供方。
3. 检测一个路由，并验证真实请求是否到达服务提供方仪表板。
4. 在生产环境中依赖追踪数据之前，添加无服务器刷新。
5. 仅当产品需要应用内追踪视图时，使用 react-o11y 呈现单独的 SpanData[] 数据流。

路由处理器边界

将服务提供方凭据和检测逻辑保留在服务器端。每个示例都使用 openai("gpt-5.6-luna")，等待 convertToModelMessages(messages) 完成，并返回 AI SDK UI 消息响应。集成页面不会使用 assistant-ui 路由辅助函数。如果路由需要该辅助函数，请从 @assistant-ui/ai-sdk 导入；对于较旧的安装，@assistant-ui/react-ai-sdk 会重新导出同一 API。

根据真实的身份验证和会话状态解析追踪属性。不要在客户端组件中放入服务提供方密钥、Langfuse 用户 ID、LangSmith 元数据或 Helicone 标头。

呈现已收集的 span

SpanResource({ spans }) 接受完整的原始 SpanData[] 列表，规范化父子关系，按可见 span 的开始时间排序，并管理折叠状态。请将其挂载在独立的服务提供方根节点下：

const config = AuiConfig({ span: SpanResource({ spans }) });

<AuiProvider extends={null} config={config}>
  <SpanPrimitive.Children components={{ Span: SpanRow }} />
</AuiProvider>;

SpanRow 组件会自动限定在单个可见 span 的范围内。如果各行必须共享时间轴，请使用 SpanPrimitive.Timeline 和 SpanPrimitive.TimelineBar。如果带样式的扁平消息和工具瀑布图更适合现有数据，请使用复制的 TraceWaterfall 元素。

常见问题

在 Vercel、Lambda 或其他无服务器运行时中，追踪记录消失

• Langfuse 需要在函数退出前调用 await langfuseSpanProcessor.forceFlush()，或使用特定于部署的 waitUntil 路径。
• LangSmith 需要在函数退出前调用 await client.awaitPendingTraceBatches()。

Langfuse 没有跨度

• 在每个被追踪的 streamText 或 generateText 调用中设置 experimental_telemetry: { isEnabled: true }。
• 仅在 Node 运行时注册 LangfuseSpanProcessor。OpenTelemetry 不会在边缘运行时中运行。

LangSmith 未追踪该路由

• 调用从 wrapAISDK(ai) 解构的函数，而不是从 ai 导入的原始函数。
• 在运行时环境中设置 LANGSMITH_TRACING=true。

Helicone 流量仍直接发送到 OpenAI

• 提供方的 baseURL 必须为 https://oai.helicone.ai/v1，且请求必须携带 Helicone-Auth 以及提供方授权标头。

react-o11y 视图未渲染任何行

• 使用 AuiConfig({ span: SpanResource({ spans }) }) 挂载 SpanResource，并在 <AuiProvider extends={null} config={config}> 下方渲染。
• 传入完整的 SpanData[] 列表。SpanPrimitive.Children 会读取当前跨度作用域，不会获取追踪记录。

缺少文档中提到的跨度组件

• 当前源码未重新导出 SpanPrimitive.ChildByIndex。如果需要显式指定索引作用域，请使用导出的 SpanByIndexProvider 和行组件。

相关技能

• 流式传输 -- AI SDK 流传输和路由响应处理。
• 设置 -- 项目创建、CLI 设置和运行时安装。
• 云 -- Assistant Cloud 持久化和运行报告配置。
• 元素 -- 复制的样式化元素，包括 TraceWaterfall。