🪢 Langfuse 图解教程Langfuse Visual Guide 第八部分 · 仪表盘·指标·成本Part 8 · Dashboards, Metrics & Cost 40 / 55
第八部分 · 仪表盘·指标·成本Part 8 · Dashboards, Metrics & Cost

仪表盘与 widget 系统Dashboards & widgets

🧭 读前Before you start
先读 第8课 的宽事件表,本课讲仪表盘与 widget 如何聚合展示。
Read Lesson 8 on the wide-event tables; this lesson covers how dashboards and widgets aggregate and display.

前七部分让你能看清单条——一条 trace、一个 score、一次实验。但运营一个 LLM 应用,你更常问的是全局的问题:这周成本涨了没?哪个模型最慢?平均有用性的走势如何?错误率有没有抬头?这些答案藏在成千上万条数据的聚合里——把它们汇成一张张图,就是仪表盘(dashboard)和它的积木 widget(图件)。 这一课讲它们的数据模型,重点是一个会反复回响的设计:一个 widget 把「要算什么」声明成 view + dimensions + metrics + filters 这样一套查询形状——而这套形状,正是第 33 课监控器复用的、也是下一课查询引擎要编译成 SQL 的。画一张图、盯一个指标、跑一个聚合,背后是同一种声明。

📋 生活类比
仪表盘就像汽车驾驶舱的那块仪表板:一块板上摆着一排表(widget)——油量表、转速表、时速表、水温灯。每块表只管一件事:读哪个量、画成什么样(指针?数字?柱状?),它不关心这个数到底是怎么从引擎、油箱里采集上来的。 你能自由地往板上增删、挪动这些表,拼出最适合你的那套布局。而真正决定「这块表测什么、按什么分组」的,是一张声明(「测:平均时速;按:每分钟分组」),而不是焊死在表里的电路。于是同一份「测什么」的声明,既能驱动这块指针表,也能驱动旁边那盏「超速就亮」的警示灯(第 33 课监控)——测量与展示,是分开的两件事。

仪表盘 = 一块布局 + 一排 widget

数据模型分两层。Dashboard 是「一块板」:有名字、描述,一个 definition(JSON 布局,决定哪些 widget、各摆哪、多大),外加一组板级 filters(套在所有 widget 上的全局过滤,比如「只看 production 环境」)。DashboardWidget 才是「一块表」:每个 widget 是一份保存好的查询 + 图表。一个 dashboard 装一排 widget,拼成你要的全景。

一块 Dashboard 板,摆一排 widget,全局 filter 套全板 Dashboard:definition(布局)+ 全局 filters(套在所有 widget 上,如「env=production」) widget · 成本走势折线时序 widget · 各模型调用量柱状 widget · 总成本$1,284 widget · 平均有用性折线时序 widget · score 分布饼图 widget · 延迟直方直方图
两层结构:schema.prisma:1494 Dashboard 有 definition(布局 JSON)与板级 filters;:1536 DashboardWidget 是单块「查询+图表」。一个板上的多个 widget 各看一个角度,板级 filter 同时收敛全部——「先全局圈定范围,再各看各的指标」。
示例:一个仪表盘(4 个 widget) 📅 last 30 days env = production model = * + 添加 widget traces / day LINE_TIME_SERIES Jun 1Jun 30 各模型成本 (USD) VERTICAL_BAR gpt-4o$126 4o-mini$43 claude$94 llama$25 p95 延迟 NUMBER 1.8 s ▼ 12% 对比上周 高频用户 PIVOT_TABLE userId traces cost u_8f3a1820$58 u_2b711340$41 u_55c9980$33 每个 widget = 查询引擎上的一条保存查询(view + metrics + dimensions),第 41 课细讲
一个仪表盘 = 一组 widget,每个 widget = 一条保存的查询(widget 类型取自 DashboardService 的 chartType;数据为示例):顶部筛选条作用于全盘,下面四块分别是 LINE_TIME_SERIES(每日 trace)、VERTICAL_BAR(各模型成本)、NUMBER(p95 延迟大数字)、PIVOT_TABLE(高频用户)。同一份指标,选不同图型就有不同读法——趋势看折线、构成看柱状、单点 KPI 看大数字、明细看透视表。这些 widget 背后都是第 41 课的查询引擎。
板Dashboard
一块画布:definition 是 JSON 布局(哪些 widget、各占什么格子),filters 是板级全局过滤。projectId 可空——Langfuse 还内置了一批「托管仪表盘」开箱即用。你能像摆桌面小组件一样自由编排。
表DashboardWidget
一块表 = 一份声明式查询(view 看什么数据 + dimensions 按什么分组 + metrics 算什么 + filters)加一种图表呈现(chartType + chartConfig)。查询定义「算什么」,图表定义「怎么画」——下一节细看。
复用同一份指标,多处消费
widget 的查询形状不是仪表盘私有的:第 33 课的监控器直接复用它(注释原文「mirrors DashboardWidget」),下一课的查询引擎负责把它编译成 ClickHouse SQL。一份「算什么」,画图、告警、聚合三处共享。

widget = 声明式查询 + 图表呈现

拆开一个 widget,它清清楚楚分成两半:查询(要算什么)和图表(怎么画)。查询那半是四件套:view(数据源:TRACES / OBSERVATIONS / SCORES_NUMERIC / SCORES_CATEGORICAL)、dimensions(分组轴,如「按模型」「按天」)、metrics(聚合量,如「计数」「成本求和」「分数求平均」)、filters(过滤)。图表那半是 chartType(折线/柱状/饼/大数字/直方/透视表…)+ chartConfig。

一个 widget:左半「算什么」+ 右半「怎么画」 查询(声明:算什么)view: OBSERVATIONS(看观测)dimensions: [model](按模型分组)metrics: [sum(totalCost)](成本求和)filters: [env=production] 图表(呈现:怎么画)chartType: BAR / LINE / PIE / NUMBER …同一查询可换图表 查询与图表解耦:换一种 chartType 不动查询,换一个 metric 不动画法——各自独立演化
声明式查询 + 呈现,干净分家:schema.prisma:1536 DashboardWidget 把 view/dimensions/metrics/filters(算什么)与 chartType/chartConfig(怎么画)分别建模。view 取自 DashboardWidgetViews(4 值),chartType 取自 DashboardWidgetChartType(9 种图)。
四件套(查询)含义例子
view数据源TRACES / OBSERVATIONS / SCORES_NUMERIC / SCORES_CATEGORICAL
dimensions分组轴(GROUP BY)按 model、按 day、按 name……
metrics聚合量count、sum(totalCost)、avg(value)、p95(latency)
filters过滤条件env=production、name=chat、时间窗
packages/shared/prisma/schema.prisma:1516-1560widget 模型 + 两个枚举
enum DashboardWidgetViews { TRACES  OBSERVATIONS  SCORES_NUMERIC  SCORES_CATEGORICAL }
enum DashboardWidgetChartType { LINE_TIME_SERIES  BAR_TIME_SERIES  HORIZONTAL_BAR
  VERTICAL_BAR  PIE  NUMBER  HISTOGRAM  PIVOT_TABLE  … }   // 9 种图表
model DashboardWidget {
  view       DashboardWidgetViews   // 看什么数据
  dimensions Json   // 按什么分组(GROUP BY 轴)
  metrics    Json   // 算什么(聚合)
  filters    Json   // 过滤
  chartType   DashboardWidgetChartType   // 怎么画
  chartConfig Json                       // 图表细节
}
图表类型(节选)适合表达典型用途
LINE / AREA / BAR_TIME_SERIES随时间的趋势成本走势、每日调用量、分数变化
HORIZONTAL / VERTICAL_BAR类别间对比各模型调用量、各用户花费排名
NUMBER单个关键值本月总成本、总 trace 数(KPI 大数字)
PIE整体的构成各模型成本占比、score 分类分布
HISTOGRAM数值的分布延迟分布、token 数分布
PIVOT_TABLE多维交叉模型 × 环境 的成本矩阵

同一份查询,选不同 chartType 就是不同的看法:想看趋势用时序、想比大小用柱状、想看构成用饼、想看分布用直方。数据不变,视角随需而换——这正是查询/呈现分离给探索带来的自由。

一份查询形状,三处复用

widget 这套 view + dimensions + metrics + filters 的声明,最妙的不是它能画图,而是它不只用来画图。同一套声明被三个地方共享:仪表盘拿它画成图表、第 33 课的监控器拿它定时算并比阈值、下一课的查询引擎拿它编译成 ClickHouse SQL。一个例证就藏在枚举里:监控器的 MonitorView 恰好是 DashboardWidgetViews 去掉 TRACES(源码注释原文「mirrors DashboardWidget, minus TRACES」)。

同一份「算什么」声明,喂给三个消费者 查询形状(声明)view + dimensions + metrics + filters 仪表盘(本课)画成图表(pull:你来看) 监控器(第33课)定时比阈值(push:它来喊) 查询引擎(第41课)编译成 ClickHouse SQL MonitorView = DashboardWidgetViews 去掉 TRACES(源码注释 mirrors DashboardWidget, minus TRACES)
声明一次,处处复用:能在仪表盘上画出的任何曲线,都能一键变成一个监控告警(第 33 课),也都由同一个查询引擎(第 41 课)落成 SQL。pull(仪表盘你来看)与 push(监控它来喊)共享同一个指标定义——这正是第 33 课能「复用 DashboardWidget」的根因。
🎯 设计取舍
为什么 widget 要把「算什么」和「怎么画」分开声明,而不是直接写死一段「画某张图」的代码? 因为这是两个正交的维度,强行耦合只会两头受限。把它们分开,你立刻得到三重自由:同一份查询换个 chartType 就从折线变柱状(探索数据时极有用);同一种图表换个 metric 就从看成本变看延迟;更关键的是,那份纯粹的「算什么」声明,因为不掺任何展示逻辑,才能被监控器、查询引擎原样借走。声明式的威力,正在于它描述「意图」而非「步骤」——意图可以被任意多个执行者以不同方式实现。这和第 23 课 FilterState、第 21 课 tRPC 契约是同一种信念:把「想要什么」从「怎么做到」里剥离,复用与演进的空间就此打开。

为什么这套查询形状值得被三处共用,而不是各写各的? 因为「指标」这个概念在产品里本就该统一。如果仪表盘上的「平均有用性」和监控器里的「平均有用性」是两段独立实现,它们迟早会算出不同的数——口径漂移是数据产品的慢性毒药。让三处共享同一份声明、同一个查询引擎,等于钉死了「这个指标全公司只有一种算法」。你在图上看到的、和告警依据的、和 API 取到的,永远是同一个数。一致性不是靠纪律维持,而是靠架构从根上保证。
🎯 本课要点
  • 仪表盘看全局:把成千上万条数据聚合成图,回答「成本涨没」「哪个模型慢」「分数走势」这类全局问题——补上前七部分「看单条」之外的「看整体」。
  • 两层模型:Dashboard(definition 布局 + 板级 filters)装一排 DashboardWidget;每个 widget 是一份保存好的「查询 + 图表」。
  • widget = 声明式查询 + 图表:查询四件套 view(数据源)+ dimensions(分组)+ metrics(聚合)+ filters;呈现是 chartType(9 种图)+ chartConfig。算什么与怎么画,干净分家。
  • 查询/呈现解耦:换图不动查询、换指标不动画法;纯粹的「算什么」声明才能被原样复用——声明式描述意图而非步骤。
  • 一份查询形状三处复用:仪表盘画图、第 33 课监控比阈值、第 41 课引擎编译 SQL,共享同一声明(MonitorView = DashboardWidgetViews 去掉 TRACES)。指标全公司一种算法,pull 与 push 永远同一个数。

🧪 自测 · 想一想为什么这么设计

1. Langfuse 的 DashboardWidget 把 view+dimensions+metrics+filters(查询)和 chartType+chartConfig(图表)分开建模。这种「查询/呈现分离」最大的好处是?
  1. 让图表渲染更快
  2. 自动选择最优图表
  3. 查询与图表正交、各自自由演化:同查询换 chartType 即换图、同图换 metric 即换量;更关键的是纯粹的「算什么」声明不掺展示逻辑,才能被监控器/查询引擎原样复用
  4. 减少数据库表数量
看答案与解析 点击展开
答案:C。查询(算什么)与图表(怎么画)是两个正交维度,强耦合两头受限。分开后:同查询换 chartType 从折线变柱状、同图换 metric 从看成本变看延迟;更关键的是那份纯粹「算什么」声明不掺展示逻辑,才能被第33课监控器、第41课查询引擎原样借走。声明式描述意图而非步骤——和第23课 FilterState、第21课 tRPC 契约同一种信念。
2. 第 33 课的监控器源码注释说它「mirrors DashboardWidget, minus TRACES」,且 MonitorView 恰好是 DashboardWidgetViews 去掉 TRACES。这个复用透露了什么设计意图?
  1. 为了节省存储
  2. TRACES 数据不能被监控
  3. 监控器是仪表盘的子集功能
  4. 「指标」全公司只有一种算法:仪表盘画图、监控比阈值、查询引擎编 SQL 共享同一份查询形状,于是图上看到的、告警依据的、API 取到的永远是同一个数——一致性靠架构从根上保证而非靠纪律
看答案与解析 点击展开
答案:D。若仪表盘的「平均有用性」和监控器的「平均有用性」各写一套实现,迟早算出不同的数——口径漂移是数据产品的慢性毒药。让三处共享同一份 view+dimensions+metrics+filters 声明、同一个查询引擎,等于钉死「这个指标全公司只有一种算法」。pull(看图)与 push(告警)永远同一个数。一致性靠架构保证,不靠纪律维持。
3. DashboardWidget 的 view 字段取自 DashboardWidgetViews 枚举。它有哪四个值?
  1. SUM、AVG、COUNT、MAX
  2. LINE、BAR、PIE、NUMBER
  3. DAY、WEEK、MONTH、YEAR
  4. TRACES、OBSERVATIONS、SCORES_NUMERIC、SCORES_CATEGORICAL——即一个 widget 能聚合 trace、观测、数值分或分类分这四种数据源之一
看答案与解析 点击展开
答案:D。DashboardWidgetViews = { TRACES, OBSERVATIONS, SCORES_NUMERIC, SCORES_CATEGORICAL },决定 widget 聚合哪种数据源。LINE/BAR/PIE/NUMBER 那些是另一个枚举 DashboardWidgetChartType(怎么画,9 种)。view 管「看什么数据」、chartType 管「画成什么图」——正是查询与呈现分离的体现。监控器的 MonitorView 则是这个去掉 TRACES。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 「一份查询形状,三处复用」是 Langfuse 保证指标口径一致的核心招式。回想你做过或用过的数据产品:是否遇到过「同一个指标在不同页面/报表/告警里算出不同数」的口径漂移?如果让你设计一套机制根治它,你会怎么做?声明式查询 + 统一引擎的代价(灵活性受限、引擎要支持所有需求)你怎么权衡?

The first seven parts let you see one thing clearly—one trace, one score, one experiment. But operating an LLM app, you more often ask global questions: did cost rise this week? which model is slowest? how is average helpfulness trending? is the error rate creeping up? These answers hide in the aggregation of thousands of records—rolling them into charts is the dashboard and its building block, the widget. This lesson covers their data model, focusing on a design that will echo repeatedly: a widget declares "what to compute" as a view + dimensions + metrics + filters query shape—and this shape is the very one Lesson 33's monitor reuses, and the one the next lesson's query engine compiles to SQL. Drawing a chart, watching a metric, running an aggregation—behind them is the same declaration.

📋 Analogy
A dashboard is like a car's cockpit instrument panel: a board with a row of gauges (widgets)—fuel gauge, tachometer, speedometer, temperature light. Each gauge cares about one thing: which quantity to read, and how to draw it (needle? number? bar?); it doesn't care how that number was actually gathered from the engine or tank. You can freely add, remove, rearrange these gauges into the layout that suits you. And what truly decides "what this gauge measures, grouped by what" is a declaration ("measure: average speed; group by: per minute"), not circuitry welded into the gauge. So the same "what to measure" declaration can drive both this needle gauge and the "blinks when over-speeding" warning light next to it (Lesson 33's monitor)—measurement and display are two separate things.

A dashboard = a layout + a row of widgets

The data model has two layers. Dashboard is "the board": a name, a description, a definition (JSON layout deciding which widgets go where and how big), plus a set of board-level filters (global filters applied to all widgets, e.g. "only production"). DashboardWidget is "a gauge": each widget is a saved query + chart. A dashboard holds a row of widgets, composing the panorama you want.

one Dashboard board, a row of widgets, global filter over the whole board Dashboard: definition (layout) + global filters (on all widgets, e.g. "env=production") widget · cost trendline time-series widget · calls per modelbar widget · total cost$1,284 widget · avg helpfulnessline time-series widget · score distributionpie widget · latency histogramhistogram
Two-layer structure: schema.prisma:1494 Dashboard has a definition (layout JSON) and board-level filters; :1536 DashboardWidget is one "query+chart". Multiple widgets on a board each show one angle, the board filter converging all at once—"globally scope first, then each shows its own metric".
Example: one dashboard (4 widgets) 📅 last 30 days env = production model = * + add widget traces / day LINE_TIME_SERIES Jun 1Jun 30 cost by model (USD) VERTICAL_BAR gpt-4o$126 4o-mini$43 claude$94 llama$25 p95 latency NUMBER 1.8 s ▼ 12% vs last wk top users PIVOT_TABLE userId traces cost u_8f3a1820$58 u_2b711340$41 u_55c9980$33 each widget = one saved query on the engine (view + metrics + dimensions), detailed in Lesson 41
A dashboard = a set of widgets, each widget = one saved query (widget types from DashboardService's chartType; data illustrative): the filter bar on top applies to the whole board, and the four panels are LINE_TIME_SERIES (traces/day), VERTICAL_BAR (cost by model), NUMBER (p95 latency big-stat) and PIVOT_TABLE (top users). Same metrics, different chart types read differently — a line for trend, bars for composition, a big number for a single KPI, a pivot for detail. Every widget is backed by Lesson 41's query engine.
boardDashboard
A canvas: definition is a JSON layout (which widgets, what grid cells), filters are board-level global filters. projectId is optional—Langfuse ships a set of "managed dashboards" ready out of the box. You arrange it freely like desktop widgets.
gaugeDashboardWidget
A gauge = a declarative query (view what data + dimensions group by what + metrics compute what + filters) plus a chart presentation (chartType + chartConfig). The query defines "what to compute", the chart defines "how to draw"—detailed next.
reuseone metric, many consumers
The widget's query shape isn't dashboard-private: Lesson 33's monitor directly reuses it (the source comment "mirrors DashboardWidget"), and the next lesson's query engine compiles it to ClickHouse SQL. One "what to compute" is shared by charting, alerting, and aggregation.

A widget = a declarative query + a chart presentation

Unpack a widget and it clearly splits in two: the query (what to compute) and the chart (how to draw). The query half is a quartet: view (data source: TRACES / OBSERVATIONS / SCORES_NUMERIC / SCORES_CATEGORICAL), dimensions (group-by axes, e.g. "by model", "by day"), metrics (aggregations, e.g. "count", "sum cost", "average score"), filters. The chart half is chartType (line/bar/pie/number/histogram/pivot…) + chartConfig.

one widget: left "what to compute" + right "how to draw" query (declare: what to compute)view: OBSERVATIONSdimensions: [model] (group by model)metrics: [sum(totalCost)]filters: [env=production] chart (present: how to draw)chartType: BAR / LINE / PIE / NUMBER …same queryswap the chart query and chart decoupled: swap a chartType without touching the query, swap a metric without touching the drawing—each evolves independently
declarative query + presentation, cleanly split: schema.prisma:1536 DashboardWidget models view/dimensions/metrics/filters (what to compute) separately from chartType/chartConfig (how to draw). view from DashboardWidgetViews (4 values), chartType from DashboardWidgetChartType (9 charts).
quartet (query)meaningexample
viewdata sourceTRACES / OBSERVATIONS / SCORES_NUMERIC / SCORES_CATEGORICAL
dimensionsgroup-by axes (GROUP BY)by model, by day, by name…
metricsaggregationscount, sum(totalCost), avg(value), p95(latency)
filtersfilter conditionsenv=production, name=chat, time window
packages/shared/prisma/schema.prisma:1516-1560widget model + two enums
enum DashboardWidgetViews { TRACES  OBSERVATIONS  SCORES_NUMERIC  SCORES_CATEGORICAL }
enum DashboardWidgetChartType { LINE_TIME_SERIES  BAR_TIME_SERIES  HORIZONTAL_BAR
  VERTICAL_BAR  PIE  NUMBER  HISTOGRAM  PIVOT_TABLE  … }   // 9 chart types
model DashboardWidget {
  view       DashboardWidgetViews   // what data
  dimensions Json   // group by what (GROUP BY axes)
  metrics    Json   // compute what (aggregations)
  filters    Json   // filter
  chartType   DashboardWidgetChartType   // how to draw
  chartConfig Json                       // chart details
}
chart type (selection)good at expressingtypical use
LINE / AREA / BAR_TIME_SERIEStrend over timecost trend, daily call volume, score changes
HORIZONTAL / VERTICAL_BARcomparison across categoriescalls per model, spend ranking by user
NUMBERa single key valuethis month's total cost, total trace count (KPI number)
PIEcomposition of a wholecost share per model, score categorical distribution
HISTOGRAMdistribution of a valuelatency distribution, token-count distribution
PIVOT_TABLEmulti-dimensional cross-tabmodel × environment cost matrix

The same query, with a different chartType, is a different view: trend → time-series, magnitude → bar, composition → pie, distribution → histogram. Data stays, the angle changes on demand—exactly the exploratory freedom query/presentation separation brings.

One query shape, three reuses

The widget's view + dimensions + metrics + filters declaration—the neat part isn't that it can draw charts, it's that it's not only for drawing charts. The same declaration is shared by three places: the dashboard draws it as a chart, Lesson 33's monitor periodically computes it and compares to thresholds, and the next lesson's query engine compiles it to ClickHouse SQL. One proof hides in the enums: the monitor's MonitorView is exactly DashboardWidgetViews minus TRACES (the source comment literally says "mirrors DashboardWidget, minus TRACES").

one "what to compute" declaration, fed to three consumers query shape (declaration)view + dimensions + metrics + filters dashboard (this lesson)draw as a chart (pull: you look) monitor (Lesson 33)periodic threshold (push: it calls) query engine (Lesson 41)compile to ClickHouse SQL MonitorView = DashboardWidgetViews minus TRACES (source comment: mirrors DashboardWidget, minus TRACES)
declare once, reuse everywhere: any curve you can draw on a dashboard can become a monitor alert in one click (Lesson 33), and is compiled to SQL by the same query engine (Lesson 41). Pull (you look at a dashboard) and push (a monitor calls you) share one metric definition—the very reason Lesson 33 can "reuse DashboardWidget".
🎯 Design trade-off
Why does a widget declare "what to compute" and "how to draw" separately rather than just write code that "draws some chart"? Because these are two orthogonal dimensions, and forcing them together limits both. Splitting them, you instantly get triple freedom: the same query swaps a chartType to go from line to bar (great for exploring data); the same chart swaps a metric to go from cost to latency; and crucially, that pure "what to compute" declaration, untainted by any presentation logic, can be borrowed verbatim by the monitor and the query engine. The power of declarative is that it describes "intent" not "steps"—intent can be realized by arbitrarily many executors in different ways. Same belief as Lesson 23's FilterState and Lesson 21's tRPC contract: lift "what you want" out of "how to do it", and the room for reuse and evolution opens up.

Why is this query shape worth sharing across three places rather than each writing its own? Because "a metric" as a product concept should be unified. If the dashboard's "average helpfulness" and the monitor's "average helpfulness" are two separate implementations, they will eventually compute different numbers—definition drift is a slow poison for data products. Having three places share one declaration and one query engine nails down "this metric has exactly one algorithm company-wide". What you see on the chart, what alerts are based on, and what the API returns are always the same number. Consistency isn't maintained by discipline but guaranteed at the root by architecture.
🎯 Key points
  • Dashboards see the global: aggregate thousands of records into charts, answering "did cost rise", "which model is slow", "score trends"—adding the "see the whole" the first seven parts' "see one" lacked.
  • Two-layer model: Dashboard (definition layout + board-level filters) holds a row of DashboardWidgets; each widget is a saved "query + chart".
  • A widget = declarative query + chart: the query quartet view (source) + dimensions (group) + metrics (aggregate) + filters; presentation is chartType (9 charts) + chartConfig. What to compute and how to draw, cleanly split.
  • Query/presentation decoupled: swap the chart without the query, swap the metric without the drawing; a pure "what to compute" declaration can be reused verbatim—declarative describes intent not steps.
  • One query shape, three reuses: dashboard charts, Lesson 33 monitor thresholds, Lesson 41 engine SQL share one declaration (MonitorView = DashboardWidgetViews minus TRACES). One algorithm per metric company-wide; pull and push always the same number.

🧪 Self-test - think about the design

1. Langfuse's DashboardWidget models view+dimensions+metrics+filters (query) separately from chartType+chartConfig (chart). The biggest benefit of this 'query/presentation separation' is?
  1. makes charts render faster
  2. auto-selects the best chart
  3. query and chart are orthogonal and evolve freely: same query swaps chartType to change the chart, same chart swaps metric to change the quantity; crucially the pure 'what to compute' declaration, untainted by presentation, can be reused verbatim by the monitor/query engine
  4. reduces the number of DB tables
Show answer & explanation click to expand
Answer: C. Query (what to compute) and chart (how to draw) are two orthogonal dimensions; tight coupling limits both. Split: same query swaps chartType from line to bar, same chart swaps metric from cost to latency; crucially that pure 'what to compute' declaration, untainted by presentation, can be borrowed verbatim by Lesson 33's monitor and Lesson 41's query engine. Declarative describes intent not steps—same belief as Lesson 23's FilterState and Lesson 21's tRPC contract.
2. Lesson 33's monitor source comment says it 'mirrors DashboardWidget, minus TRACES', and MonitorView is exactly DashboardWidgetViews minus TRACES. What design intent does this reuse reveal?
  1. to save storage
  2. TRACES data can't be monitored
  3. the monitor is a subset feature of dashboards
  4. a metric has exactly one algorithm company-wide: dashboard charts, monitor thresholds, and the query engine's SQL share one query shape, so what you see on the chart, what alerts on, and what the API returns are always the same number—consistency guaranteed at the root by architecture, not discipline
Show answer & explanation click to expand
Answer: D. If the dashboard's and the monitor's 'average helpfulness' were separate implementations, they'd eventually compute different numbers—definition drift is a slow poison for data products. Having three places share one view+dimensions+metrics+filters declaration and one query engine nails down 'this metric has one algorithm company-wide'. Pull (chart) and push (alert) are always the same number. Consistency is guaranteed by architecture, not maintained by discipline.
3. A DashboardWidget's view field comes from the DashboardWidgetViews enum. What are its four values?
  1. SUM, AVG, COUNT, MAX
  2. LINE, BAR, PIE, NUMBER
  3. DAY, WEEK, MONTH, YEAR
  4. TRACES, OBSERVATIONS, SCORES_NUMERIC, SCORES_CATEGORICAL—i.e. a widget can aggregate one of these four data sources: traces, observations, numeric scores, or categorical scores
Show answer & explanation click to expand
Answer: D. DashboardWidgetViews = { TRACES, OBSERVATIONS, SCORES_NUMERIC, SCORES_CATEGORICAL }, deciding which data source a widget aggregates. LINE/BAR/PIE/NUMBER belong to a different enum, DashboardWidgetChartType (how to draw, 9 types). view governs 'what data', chartType 'what chart'—exactly the query/presentation split. The monitor's MonitorView is this minus TRACES.
💭 Open questions (no single right answer - just think or try)
  • 'One query shape, three reuses' is Langfuse's core move for guaranteeing metric-definition consistency. Recall data products you've built or used: have you hit 'the same metric computes different numbers on different pages/reports/alerts' definition drift? If you designed a mechanism to cure it, how would you? How would you weigh the costs of declarative-query + unified-engine (limited flexibility, the engine must support all needs)?