LangWatch 自定义仪表盘实战指南：五分钟搭出你的第一块 AI 应用监控报表

【免费下载链接】langwatchOpen-Source Agent Observability & Evals for AI Platform teams. Trace, test, route and govern every agent & coding assistant in the company.项目地址: https://gitcode.com/GitHub_Trending/la/langwatch

LangWatch 的数据可视化能力让你把 Trace 数据变成自定义仪表盘：选指标、定聚合、挑图表、设粒度，几步就能生成可保存、可告警、可分享的 AI 应用监控报表。这篇指南带你走完从空白图表到团队共用看板的全过程，所有字段名都来自仓库真实代码。

从一个具体场景说起

昨晚上线了一个新的 AI 客服，今早你第一个问题不是"今天有多少请求"，而是"它答得还行吗，贵不贵，有没有人骂它"。

如果你只有原始 Trace 列表，这三个问题都要手工翻数据。LangWatch 把 Trace 数据预先暴露成一组可图表化的指标——仓库里注册了 25 个图表指标、13 个分组维度、11 种图表类型（见 analytics.chart-series.ts），你只需要回答三个问题：看什么、怎么算、画成什么。仪表盘就是这三个答案的持久化结果。

五分钟搭出第一块仪表盘

流程只有四步，图表构建器（chart builder）会实时预览：

第一步，选指标。指标是带命名空间的字符串，比如metadata.user_id（独立用户数）、performance.completion_time（完成时间）。

第二步，定聚合（aggregation，即"多个数据点怎么压成一个数字"）。系统内置 10 种：sum、avg、min、max、median、p90、p95、p99，以及cardinality（去重计数）和terms（按取值分桶）。注意配对规则是写死在代码里的：ID 类指标只允许cardinality，成本/耗时类指标支持全部数值聚合——配错组合会被合约直接拒绝。

第三步，挑图表。类型清单在 custom-graph.ts 里，共 11 种：line、area、stacked_area、bar、stacked_bar、horizontal_bar、scatter、pie、donnut、summary、monitor_graph。

第四步，设粒度与分组。timeScale以秒为单位决定时间桶大小（也支持full表示整段聚合）；groupBy选 13 个维度之一，比如按metadata.model拆线。保存后，图表配置就是一段可版本管理的 JSON，之后既能在页面上改，也能走 API 改。

哪种图表回答哪类问题

别按图表类型记功能，按你要问的问题选：

经验值：趋势用 line，占比用 donnut，排名用 horizontal_bar，状态用 monitor_graph。同一张图里可以放多条 series（数据系列），每条独立选指标和颜色集（12 套色板，如blueTones、redTones），所以"成本 + 延迟"双指标一张图完全没问题。

看哪些指标才真正有用

25 个指标不必都看。按"先保命、再算账、后提质"排优先级：

第一层：可用性与时延。performance.completion_time（完成时间）、performance.first_token（首 token 时间，流式场景尤其关键）、performance.tokens_per_second（生成速度）。这三个配p95/p99聚合，比看平均值更能暴露长尾问题。流量盘子用metadata.trace_id+cardinality打底。

第二层：成本与用量。performance.total_cost、performance.prompt_tokens/completion_tokens，还有缓存类指标（cache_read_tokens、cache_write_tokens）——缓存命中率上没上去，成本曲线会骗你。

第三层：质量与满意度。evaluations.evaluation_pass_rate（评估通过率）、evaluations.evaluation_score、sentiment.thumbs_up_down（用户点赞点踩）。这层指标通常需要配合key锁定某个评估器，否则口径会混。

让仪表盘有人看：告警与共享

仪表盘建出来没人看等于没建。三个抓手：

• 阈值告警。monitor_graph 是给监控用的图表：配一条告警规则，包含阈值（threshold）、比较运算符、时间窗口和触发动作（邮件或 Slack）。数据越过阈值后，卡片按绿/黄/红三档变色，值班的人扫一眼就知道红没红。monitorGraph.isGuardrail为 true 时它会被当作防护栏类监控对待。
• API 保存与脚本化。图表的增删改查都有 REST 端点，文档在 docs/api-reference/graphs/。把常用看板写成脚本随 CI 更新，避免"每个人手搓一份还不一样"。
• 权限与共享。仪表盘走项目的成员角色体系：查看者只读，编辑者能改配置，管理员完全控制；图表支持生成共享链接，同事点开看到的就是你存的那版配置，不会被对方浏览器里的过滤器带偏。

两份可以直接抄的配方

配方一：AI 客服质量监控。

场景：盯"回复质量有没有变差"。配置要点：主 series 用evaluations.evaluation_pass_rate取avg，按天分桶；第二 series 叠sentiment.thumbs_up_down看点赞率；groupBy选evaluations.evaluation_label区分不同质检项；给通过率那条 series 配阈值告警。看什么结果：通过率曲线和点赞率背离的那天，通常就是模型或提示词改动出了问题。

配方二：多模型性能对比看板。

场景：回答"换到便宜模型到底值不值"。配置要点如下：

{ "graphType": "bar", "groupBy": "metadata.model", "series": [ { "name": "p95 完成时间", "metric": "performance.completion_time", "aggregation": "p95", "colorSet": "greenTones" }, { "name": "总成本", "metric": "performance.total_cost", "aggregation": "sum", "colorSet": "blueTones" } ] }

看什么结果：两根柱并排——延迟没恶化多少、成本掉一半，换模型就有依据；反过来 p95 翻倍，"省钱"就不成立。

它是怎么做到的（选读）

Trace 数据经 OTLP 协议入库，落到 ClickHouse 时序表（架构决策见 analytics ADR）。Analytics 服务负责时序读取，图表查询是"按请求聚合 + 预聚合 rollup 表加速"的组合：常规时间桶直接查 rollup，保证刷新快；明细级下钻才回大表。指标与聚合的合法组合由 Zod 合约在服务端二次校验，前端渲染走 Vega-Lite 声明式图表，同一份 JSON 配置在任意屏幕尺寸下自适应。

延伸

自定义仪表盘的价值在于：监控口径从"每个人脑子里"变成"一段可保存、可告警、可分享的配置"。想继续深入：

• Graphs API 文档：图表的 REST 接口
• 图表构建器合约：11 种图表类型与完整字段定义
• 指标与分组枚举：25 个指标、13 个分组维度的出处

【免费下载链接】langwatchOpen-Source Agent Observability & Evals for AI Platform teams. Trace, test, route and govern every agent & coding assistant in the company.项目地址: https://gitcode.com/GitHub_Trending/la/langwatch