企业官网建设流程全解析

LangWatch 仪表盘实战：从 Trace 数据到可共享报表的 5 步搭建法

【免费下载链接】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 数据可视化 实战教程：以"AI 应用上线第一周"为场景，带你一步步搭出 AI 应用监控 仪表盘——从选图表类型、配指标，到设阈值告警、保存共享报表，全程可直接复用。

上线第一周，先想清楚要回答哪 3 个问题

AI 应用刚上线时，数据会迅速堆积：海量 Trace、大量用户会话、密集的模型调用。逐条翻 Trace 谁也翻不完，这时候你需要的不是更多数据，而是一个能回答问题的视图。

建议动手前先写下 3 个你要回答的问题：

1. 好不好用——evaluations 通过率、guardrail 检查是否稳定；
2. 快不快——完成时间、首 token 延迟有没有偶发飙高；
3. 贵不贵——token 总量和成本趋势如何。

每个问题对应一到两张图，按问题搭图是最省事的路线，比对着 11 种图表类型逐个"试摆"高效得多。

LangWatch 的 Analytics 页面把 Messages、Threads、Users 等核心指标组织成折线图与汇总卡片，Top Topics 和情绪占比环形图也一并呈现。

全文按 5 步主线展开：选图表类型 → 选指标与聚合 → 配分组与时间粒度 → 配监控阈值 → 保存共享。

选图表类型：11 种内置类型的 3 个判断标准

LangWatch 内置 11 种图表类型：line、area、stacked_area、bar、stacked_bar、horizontal_bar、scatter、pie、donnut、summary、monitor_graph（API 字段名以官方文档为准）。数量不可怕，怕的是不知道选哪个。经验上，问自己 3 个问题就够。

看时间趋势怎么选

问题是"XX 随时间怎么变"，选line或area：line 强调趋势本身，area 强调总量累积。响应时间、成本曲线基本是 line 的天下；想看各成分随时间的变化（比如各模型 token 量的占比走势），用stacked_area。

看构成与排名怎么选

问题是"占多少比例"或"谁排第几"，用pie/donnut看构成，用bar做分类对比；标签很长时（模型名、用户 ID），horizontal_bar比竖排 bar 好读得多。要一次对比两个维度，上stacked_bar。怀疑两个指标之间存在关系（如 token 量 vs 完成时间），用scatter。

看单个数字或告警怎么选

只需要一个数，比如"本周总成本 $450"，用summary；这个数字还要被盯住、需要按数值变状态，用monitor_graph，后面单独展开。

选指标与聚合：最容易踩坑的一步

内置指标分四大类

series 里的 metric 字段形如类别.字段。LangWatch 提供一批预定义指标，按用途分四类（具体字段清单以官方文档为准）：

• 流量与用户：metadata.trace_id（cardinality 去重计数即总请求量）、metadata.user_id（独立用户数）、metadata.thread_id（会话数）；
• 性能：performance.completion_time（完成时间）、performance.first_token（首 token 时间）、performance.tokens_per_second（生成速度）；
• 成本与用量：performance.prompt_tokens、performance.completion_tokens、performance.total_tokens（总量）、performance.total_cost（总成本）；
• 评估与质量：evaluations.evaluation_pass_rate（通过率）、evaluations.evaluation_score（分数），以及sentiment.thumbs_up_down这类用户反馈指标。

注意这里容易踩坑：有些指标需要同时指定 key 才有意义——比如看通过率时要指定看哪个 evaluator，配置 key 的名称以官方文档为准。

指标和聚合方式的匹配陷阱

聚合方式常见 cardinality、sum、avg，还有 min/max 以及 p95、p99 等分位数。对应关系有坑：

• ID 类字段只能用 cardinality——"今天多少请求"本质是 trace_id 去重计数，不能对它求 sum；
• 成本与 token 量一般用 sum——你要的是总量，avg 出来的"平均成本"业务意义不大；
• 延迟看 avg 够，但要盯尾部——怀疑偶发飙高时把聚合换成 p95/p99，真实的长尾才看得见。

一张图可以混排多个 series，比如做一张多模型 A/B 对比图：

{ "graphType": "line", "timeScale": 360, "groupBy": "metadata.model", "series": [ { "name": "总请求量", "metric": "metadata.trace_id", "aggregation": "cardinality", "colorSet": "orangeTones" }, { "name": "平均完成时间", "metric": "performance.completion_time", "aggregation": "avg", "colorSet": "greenTones" } ] }

colorSet控制系列配色（blueTones、greenTones、tealTones 等均可选）。建议同一张图内的 series 用同一色系的不同色调，避免满屏彩虹。

分组与时间粒度：一张折线图看多维度

常用分组维度

给配置加一行groupBy，"公司大盘"的折线图就变成按维度拆开的多条并行线。最常用的 4 个维度：

1. 按用户（metadata.user_id）：识别谁的量大、谁的体验差；
2. 按主题：看话题分布，哪些咨询集中爆发；
3. 按模型（metadata.model）：多模型性能与成本对比，A/B 看板的核心；
4. 按 Span 类型：定位 pipeline 里哪一步是瓶颈。

坑在分组基数：维度值太多（比如用户 ID 有几千个）时，折线会糊成一团。建议先用 filters 过滤出 Top N，或干脆换成 horizontal_bar 排名。

时间粒度怎么选

timeScale控制横轴聚合粒度：填数字表示粒度（如 60 表示 1 小时桶），也可以设full整段聚合——summary 图会自动按全周期聚合。经验值供参考：

• 实时监控：10 分钟粒度，尖峰看得清；
• 日常分析：1 小时粒度，曲线稳定可读；
• 趋势与成本统计：1 天粒度；
• 长期回顾：7 天或 30 天。

粒度越细曲线越"毛刺"，噪声越多；拿不准就先按 1 小时出图，再往粗或往细调。

监控图表：阈值怎么设才不会被误报淹没

普通图是"给人看的"，monitor_graph是"给机器盯的"。上线后不可能全天盯屏，要把最关键的数字交给监控图，例如盯质量检查通过率：

{ "graphType": "monitor_graph", "series": [ { "name": "质量检查通过率", "metric": "evaluations.evaluation_pass_rate", "aggregation": "avg" } ], "monitorGraph": { "isGuardrail": true, "disabled": false } }

isGuardrail: true表示这张图按 guardrail（防护栏）检查来监控；disabled控制是否启用。图表会根据数据值自动变色，以通过率为例的参考档位是：

• 绿色：通过率 > 80%，正常；
• 黄色：40%–80%，需要关注；
• 红色：< 40%，异常，需要处理。

注意这里最容易踩的坑：别一开始就把阈值定得过于激进。建议先按默认档位跑一两周，观察历史数据的自然波动区间，再收紧或放宽。天天报红的监控，大家很快就会视而不见，仪表盘等于白搭。

这类延迟监控图会同时展示当前值与周期基线（虚线），尖峰是否越过基线一眼可判，适合作为值班同学的第一屏。

保存与共享：把仪表盘变成团队资产

用 REST API 保存图表

图调到自己满意后，可以把它存为报表。除了界面操作，还可以用 REST API 写入，实现"仪表盘即代码"：

curl -X POST "https://YOUR_DEPLOY_DOMAIN/api/v1/graphs" \ -H "X-Auth-Token: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "多模型对比日报", "graph": { "graphType": "bar", "series": [/* 同上 JSON */] }, "filters": {} }'

新接入一个项目时自动批量生成一套仪表盘，走的就是这条路。请求体字段以官方文档为准。

权限级别与共享方式

报表存好后，用三级权限管理：

共享方式有三种：生成只读公开链接（给无账号的人看）、邮件订阅（定期推送报表）、嵌入集成到自有系统。建议上线后第一件事就是把日报配成邮件订阅——成本最低，但能逼着团队每天真的看数据。

数据链路：图表上的数是怎么来的

排障"数据为什么延迟"时，理解这条链路很有用：

1. 数据收集：OpenTelemetry Collector 接收各 SDK 上报的 Trace 数据；
2. 近实时存储：存储层使用 ClickHouse，数据入库即可被查询；
3. 按需聚合：打开仪表盘时，才按 series 配置做 cardinality/sum/avg 等聚合，不是全量预计算；
4. 结果缓存：重复查询直接命中缓存，同一仪表盘反复打开会越来越快。

所以"仪表盘比 Trace 详情页慢一点"通常只是聚合口径与数据量的问题，而不是数据丢了；如果长时间缺数据，优先检查第 1 步的采集链路。

下一步可以做什么

1. 写下你当前项目的 3 个问题（好不好用 / 快不快 / 贵不贵），每个问题先定一个图表类型，再定指标；
2. 照抄文中的多模型对比配置，先把 token 总量 + 平均完成时间的 bar 对比图跑出来；
3. 给通过率配置monitor_graph并开启 guardrail 模式，按默认档位跑 1–2 周后再校准阈值；
4. 用 REST API 保存第一个仪表盘，给干系人发只读链接，并配好日报邮件订阅。

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