LangWatch 自定义仪表盘指南：4 步搭出 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

日常巡检时，你发现某个模型的 token 消耗这一周翻了三倍，翻遍日志和调用记录，半天也没定位到原因。用 LangWatch 数据可视化，可以把分散的 Trace 数据变成自定义仪表盘，不写 SQL 也能搭出属于自己的 AI 应用监控报表。

场景：token 消耗突然不对劲

上周五，值班工程师发现某客服 agent 的日 token 消耗是平时的三倍。第一反应是逐条打开 Trace（一次 AI 请求调用的完整记录），在调用详情里核对时间、模型名和 token 数。

麻烦在于这些数据是"平"的：模型、用户、话题、评估结果全都摊在 metadata 里，回答"到底是谁多用了"要人肉交叉好几个字段。管几个 agent 的团队还撑得住，几十个 agent 就没法靠人翻了。

出路不是攒更多数据，而是换一种问法：不做"翻找单个异常"，改用"聚合指标 + 分组维度"，让仪表盘直接回答。

分散的 Trace 数据如何变成自定义仪表盘

LangWatch 把每次 AI 调用记为一条 Trace，Trace 内部最小的执行单元叫 Span（例如一次 LLM 请求或一次工具调用）。每条 Trace 都带一组结构化字段：总耗时、首 token 时间、prompt/completion tokens、成本、模型名、用户 ID、评估结果等。

dashboard 模块（源码见 modules/dashboard/）直接基于这些字段渲染图表。不需要写 SQL，从列表里挑一个指标、选一种聚合方式、挑一个图表类型，系统当场生成聚合查询：

一页里可以同时摆多种图：请求总量趋势（折线）、用户情绪占比（环形）、热门话题 Top N（柱状）。它们都是"指标 + 聚合 + 分组 + 时间粒度"的组合。问题变成：这些要素怎么配。

从指标到图表：50+ 预定义指标如何组合

图表的起点是指标。LangWatch 提供 50 多个预定义指标，大致分四类：

• 流量：Traces、Users、Threads（会话线程），看系统忙不忙
• 性能：总耗时metrics.total_time_ms、首 token 时间metrics.first_token_ms、每秒 tokens，看跑得快不快
• 成本用量：metrics.prompt_tokens、总成本，看一次请求花多少钱
• 评估质量：评估通过率，需指定评估器（evaluator，判定通过与否的质量规则），看哪项质量检查挂了

每条系列（series，图表里的一条数据线）本质是一段短配置。比如"每小时 prompt tokens"这条系列：

{ "metric": "metrics.prompt_tokens", "aggregation": "sum", "format": "0.[0]a", "colorSet": "blueTones" }

剩下三个变量：聚合方式（sum、avg、cardinality（去重计数））、分组维度（用户、话题、模型、Span 类型）、时间粒度（分钟级到 30 天级）。三者和指标一组合，就决定了图表的最终形态：

常用图表类型及适用场景：

背后如何工作：数据经 OpenTelemetry 采集写入后端列式数据库，图表查询按需聚合，重复查询条件走缓存；前端由 Recharts 库渲染，明暗主题都支持。

实战：4 步搭一个客服质量监控仪表盘

问题很典型：客服 agent 上线三个月，运营想一眼看到"今天质量行不行"，而不是翻调用明细。配置思路分四步：

1. 选图表类型：上排摘要卡片（总对话量、正面反馈率、平均响应时间、超时对话占比），下排折线图（满意度趋势、超时占比趋势）
2. 配数据系列：总对话量用metadata.trace_id+ cardinality；满意度用评估通过率 + avg，按 quality_check 评估器过滤；响应时间用metrics.total_time_ms+ avg
3. 设粒度：小时级给值班实时看，天级进周报
4. 加分组：超时占比那条折线按话题分组，直接看出是哪类问题在拖后腿

效果是早上打开仪表盘，4 张 KPI 卡片先告诉你 agent 是否正常；某张卡片变红，下面趋势图回答从什么时候开始劣化，话题分组回答发生在哪类问题上。

如何配置监控图表的告警阈值

普通图表用来"看数"，有些指标还需要"判断"——这是监控图（monitor graph）干的活。配置片段如下：

{ "graphType": "monitor_graph", "series": [{ "metric": "evaluations.evaluation_pass_rate", "aggregation": "avg", "key": "quality_check" }], "monitorGraph": { "isGuardrail": true, "disabled": false } }

图表主体会随取值实时变色，以通过率为例：

• 🟢 绿色：通过率 > 80%，正常
• 🟡 黄色：通过率 40%–80%，警告
• 🔴 红色：通过率 < 40%，异常

把isGuardrail打开，这个指标同时充当护栏（拦截不合格输出上线的关卡），同一份通过率既能做事后监控，也能看在线拦截效果。

报表权限怎么分、报表怎么分发

图建好、阈值设完，最后一步是让团队用起来。先通过 API 把图表配置存成持久资源：

curl -X POST "$API_BASE/api/graphs" \ -H "X-Auth-Token: $API_KEY" \ -d '{"name": "每日性能监控", "graph": {...}}'

访问控制分三档：

分发方式有三种：

• 📎 公开链接：生成只读分享链接，直接丢进 IM
• 📧 邮件订阅：按周期把报表发到指定邮箱
• 🔌 嵌入集成：把图表嵌进内部系统或 wiki，详见官方仪表盘文档

读完后的 3 个可执行动作

1. 挑出团队最关心的 3 个指标（通常是总量、成本、通过率），先搭一个"3 卡片 + 1 折线"的最小仪表盘。
2. 给最核心的评估加一张监控图，把绿/黄/红阈值边界设出来。
3. 用公开链接 + 邮件订阅把仪表盘分发给团队，把"翻日志排查"降级成"先开仪表盘"。

【免费下载链接】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