上一课说 Langfuse 的「设计灵魂」是宽事件 / 可观测性 2.0。这一课把这句口号讲透——它不是营销词,
而是写在 .agents/ARCHITECTURE_PRINCIPLES.md 里、约束着 Langfuse 每一处存储与查询设计的第一性原则。
理解了它,后面「为什么用 ClickHouse」「为什么事件不可变」「为什么列表只读窄字段」这些问题,答案都会自己浮现。
可以说,这一课是整份指南的地基课:它不讲某个具体模块,而讲一种看问题的方式,后面五十多课都建在它之上。
ARCHITECTURE_PRINCIPLES.md 说的「偏好宽而属性丰富的事件,而非需要事后重建的零散指标/日志/链路」。domain/observations.ts;值为示例):左边 1.0 把一步操作的数字、文本、调用链分给三套系统,回答「这个用户这小时花了多少」要先按 traceId 拼三处;右边 2.0 把它们焊进同一行宽 observation,同样的问题只是这张宽表的一次列查询。「指标 + 日志 + 链路」这套经典组合(业内常称可观测性 1.0)每一件单看都没错,问题出在三者分离:
于是真要排查一个跨维度的问题,你得在三套系统之间来回对账。Langfuse 的架构原则第一条就是冲着这个来的—— 把 observation 当作主分析单元,trace 只是关联句柄(原文:"Model observations as the primary analytical unit. A trace is a correlation handle that links related observations, not the only useful entry point.")。
举个具体的对比。线上有人投诉「晚高峰回答变慢」,你想知道「是不是某个模型在某些用户上特别慢」。
在 1.0 里:指标只有「全局平均延迟」这一条曲线,看不出是哪个模型、哪批用户;日志里能翻到单条记录,但几万行文本没法快速按模型分组算分位数;
链路能看单次调用的耗时,却没记 user 和 model 这些业务字段。三套都「沾边」,但没有一套能直接回答,你只能导出数据自己写脚本拼。
在 2.0 里:每条 observation 都同时带着 model、userId、latency,于是这个问题退化成一句普通查询——
「按 model + userId 分组、看 latency 的 p95」。同一个问题,1.0 要跨三系统拼半天,2.0 改个查询就答了。
「可观测性 2.0」的解法很直接:不要事后拼接,写的时候就别拆开。把一步操作的所有高基数上下文
(哪个模型、多少 token、多少钱、多久、哪个用户、哪些标签、什么环境……)原样塞进同一条记录——这条记录就是
Langfuse 里的 observation。它既是「链路节点」(有 parentObservationId 能拼出调用树),
又自带可聚合的数字(usageDetails / costDetails / latency),还携带任意业务字段
(metadata / tags / userId)。三件套想分开做的事,一条宽事件全包了。
你可能会问:那为什么不把这些字段拆成多张规整的表、用外键关联,岂不是更「干净」?答案是——查询时的 JOIN 是热路径上的隐藏成本。 可观测数据量极大(一个活跃项目一天可能上亿条 observation),如果每次「按模型看成本」都要把 observation 表和一张「模型表」「用量表」JOIN 起来, 扫描与连接的代价会随数据量爆炸。Langfuse 的原则是谨慎反范式化(denormalize carefully):把常用来过滤、聚合的字段直接内联到 observation 行上,让「按模型 / 按用户 / 按时间」这些高频查询变成直接的列谓词,而不是 JOIN。这就是「宽」的另一层含义—— 不只是字段多,更是有意把该放在一起的放在一起,用一点存储冗余换查询时不必连表。
指标、日志、链路各存一处;问一个跨维度问题,要在三套系统里查三次再人肉对账。能问什么,上线前就被字段设计锁死了。
一条 observation 同时有数字、结构、业务字段。切片、分组、过滤都是对同一张宽表的查询,事后想问什么都行。代价:行更宽、存得更多。
packages/shared/src/domain/observations.ts:55 ObservationSchema 把关联(id/traceId/parentObservationId)、数字(latency/usageDetails/costDetails)、业务(model/metadata/environment/promptName)三类字段塞进同一行。这就是「宽」的字面含义——也是「下钻=查这张表、聚合=也查这张表」的根。export const ObservationSchema = z.object({ // ① 关联字段:拼出调用树,也让本行能独立查询 id: z.string(), traceId: z.string().nullable(), projectId: z.string(), parentObservationId: z.string().nullable(), type: ObservationTypeDomain, // ② 数字字段:可直接 sum/avg/p95,无需从日志 parse latency: z.number().nullable(), timeToFirstToken: z.number().nullable(), usageDetails: z.record(z.string(), z.number()), costDetails: z.record(z.string(), z.number()), totalCost: z.number().nullable(), totalUsage: z.number(), // ③ 业务字段:让「按模型 / 按环境 / 按 prompt」变成列谓词 model: z.string().nullable(), environment: z.string(), metadata: MetadataDomain, promptName: z.string().nullable(), promptVersion: z.number().nullable(), input: jsonSchema.nullable(), output: jsonSchema.nullable(), // 大字段,详情页才读(第24课) });
ARCHITECTURE_PRINCIPLES.md 里的每一条,都能在后面的课里找到对应的工程落点。下表是「原则 → 它换来什么 → 哪一课展开」:
| 架构原则(原文要义) | 它换来什么 | 对应 |
|---|---|---|
| observation 为主分析单元,trace 是关联句柄 | 任何一步都能独立查询,不必从 trace 进入 | 第 3 课 |
| 偏好宽而属性丰富的事件,而非零散三件套 | 下钻与聚合统一成「查同一张宽表」 | 第 8 课 |
| 保留高基数上下文,应对 unknown unknowns | 事后能问上线时没想到的问题 | 本课 |
| 偏好不可变 / 追加式事件记录 | 避免读时去重的隐藏开销;用 ReplacingMergeTree | 第 8 课 |
| 谨慎反范式化,消除热路径 JOIN | 常用过滤变成直接的列谓词 | 第 8 · 22 课 |
| 围绕列式访问设计(窄字段、时间窗口、排序键、剪枝) | 大表上也能毫秒级扫描聚合 | 第 8 · 23 课 |
| 列表/仪表盘用紧凑表示,详情页才读大字段 | 列表快、详情全,互不拖累 | 第 24 课 |
| API 契约要「规模感知」:强制时间窗口、token 分页 | 防止一不小心扫全表历史 | 第 27 课 |
| 把成本与运维简单性当作架构约束 | 不轻易加库/队列/物化视图 | 第 53 课 |
宽事件最大的价值,是回答你当初没想到要问的问题。预先聚合的指标只能回答已知问题(你建了哪张仪表盘就只能看哪个维度); 而把高基数上下文整行留下,新问题来了,换个查询就能答,不必改埋点、不必等下次上线。
这一点对一个平台尤其关键。Langfuse 要给成千上万个项目用,它不可能预先知道每个团队会关心什么维度——
有人想看「按 prompt 版本对比成本」,有人想看「按 session 看用户多轮对话的总延迟」,有人想按自定义 metadata 标签切分。
如果走预聚合的老路,平台就得为每种需求预先建一张指标——这既做不完、也僵化。宽事件让 Langfuse 把「定义新视图」这件事,
从「改埋点 + 重新上线」降级成「写一条新查询」:仪表盘、自定义指标、过滤器(第 23、40 课)本质上都是在同一张宽表上换查询。
这就是为什么「保留高基数上下文」不是锦上添花,而是整个平台可扩展性的地基。
.agents/ARCHITECTURE_PRINCIPLES.md 的第一性原则,逐条对应后面的存储与查询设计。九到十条原则乍看零散,其实围着四个主题转——它们层层递进,正好对应这份指南后面四大块内容。把它们分组记,比逐条背更有用:
这四组也正是本指南的主线:数据模型是第一部分(本部分),存储是第二部分,写入与查询两条链路是第三、四部分, 契约与成本则散落在公共 API(第 27 课)与运维(第 53 课)。换句话说,你现在读的这份「设计哲学」,就是后面五十多课的提纲。
还有一条容易被忽略但很关键的原则:保留近实时的调试体验(原文:"Preserve real-time or near-real-time debugging workflows. Batch processing can help, but it should not make fresh production behavior invisible.")。这解释了为什么 Langfuse 的摄取虽是异步的,却要把处理延迟压到秒级——可观测性如果「看不到刚刚发生的事」,就失去了一半意义。这条会在第 14–17 课的摄取链路里反复出现。
Last lesson called Langfuse's "design soul" wide events / Observability 2.0. This lesson makes the slogan
concrete — it is not marketing; it's a first principle written into
.agents/ARCHITECTURE_PRINCIPLES.md that constrains every storage and query decision in Langfuse. Grasp it and
the later questions — "why ClickHouse", "why immutable events", "why lists read only narrow fields" — answer themselves. This
lesson is the guide's foundation lesson: not about one module but about a way of seeing that the
fifty-odd later lessons build on.
ARCHITECTURE_PRINCIPLES.md means by "prefer wide, richly attributed events over fragmented metrics, logs, and trace records that require later reconstruction".domain/observations.ts; values illustrative): on the left, 1.0 scatters one step's numbers, text and call tree across three systems — answering "how much did this user spend this hour" means stitching three places by traceId; on the right, 2.0 welds them onto one wide observation row, and the same question is one column query.The classic "metrics + logs + traces" combo (often called Observability 1.0) is fine piece by piece; the problem is that the three are separate:
So to triage a cross-dimension problem you end up reconciling across three systems. Langfuse's very first architecture principle targets exactly this — treat the observation as the primary analytical unit, with the trace as a correlation handle (verbatim: "Model observations as the primary analytical unit. A trace is a correlation handle that links related observations, not the only useful entry point.").
A concrete contrast. Someone complains that "answers get slow at peak hours" and you want to know "is a
particular model slow for particular users". In 1.0: metrics give you one "global average latency" curve that can't tell
which model or which users; logs have the individual records but tens of thousands of text lines won't quickly group-by-model and
compute percentiles; traces show per-call duration but never recorded the user and model business fields.
All three are "related", yet none can answer directly — you end up exporting data and scripting the join yourself.
In 2.0: every observation already carries model, userId and latency, so the question
collapses to one ordinary query — "group by model + userId, look at p95 of latency". Same question: 1.0 stitches across
three systems for ages; 2.0 just changes the query.
The "Observability 2.0" fix is direct: don't reassemble later — don't split it when you write. Cram all
the high-cardinality context of one step (which model, how many tokens, how much money, how long, which user, which tags,
what environment…) into one record — that record is a Langfuse observation. It's both a "trace
node" (with parentObservationId to rebuild the call tree), a bag of aggregatable numbers
(usageDetails / costDetails / latency), and a carrier of arbitrary business fields
(metadata / tags / userId). Everything the three pillars do separately, one wide event does
together.
You might ask: why not split these fields into several normalized tables with foreign keys — isn't that "cleaner"? Because JOINs at query time are a hidden hot-path cost. Observability data is enormous (an active project can write hundreds of millions of observations a day); if every "cost by model" had to JOIN the observation table with a "models" table and a "usage" table, the scan-and-join cost explodes with volume. Langfuse's principle is to denormalize carefully: inline the fields commonly used to filter and aggregate directly onto the observation row, so "by model / by user / by time" become plain column predicates instead of JOINs. That's the other meaning of "wide" — not just many fields, but deliberately keeping together what belongs together, trading a little storage redundancy for not joining at query time.
Metrics, logs and traces live apart; a cross-dimension question means three queries plus manual reconciliation. What you can ask is locked by field design before you ship.
One observation carries numbers, structure and business fields at once. Slice, group and filter are all queries over one wide table; ask anything later. Cost: wider rows, more storage.
packages/shared/src/domain/observations.ts:55 ObservationSchema packs link (id/traceId/parentObservationId), numeric (latency/usageDetails/costDetails), and business (model/metadata/environment/promptName) fields onto one row. That's the literal meaning of "wide" — and the root of "drill-down = query this table, aggregate = also query this table".export const ObservationSchema = z.object({ // ① link fields: build the call tree, and let this row be queried alone id: z.string(), traceId: z.string().nullable(), projectId: z.string(), parentObservationId: z.string().nullable(), type: ObservationTypeDomain, // ② numeric fields: sum/avg/p95 directly, no parsing from logs latency: z.number().nullable(), timeToFirstToken: z.number().nullable(), usageDetails: z.record(z.string(), z.number()), costDetails: z.record(z.string(), z.number()), totalCost: z.number().nullable(), totalUsage: z.number(), // ③ business fields: make "by model / by env / by prompt" a column predicate model: z.string().nullable(), environment: z.string(), metadata: MetadataDomain, promptName: z.string().nullable(), promptVersion: z.number().nullable(), input: jsonSchema.nullable(), output: jsonSchema.nullable(), // big fields, read on the detail page (Lesson 24) });
Every line in ARCHITECTURE_PRINCIPLES.md has an engineering landing spot in a later lesson. Below: "principle → what it buys → where".
| Architecture principle (gist) | What it buys | Lesson |
|---|---|---|
| observation = primary unit; trace = correlation handle | any step is independently queryable | L03 |
| prefer wide, richly-attributed events over fragmented pillars | drill-down & aggregation unify into one wide table | L08 |
| preserve high-cardinality context for unknown unknowns | ask questions you didn't foresee | this |
| favor immutable / append-oriented records | no read-time dedup cost; ReplacingMergeTree | L08 |
| denormalize carefully to kill hot-path JOINs | common filters become column predicates | L08·22 |
| design around columnar access (narrow fields, time bounds, ordering, pruning) | ms scans/aggregations even on big tables | L08·23 |
| compact list/dashboard views; read big payloads only on detail | fast lists, full detail, no mutual drag | L24 |
| scale-aware API contracts: time windows, token pagination | avoid accidental full-history scans | L27 |
| treat cost & operational simplicity as constraints | don't casually add DBs/queues/MVs | L53 |
The biggest payoff of wide events is answering questions you didn't think to ask up front. Pre-aggregated metrics answer only known questions (you see only the dimensions of dashboards you built); keep the high-cardinality context on the row and a new question is just a new query — no re-instrumenting, no waiting for the next deploy.
This matters especially for a platform. Langfuse serves thousands of projects and cannot know in
advance which dimensions each team cares about — one wants "cost by prompt version", another "total latency of a user's multi-turn
session", another to slice by custom metadata tags. The pre-aggregation route would force the platform to
predefine a metric per need — never-ending and rigid. Wide events let Langfuse demote "define a new view" from
"change instrumentation + redeploy" to "write a new query": dashboards, custom metrics and filters
(lessons 23, 40) are all just different queries over the same wide table. That's why "preserve high-cardinality context" isn't a
nicety — it's the foundation of the platform's extensibility.
.agents/ARCHITECTURE_PRINCIPLES.md, mapping line-by-line to later storage/query design.The nine-to-ten principles look scattered but revolve around four themes — layered, and matching the four big blocks of this guide. Grouping them beats memorizing them one by one:
These four groups are also the spine of this guide: data model is Part 1 (here), storage is Part 2, the write and read paths are Parts 3–4, and contract & cost show up in the public API (L27) and operations (L53). In other words, the "design philosophy" you're reading now is the outline of the fifty-odd lessons ahead.
One easily-missed but crucial principle: preserve near-real-time debugging (verbatim: "Preserve real-time or near-real-time debugging workflows. Batch processing can help, but it should not make fresh production behavior invisible."). This is why Langfuse's ingestion, though async, keeps processing lag to seconds — observability that "can't see what just happened" loses half its value. This recurs across the ingestion path in lessons 14–17.