企业官网建设流程全解析

LangWatch 监控仪表盘实战：从一次延迟排查到可分享的告警报表，6 步配完

【免费下载链接】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 数据变成自定义仪表盘的能力，核心是一条可复现的配置线：选指标、定聚合、拼图表、调粒度、挂阈值、保存分享。下面从一个真实的排查场景切入，走一遍从 0 到 1 的监控仪表盘搭建过程，并给出图表、聚合函数和时间粒度的选型对照，帮你把"看得见数据"变成"看得懂问题"。

一次 RAG 检索延迟翻倍的排查

上周三下午，代码生成服务的用户开始反馈"回答变慢"。值班同学第一反应是看 Trace 列表，但翻了几十条也看不出规律——单条 Trace 的耗时都在正常范围内，慢的感觉来自"最近一小时整体变重了"。

后来把时间范围缩到最近 60 分钟，按 Span 类型拆分完成耗时，才发现慢的只是retrieval这一类 Span——是向量库索引刚做过重建，而不是 LLM 变慢。这个例子说明：出问题时你要的不是"看日志"，而是"一条按正确维度切开的趋势线"。LangWatch 的自定义仪表盘就是干这件事的：指标、聚合、分组、粒度全部可配，排查路径可以直接沉淀成团队共用的视图。

配置主线：从 0 到 1 搭一张图

整条配置线不长，按顺序做就行：

1. 接数据源：SDK 上报的 Trace 天然带metadata（用户、模型、Span 类型等字段），不需要额外建模，这些字段直接就是后续分组的候选维度。
2. 选指标 + 定聚合：每个数据系列 = 一个指标 + 一种聚合方式。比如"完成耗时"配p95，"请求量"用cardinality（即去重计数）。这一步决定图回答什么问题，是整条线里最重要的一步。
3. 拼图表：指定graphType和系列，系列上还能挂colorSet、increaseIs（涨是好事还是坏事，决定涨跌配色）。
4. 设粒度与分组：timeScale控制横轴密度，groupBy控制按什么维度展开成多条线。
5. 挂阈值：把图升级为监控图，越界时自动变色提示。
6. 保存分享：存进仪表盘后，任何人打开链接看到的都是实时最新数据，配置本身就是可版本化的 JSON。

下面这张图就是搭完一个项目级看板后的样子，时间序列、会话指标、情感分布各占一块：

最小可用的图配置长这样，两个系列共用一条横轴，一个看延迟一个看量级：

{ "graphType": "line", "timeScale": 60, "series": [ { "name": "P95 完成耗时", "metric": "performance.completion_time", "aggregation": "p95", "colorSet": "redTones" }, { "name": "请求量", "metric": "metadata.trace_id", "aggregation": "cardinality", "colorSet": "grayTones" } ] }

配置结构在 modules/dashboard/ 里有完整契约定义，想扩展字段时可以直接看 schema。

选型对照：图表、聚合、粒度怎么选

三个决策各有一张速查表，照着挑即可。

图表类型

聚合方式（指标聚合方式怎么选）

时间粒度（时间粒度对结果的影响）

想按"每条请求先算一次再汇总"的口径，就在系列上加一层pipeline，先按 trace 归并再整体平均：

{ "metric": "evaluations.evaluation_pass_rate", "aggregation": "avg", "key": "answer-quality", "pipeline": { "field": "trace_id", "aggregation": "avg" } }

成本类看板可以直接参考内置模板，它把"这个月花多少、哪个模型最贵"做成了现成的卡片加堆叠条组合：

三个高频踩坑点

坑一：聚合口径选错，指标直接失真。对performance.completion_time用sum得到的是总耗时，误读成"平均耗时"会把慢的程度夸大成倍数级。原则是：看典型体验用avg/median，看尾部风险用p95/p99，看总量才用sum。

坑二：guardrail 阈值设太宽，等于没设。guardrail（防护栏）就是给监控图划的红线，越界自动报警。如果你正常通过率在 90% 上下，却把红线划在 40%，它永远不会响。正确做法是先跑一两周，把阈值设在历史波动下沿之内一点。

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

坑三：粒度太粗，尖峰被抹平。用天级粒度回看，一次 10 分钟的检索延迟尖峰会摊进 1440 个点里几乎看不见。排查中的图用分钟级，确认没事之后再切回天级做趋势，别用一套粒度打天下。

评估质量类的现成模板可以对照着看，它把"自动评分是否稳定"做成了双系列线加目标虚线：

上手清单：3 步跑通最小仪表盘

1. 一条线：选performance.completion_time+p95，粒度 60 分钟，保存。此时你已能回答"现在慢不慢"。
2. 切一刀：加groupBy: "metadata.span_type"（或metadata.model），同一张图立刻能回答"慢在哪一段"。
3. 挂个铃：复制该图改为monitor_graph，按两周历史下沿设阈值，存进团队仪表盘，把链接发到频道——此后数据越界，打开链接的人一眼就能看见。

保存后的图表走的是 REST 接口，想脚本化批量生成报表时，字段说明在 docs/api-reference/dashboards/ 里都有。

三步走完，你就有了一个能排查、能值守、能分享的自定义仪表盘；后面每加一张图，都只是重复"指标 + 聚合 + 粒度"这个公式。

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