VoltAgent User Analytics：按用户分组 Trace、按会话聚合并联动反馈信号的排查方法

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载在 VoltAgent 的 VoltOps 可观测平台中User Analytics用户分析页面把零散的 trace 按用户维度重新组织让你从感觉哪里不对劲快速定位到具体的用户、会话session/conversation乃至单条 trace。本文基于官方文档 User Analytics 展开并结合仓库中 OpenTelemetry 埋点与导出的源码实现讲清楚用户与会话标识是如何进入 trace 体系的、Users 页面上三大模块Key Metrics、User Feedback、Conversations各自解决什么问题以及如何设计一次从指标异常到单条 trace 的完整排查路径。为什么需要按用户维度看 Trace单条 trace 回答的是这一次请求内部发生了什么而用户问题往往跨越多次请求某个用户连续三天不满意、某类会话成本异常高、某个版本发布后特定用户群的成功率下降。Users 页面正是为此设计的聚合视图——它按 user 分组 trace帮助你判断问题影响了谁、集中在哪里which user is impacted and where issues concentrate。排查路径因此被压缩为三级跳转用户 → 会话Conversation/Session→ 单条 Trace。这与 Tracing 总览 中的过滤器设计一脉相承总览页提供 Status、Duration、Token usage / Cost、User ID / Conversation ID 等过滤条件其中User ID / Conversation ID过滤器就是专门用来钻进某一个用户旅程的入口与 Users 页面形成互补。前置条件让 trace 带上用户与会话标识Users 页面的分组能力依赖于每条 trace 上携带用户与会话信息。在 VoltAgent 中这一步通过agent.run的运行选项完成参考 Observability Setup 文档const agent new Agent({ name: Support Agent, model: openai(gpt-4), instructions: Help users with their questions, }); await agent.run(Hello, { userId: user-123, conversationId: conv-456, });字段说明userId将 trace 关联到具体用户Associates traces with a specific userconversationId按会话对 trace 进行分组Groups traces by conversation从源码结构看这两个选项最终落成 OpenTelemetry 的 span 属性并且是公共属性——在 trace-context.ts 中TraceContext构造时会把user.id、conversation.id以及operation.id、父 agent 信息等写入commonAttributes被该次运行的所有子 span 继承// Store common attributes once - these will be inherited by all child spans const commonAttributes: Recordstring, any { ...(options.userId { user.id: options.userId }), ...(options.conversationId { conversation.id: options.conversationId }), ...(parentAgentId { agent.parent.id: parentAgentId }), ...(parentAgentName { agent.parent.name: parentAgentName }), operation.id: options.operationId, };这意味着无论一次运行中发生多少次 LLM 调用、多少次工具执行用户与会话标识都会随整条 trace 链路一起上报为后续按用户/会话聚合提供了数据基础。数据如何到达观测平台两条上报路径根据部署形态trace 可以走两条路径二者在用户/会话如何映射为 trace 级字段上的逻辑是文档排查的关键VoltOps 托管路径自动检测在 Setup 文档 中说明配置VOLTAGENT_PUBLIC_KEYpk_xxxx与VOLTAGENT_SECRET_KEYsk_live_xxxx两个环境变量后VoltAgent 会自动检测并连接 VoltOps无需额外观测代码需要更细粒度控制时可用VoltOpsClient显式传入密钥或用createVoltAgentObservability配置服务名、采样策略always/never/ratio/parent、队列与批量导出参数等。Langfuse 自托管路径LangfuseExporter 作为 OpenTelemetrySpanExporter实现把 span 批转换为 Langfuse 的 trace/span/generation通过 README 中的示例挂载到VoltAgent的telemetryExporterimport { Agent, VoltAgent } from voltagent/core; import { LangfuseExporter } from voltagent/langfuse-exporter; const langfuseExporter new LangfuseExporter({ publicKey: process.env.LANGFUSE_PUBLIC_KEY, secretKey: process.env.LANGFUSE_SECRET_KEY, baseUrl: process.env.LANGFUSE_BASE_URL, // 可选默认 Langfuse Cloud // debug: true, // 可选开启导出器详细日志 }); new VoltAgent({ agents: { myAgent }, telemetryExporter: langfuseExporter, });LangfuseExporter在export时按traceId将本批 span 分组逐 trace 调用processTraceSpans其中的extractTraceInfo负责从任意 span 的属性里提取 trace 级信息用户与会话的取值优先级值得注意exporter.ts用户 ID优先enduser.id其次user.id会话 ID优先session.id其次conversation.idtrace 名称优先voltagent.agent.name其次entity.name另外还会提取tags、langfuseTraceId、langfuseUpdateParent。当updateParent为真默认值时buildTraceParams会把userId、sessionId、tags、输入输出、metadata 与模型名写入 trace 记录exporter.ts。这也解释了为什么在应用侧只传userId/conversationId两个字段平台侧就拥有了 Users 页面所需的分组键。Users 页面模块一Key Metrics关键指标Key Metrics 提供对**请求量volume、成功率success rate、延迟latency、成本cost**随时间变化的快速纵览。官方文档给出的使用定位是用它判断当前问题属于质量、性能还是花费中的哪一类并把回归regression关联到模型切换等变更上。实操建议是把 Key Metrics 当作排查的第一道分诊台成功率下跌→ 优先在 trace 列表用 Status 过滤器隔离失败或重试较多的运行再进入具体 trace 的 Waterfall 视图看哪一步失败延迟抬升→ 结合 Duration 过滤器找慢 trace关注 LLM 调用的首 chunk 延迟与工具调用耗时成本突增→ 用 Token usage / Cost 过滤器定位高价运行并核对是否与模型切换、prompt 变长相关——这正是文档强调link regressions to model switches的场景。Users 页面模块二User Feedback用户反馈User Feedback 模块把用户情绪转化为可跟踪的信号一方面用于确认修复是否真正改善了体验对比修复前后另一方面用于看清用户最在意哪些问题。文档说明该模块的图表可以呈现反馈量feedback volume、情绪趋势sentiment trends、评分聚集score clusters、主导反馈键dominant feedback keys以及用户留下评论的时间点。这与单条 trace 级的 Trace Feedback 文档构成总—分关系trace 级反馈关注三个要点——History 与来源确认这条 trace 被评过分、评分来自 app/API/model 哪一端、Key 与 Score保持信号一致例如统一使用 satisfaction 键以便跨运行比较、Comments用简短上下文说明输出为何好或坏。排查时的组合打法是在 Users 页的反馈图表中发现某类反馈键差评聚集再通过反馈源/反馈键过滤器下钻到具体 trace核对评论与当时的模型输出。Users 页面模块三Conversations会话视图Conversations 模块按 session会话分组 trace让你能端到端地跟随一条用户流程。每个会话以卡片形式呈现四个字段Status该会话内运行是否出现失败Time range会话的时间跨度帮助区分长对话与一次性请求Model会话中使用的模型便于关联模型切换带来的行为差异Cost会话累计成本用于发现异常昂贵的对话流。文档给出的使用手法很直接从卡片中挑出最可疑的会话然后把 trace 列表过滤到该会话路径上继续分析。结合前文源码部分可知会话卡片的数据基础正是运行选项conversationId写入的conversation.id属性——若你的应用没有为多轮对话维持稳定的conversationIdConversations 视图就无法把多轮 trace 归并为一个会话这一点在集成时值得优先保证。一次典型排查路径从指标到 trace综合上述模块可以沉淀出如下可复现的排查流程分诊在 Users 页 Key Metrics 中确认异常维度成功率 / 延迟 / 成本与时间范围定位用户查看受影响用户列表找到问题集中的用户定位会话在 Conversations 中按 Status / Time range / Model / Cost 四张卡片锁定最可疑会话下钻 trace把 trace 列表过滤到该会话结合 总览文档 中的 Status、Duration、Token usage / Cost 过滤器找到失败或昂贵的单条运行归因与验证打开 Waterfall / Node-Based 视图定位失败步骤并检查 User Feedback 与 trace 级 Feedback来源、key、score、comment修复后再回到 Key Metrics 与反馈趋势图验证指标与情绪是否回升。小结与适用前提Users 页面的三大模块各有分工Key Metrics 判断问题类型User Feedback 判断用户感受Conversations 定位具体哪条会话路径分组能力的前提是应用侧在agent.run中正确传入userId与conversationId它们在 trace-context.ts 中成为全链路继承的公共属性上报路径支持 VoltOps 环境变量自动接入与LangfuseExporter自托管两种形态自托管路径的用户/会话字段映射逻辑可在 exporter.ts 中直接查阅本文描述的行为以当前仓库文档与源码为准控制台的展示细节如图表具体样式可能随平台版本演进建议以实际 Setup 后在控制台中观察到的界面为准。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐es-toolkit 的 invertBy 使用指南反向映射对象键值并按组聚合es toolkit 的 invertBy 使用指南反向映射对象键值并按组聚合 invertBy 是 es toolkit 的 lodash 兼容层 es前端后端agno 如何读取 Agent 运行轨迹的 trace 并聚合按天的 metrics 指标agno 如何读取 Agent 运行轨迹的 trace 并聚合按天的 metrics 指标 在 agno 的 AgentOS 上运行 Agent 后你会经常人工智能大模型AI AgentAgent 框架多智能体工具调用RAGAgent 工作流Agent 记忆Hugo Pages.GroupByPublishDate 方法详解按发布时间分组页面并排序Hugo Pages.GroupByPublishDate 方法详解按发布时间分组页面并排序 本文是 Hugo 页面集合方法系列中的一篇聚焦于 Pages.开发工具前端CLI上一篇Obsidian中文社区论坛免费开源5 分钟跑起来的 Markdown 论坛下一篇m4s转mp4保姆级教程3 步合并B站缓存视频换设备也能随时看创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考