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

客服 Agent 上线两周，团队每天早晨的第一件事，是查看前一晚的调用量、平均延迟和评估通过率，可这些数据散落在不同系统里，拼出全貌要花半小时。LangWatch 的自定义仪表盘把已经采集的 trace 数据汇到一起，让你用三步拼出 AI 应用监控所需的数据可视化视图。这篇教程就按这三步走。

第一步：为 LangWatch 仪表盘搭建自定义图表

这一步要解决的问题很直接：让散落的 trace 数据变成一张能看的图。整个配置过程就是连续做四个决定：画成什么类型、用哪个指标、按多细的时间切分、按什么维度拆开。

图表类型速选

LangWatch 内置 11 种图表类型：折线、面积、堆叠面积、柱状、堆叠柱状、水平柱状、散点、饼图、环形图，以及两种特殊形态——摘要卡（一个大数字加环比变化，适合当 KPI 用）和监控图（第二步的主角）。选型的经验法则如下表：

指标与聚合

指标选择器里有 50 余种预定义指标，覆盖流量、性能、成本、质量四类。常用的比如：调用总量（对 trace_id 做 cardinality 去重计数）、独立用户数、会话数（threads）；性能侧是总耗时metrics.total_time_ms和首 token 时间metrics.first_token_ms；成本侧是各类 token 用量与metrics.total_cost；质量侧是评估通过率evaluations.evaluation_pass_rate，它需要先指定某个 evaluator 作为过滤键才有效果。

聚合方式只有三种，但覆盖了绝大多数场景：sum求总量，avg求平均，cardinality做去重计数——统计「有多少个不同用户」就必须用它。一张图里可以同时放多个数据系列，每个系列独立配置名称、指标、聚合和配色，例如把总调用量与按错误类型拆出的调用量叠在同一张折线图上。

粒度与分组

时间粒度决定横轴上一个点代表多久，本质是精度与可读性的权衡：值班盯盘选 10 分钟，日常复盘选 1 小时，看周级趋势选 1 天，月度回顾放宽到 7 天甚至 30 天。

分组是挖掘差异的关键：按用户拆，能找出重度用户；按主题（topic）拆，看哪类内容最热门；按模型拆，对比不同模型的耗时和成本；按 Span 类型拆，则能看清 pipeline 里每一段的开销结构。分组维度和时间粒度可以自由组合，同一张图先整体、后按模型拆开，往往是排查「平均值正常但某模型异常」的常用手法。

第二步：把仪表盘变成 AI 应用监控视图

回顾用的图是静态的，生产环境需要的是一眼能判断状态的视图。监控图（monitor_graph）把同一套聚合逻辑渲染成大号数字，并根据数值自动换色：

• 🟢 绿色：评估通过率高于 80%，视为正常
• 🟡 黄色：处于 40% 到 80% 之间，需要关注
• 🔴 红色：低于 40%，按异常处理

在配置里打开isGuardrail后，这张图还能兼任防护栏（guardrail）监控：Agent 的每次输出先过评估器打分，监控图聚合通过率，一旦转红就说明防护栏正在大量失效，而不是某次偶发失败。值班时扫一眼颜色就够了。

同一个视图里还可以塞入对比小图。比如想回答「哪个模型又快又便宜」，用水平柱状图按metadata.model分组，把平均响应时间和平均成本并排放：

// 多模型对比：平均响应时间与平均成本并列 { graphType: "bar", groupBy: "metadata.model", series: [ { metric: "metrics.total_time_ms", aggregation: "avg", name: "平均响应时间" }, { metric: "metrics.total_cost", aggregation: "avg", name: "平均成本" } ] }

第三步：保存报表并通过 API 与链接共享

视图搭好后，还有两件事：别让它丢失，别让它只你一个人看。

用 API 保存适合脚本化场景。向POST /api/graphs提交图表名称、graph 配置与 filters，鉴权通过X-Auth-Token头携带 API key；接口细节见仓库内的 Create a custom graph API 文档：

curl -X POST "https://app.langwatch.ai/api/graphs" \ -H "X-Auth-Token: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "每日性能监控", "graph": { ... }, "filters": { ... } }'

共享有三条通道：生成公开只读链接，发给不需要账号的外部干系人；配置邮件订阅，让报表按固定周期送到团队邮箱；把图表嵌入到你自己的系统或内部门户里。

权限分三级：查看者只读，适合业务人员；编辑者可以修改配置，适合分析师；管理员拥有完全控制权，适合团队负责人。想弄清看板、图表与已保存视图背后的数据模型，可以翻 dashboard 模块源码，或先看 Dashboards 官方功能文档。

背后简述：数据从采集到渲染的路径

整条链路分三段。采集端由 OpenTelemetry Collector 接收各 SDK 上报的 trace 数据；存储查询端把这些数据近实时地写入 Elasticsearch，打开仪表盘时按你配置的粒度与分组做按需聚合，重复查询走结果缓存；渲染端则交给前端的 Recharts 库完成，图表支持明暗主题与不同屏幕尺寸的自适应。你配置的每一项，最终都会翻译成一串聚合查询。

从一张折线图到一张会随阈值变色的监控图，再到能被团队打开的报表，三步走完就是一个闭环。建议从最小集合起步：先放调用量、平均延迟、评估通过率三张摘要卡跑起来，再逐步叠加分组维度和监控图，视图会自然长成团队每天愿意打开的样子。

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