为什么这套查询形状值得被三处共用,而不是各写各的? 因为「指标」这个概念在产品里本就该统一。如果仪表盘上的「平均有用性」和监控器里的「平均有用性」是两段独立实现,它们迟早会算出不同的数——口径漂移是数据产品的慢性毒药。让三处共享同一份声明、同一个查询引擎,等于钉死了「这个指标全公司只有一种算法」。你在图上看到的、和告警依据的、和 API 取到的,永远是同一个数。一致性不是靠纪律维持,而是靠架构从根上保证。
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 + filtersquery 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.
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".
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.
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).
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 typesmodel 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 expressing
typical use
LINE / AREA / BAR_TIME_SERIES
trend over time
cost trend, daily call volume, score changes
HORIZONTAL / VERTICAL_BAR
comparison across categories
calls per model, spend ranking by user
NUMBER
a single key value
this month's total cost, total trace count (KPI number)
PIE
composition of a whole
cost share per model, score categorical distribution
HISTOGRAM
distribution of a value
latency distribution, token-count distribution
PIVOT_TABLE
multi-dimensional cross-tab
model × 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 DashboardWidgetViewsminus TRACES (the source comment literally says "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?
makes charts render faster
auto-selects the best chart
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
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?
to save storage
TRACES data can't be monitored
the monitor is a subset feature of dashboards
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?
SUM, AVG, COUNT, MAX
LINE, BAR, PIE, NUMBER
DAY, WEEK, MONTH, YEAR
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)?