企业官网建设流程全解析

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 里的请求量、耗时、Token 用量和评估结果，变成可保存、可共享的监控视图。跟着本文走一遍，你能用 Trace 数据从零搭出一块 AI 应用监控看板，并让它对异常自动报警。

一、为什么需要一块统一的监控视图

AI 应用上线后，数据是分散的：请求量在日志里，延迟在 Trace 里，Token 成本要按模型算，评估分数在另一套流程里。传统监控工具能画 CPU 和 QPS，却回答不了"哪个模型的响应变慢了""上周评估通过率掉了多少"这类问题。开发者通常只能打开多个页面、手动翻 Trace 拼答案，既慢又容易漏掉趋势。

假设你要为线上 AI 客服搭一块质量看板：老板想看对话量和满意度，值班工程师想在响应超时或评估掉分时第一时间收到通知。下面就是围绕这个任务，把看板一步步搭出来的过程。

二、从 Trace 到图表：搭出第一块仪表盘

LangWatch 的图表构建链路是：数据源 → 指标 → 聚合方式 → 图表类型 → 分组维度 → 时间粒度。所有图表的原始数据都来自 Trace（每次 LLM 调用的完整记录，包含输入输出、耗时、Token 数、元数据等），你只需要告诉系统"看哪个字段、怎么算、怎么画"。

• 选指标：在图表构建器里，每条数据系列（series）对应一个指标。比如选metadata.trace_id，代表请求量；选performance.completion_time，代表总耗时。
• 定聚合：同一个指标可以有不同算法。数请求用cardinality（去重计数），看耗时用avg或p95、p99（百分位数，即 95%、99% 的请求都在这个时间内完成），看成本用sum。
• 挑图表类型：趋势用折线图，累计量用面积图，分类对比用柱状图，占比用饼图或环形图，单值 KPI 用摘要卡片（summary），需要盯盘告警时用监控图表（monitor_graph）。
• 设粒度与分组：timeScale控制时间桶，比如 30 分钟、1 天，也可以设为full把整个区间压成一个值；groupBy决定横轴按什么切分，比如按metadata.model（模型名）或topics.topics（话题）拆开看。

一个图表可以放多条数据系列。常见手法是在同一条系列上叠filters：总量曲线不加过滤，"错误请求"曲线只保留有报错的 Trace，"流式请求"曲线只留metadata.labels含streaming的——三条线叠在一张图上，结构一目了然。

三、指标怎么选：流量、性能、成本、质量

构建器内置的指标集中在四类，命名上就能看出归属。下面是选型时的业务含义，帮你快速判断"该看哪条线"。

选指标时有一条经验：KPI 卡片放绝对值（如总成本sum），趋势线放相对值（如通过率avg、asPercent转成百分比），这样看板既好看家也看趋势。评估类指标通常需要key参数指定具体评估器，只统计某个质量检查项的结果。

四、让图表会报警：monitor_graph 与阈值变色

普通图表只是"能看见"，monitor_graph类型则面向值守场景。它把一条系列画成一块状态卡片，根据当前值自动变色：

{ "graphType": "monitor_graph", "series": [{ "name": "评估通过率", "metric": "evaluations.evaluation_pass_rate", "aggregation": "avg", "key": "quality_check", "colorSet": "greenTones" }], "monitorGraph": { "isGuardrail": true, "disabled": false } }

这段配置把"quality_check 评估器的平均通过率"挂成一块防护栏（guardrail）卡片：值在安全区间显示绿色，进入警戒区间转黄色，跌破底线变红，isGuardrail: true表示它承担门禁职责，disabled: false表示启用。

在图表上还能直接配 alert：设定比较符（如<）、阈值、时间窗口，触发后通过邮件或 Slack 通知值班同学。对客服这类业务，把"满意度"或"错误率"的 alert 阈值调严一点，就能实现"用户还没投诉，工程师先收到通知"。

五、让报表成为团队资产

搭好的图表不是临时的。LangWatch 支持把图表存为命名报表，再挂到仪表盘上；仪表盘本身由Dashboard与CustomGraph记录持久化，团队里每个人打开看到同一份配置。仓库里可以看到仪表盘模块围绕权限做了完整划分：读取、创建、更新、重排序是不同操作，分别受项目级角色约束——查看者只能看图，编辑者可以调配置，管理员可以增删和重排布局。

分享上有几条现成路径：给有权限的同事直接发平台内链接；把仪表盘嵌进内部系统（仓库中 observability 文档列出了 Embedded Analytics 这一能力）；也可以只把关键图表作为嵌入组件放到其他页面。再配合报表的周期订阅，每天早上把关键指标推到邮箱，值班同学就不用守着屏幕。

六、几种常用组合

• 客服质量看板：摘要卡片放"总会话数、平均会话时长、点赞率"三个 KPI，配一条按天粒度的metadata.thread_id趋势线；再加一张sentiment.thumbs_up_down按标签分组的饼图，看正面/负面反馈占比。满意度这条线同时挂 monitor_graph 和 alert，掉分即告警。
• 多模型性能对比：groupBy选metadata.model，两条系列分别是performance.total_time_ms的p95和performance.total_cost的sum，用堆叠柱状图一眼看出哪个模型慢、哪个贵，换模型前心里有数。
• 成本与缓存效率：三条系列分别是 prompt、completion 和缓存读取 Token 的sum，用堆叠面积图按天铺开。缓存命中上来了，绿色区域就会变厚，省了多少钱不用算。

这些组合的共同点：先决定"回答什么问题"，再反推指标和分组，而不是先选图表往里填数。

收个尾

从 Trace 到一块带报警的共享看板，全程不需要写查询——指标、聚合、分组、粒度都是选择项，配置本身就是文档。这套能力的底层由 ClickHouse 承载：Trace 与评估数据近实时入库，查询时对聚合表做按需计算，前端按需拉取渲染，所以看板刷新接近实时。后续方向上，报表的跨周期对比、更多可嵌入的外部数据源，以及让评估类指标自动派生新口径，都是值得关注的演进点。想动手试的话，可以从 观测与追踪概览文档 入手，先把 Trace 接进来，再回来搭第一块看板。

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