第 1 课认识了 trace / observation / score 三个名字,这一课把它们拆开看里子:每个到底有哪些字段、为什么这样设计、
又怎么落到 ClickHouse 的三张表上。它们的「真身」是 packages/shared/src/domain/ 下的三个 Zod schema——
读懂这三个 schema,等于拿到了理解 Langfuse 后面所有功能的钥匙,因为评估、数据集、仪表盘……最终都在操作这三种对象。
打个比方,如果说第 1 课给了你一张「Langfuse 全景照」,这一课就是把照片里的三个主角拉到跟前,挨个看清他们的五官——
记住他们长什么样,后面无论他们出现在哪一课的剧情里,你都能一眼认出。
parentObservationId 指向父节点,UI 再据此反向拼出整棵调用树(第 25 课)。根节点的 parent 为 null。这种「只存父指针」的设计,让写入时各 observation 互相独立、可乱序到达——非常契合异步摄取。domain/observations.ts;值为示例):每个 observation 用 parentObservationId 指向父节点,根节点为 null;于是「谁调用了谁、各花多久」就是这棵树的结构 + 每行的 latency。score 可挂在 trace 或任一 observation 上。先看最简单的 trace。它的领域模型 TraceDomain 字段很少,几乎都是身份与标记,没有什么「重」数据:
export const TraceDomain = z.object({ id: z.string(), // trace 的唯一 id name: z.string().nullable(), timestamp: z.date(), environment: z.string(), // 多租户隔离维度(第 10 课) tags: z.array(z.string()), bookmarked: z.boolean(), public: z.boolean(), sessionId: z.string().nullable(), // 串成会话(第 26 课) userId: z.string().nullable(), input: jsonSchema.nullable(), // 整次交互的输入/输出 output: jsonSchema.nullable(), metadata: MetadataDomain, projectId: z.string(), });
注意 trace 上几乎没有「成本」「token」「模型」这类字段——那些都在 observation 上。trace 的职责就是把一次交互的所有 observation 关联起来,
外加几个方便检索的标记:userId(哪个用户)、sessionId(哪一轮会话)、tags(自定义标签)、bookmarked(人工收藏)、
public(是否可公开分享)。这印证了第 1 课那句话:trace 是关联句柄,不是主分析单元。
别小看这几个「标记」字段,它们各自对应一个真实的产品功能:bookmarked 让你在排查时把可疑 trace 收藏起来稍后细看;
public 控制这条 trace 能否生成一个公开分享链接(第 27 课),方便你把一个坏 case 甩给同事而不用对方登录;
environment 把 prod / staging / dev 的数据隔离开(第 10 课),避免测试流量污染线上看板;release 和
version 记录「这条 trace 来自应用的哪个版本」,于是上线后回归时,你能直接按版本对比质量与成本。换句话说,trace 虽薄,
但每个字段都是为「事后好查、好分享、好归类」而精心挑选的。
observation 才是「厚」的那一个。先看类型——很多人以为只有 3 种,其实当前领域模型 ObservationType 有 10 种:
在看字段之前,先理解上面那张树图背后的一个关键设计:observation 之间的父子关系,只靠子节点上的一个 parentObservationId 指针表达,
父节点完全不知道自己有哪些孩子。这看似简单,却是为异步摄取量身定做的——因为每个 observation 都自带「我爸是谁」,它们就能
各自独立、乱序到达服务端:子节点比父节点先到也没关系,反正等查询时 UI 再按指针把树拼出来(第 25 课)。如果反过来让父节点维护一个 children 列表,
那就得「等所有孩子到齐才能写父节点」,在高并发异步管线里这是灾难。一个小小的指针方向选择,背后是整条摄取链路的可行性。
| 类型 | 含义 | 典型场景 |
|---|---|---|
| GENERATION | 一次 LLM 调用 | 带 model / token / cost 的那种 |
| SPAN | 一段有耗时的逻辑 | 检索、预处理、整段流程 |
| EVENT | 一个瞬时事件 | 打点、状态变化 |
| AGENT | 一个 agent 步骤 | agent 框架的一轮决策 |
| TOOL | 一次工具调用 | function/tool call |
| CHAIN | 一条链 | LangChain 式的链路 |
| RETRIEVER | 一次检索 | 向量/关键词召回 |
| EMBEDDING | 一次向量化 | embedding 调用 |
| EVALUATOR | 一次评估 | 评审步骤 |
| GUARDRAIL | 一次护栏检查 | 安全/合规拦截 |
这 10 种里,SPAN / EVENT / GENERATION 是最基础的三型(LegacyPrismaObservationType 最早只有这 3 个,现已同步到 10 种),
其余 7 种是后来为更精细地刻画 agent/RAG 流程而加的「更具体的 span」。除了类型,observation 还有 level(DEBUG/DEFAULT/WARNING/ERROR)
表示严重程度。真正让它「厚」的,是下面这一大堆富属性字段:
parentObservationId: z.string().nullable(), // 拼树用的父指针 model: z.string().nullable(), // 哪个模型 modelParameters: jsonSchema.nullable(), input: jsonSchema.nullable(), output: jsonSchema.nullable(), promptId / promptName / promptVersion, // 关联到哪版 prompt(第 37 课) latency, timeToFirstToken, // 延迟 / 首 token 时延 usageDetails, costDetails, // 用量 / 成本明细(Map) inputUsage / outputUsage / totalUsage, // 聚合后的 token 数 inputCost / outputCost / totalCost, // 聚合后的成本 toolDefinitions, toolCalls, toolCallNames, // 工具调用信息
看到没——一条 observation 就把「这步用了哪个模型、吃了多少 token、花了多少钱、多久、关联哪版 prompt、调了哪些工具」全装下了。 这正是第 2 课说的「宽事件」:高基数上下文整行内联,于是「按模型看成本」「按 prompt 版本比延迟」都成了对这张宽表的普通查询。
这里有个容易混淆、但很能体现设计用心的细节:用量和成本各有两套字段——providedUsageDetails / providedCostDetails
是 SDK 上报时「自带」的(你的应用如果知道 token 数和价格,可以直接报上来),而 usageDetails / costDetails
是 Langfuse 自己「算出来」的(摄取时按模型定价表计算,第 16 课)。两套并存的好处是:你报的我尊重,你没报的我兜底——
既允许应用精确控制,又保证即使应用什么都不报,Langfuse 也能根据 model 名匹配定价、把成本补齐。这种「provided 优先、computed 兜底」的模式,
在后面成本计算一课会反复出现。
还有两个不起眼但排错时极有用的字段:level(DEBUG / DEFAULT / WARNING / ERROR)和 statusMessage。前者给每个 observation 标上
严重程度,后者记一句状态说明(比如报错信息)。有了它们,你就能在成千上万条 observation 里一键过滤出
level = ERROR 的那些——直接定位「哪一步挂了、报了什么」,而不必从头翻整棵树。这又一次体现了「把高基数上下文留在每一步上」的价值:
连「这步是不是出错了」都是可查询、可聚合的一列。
第三支柱 score 把「可观测」升级成「可评估」。它的两个核心维度是来源(source)和数据类型(dataType),都定义在
packages/shared/src/domain/scores.ts:
EVAL(自动评审,第 29–31 课)、ANNOTATION(人工,第 32 课)、API(SDK 提交);右边是「打给谁」——可挂在 trace(整次交互)或某个 observation(具体一步)上。中间的 score 本身带一个值和一个 dataType。score 的数据类型有 5 种(ScoreDataTypeArray):NUMERIC 数值、CATEGORICAL 分类、
BOOLEAN 布尔、CORRECTION 订正、TEXT 文本。来源(ScoreSourceArray)有 3 种:
API / EVAL / ANNOTATION。一条规则值得记住:ANNOTATION 来源的 score 必须带一个匹配的
configId(唯一例外是 CORRECTION 类型),这样它才能在标注队列 UI 里正确渲染——见 scores.ts 的
isAnnotationScoreMissingConfigId。
| dataType | 取值长什么样 | 典型用途 |
|---|---|---|
| NUMERIC | 一个数,如 0.9 | 相关性、帮助度等连续评分 |
| CATEGORICAL | 一个标签,如「正确」 | 把输出分到若干类别 |
| BOOLEAN | true / false | 是否通过、是否安全 |
| CORRECTION | 一段订正后的文本 | 人工把错误输出改对(不需要 configId) |
| TEXT | 一段自由文本(≤500 字) | 评语、理由 |
三种来源也不是随便分的,它们对应着不同的「评分主体」,权限也不同:EVAL 是 Langfuse 内部评估器的产物
(LLM-as-judge、代码评估,第 29–31 课),保留给系统内部使用;ANNOTATION 是人在 UI 里手动标注;API 则是你的应用
通过 SDK 直接提交(比如把用户点的「👍/👎」上报成分数)。源码里有个细节能印证这点:公共建分接口允许的来源只有 API 和 ANNOTATION
两种(PublicApiCreateScoreSourceDomain),EVAL 被刻意排除在外——因为它是平台自己产生的,不该由外部冒充。这种「按来源划权限」的小设计,
保证了「谁打的分」这件事可信。
为什么三支柱要落到三张分开的 ClickHouse 表,而不是塞进一张大表?因为它们的访问模式不同:observation 量最大、查询最频繁、字段最宽; score 数量少、常按 trace/observation 关联查;trace 居中、是列表页的主入口。分表能让每张表用最适合自己的排序键与分区(第 8 课), 互不拖累。这又是一次「按访问模式选存储」的体现——和「为什么 Postgres + ClickHouse 并存」(第 7 课)是同一种思路,只是粒度更细。
这三个领域对象,在分析存储里一一对应三张 ClickHouse 表(第 8 课细讲)。要区分两个层次:domain/*.ts 里的 Zod schema 是
「形状契约」——前端、后端、SDK 都按它理解数据;而 ClickHouse 的建表 SQL 是「物理存储」——决定数据在磁盘上怎么排、怎么压、怎么扫。
同一个概念,一个管「长什么样」,一个管「怎么存」:
domain/traces.tsdomain/observations.tsdomain/scores.ts
前端后端共用的形状
0001_traces.up.sql0002_observations.up.sql0003_scores.up.sql
ReplacingMergeTree · 按月分区
还有一个常被忽略的「第四类」聚合:session(会话)。它不是一张宽事件表,而是靠 trace 上的 sessionId
把多次 trace 串成一段连续对话(比如用户和你的 bot 来回聊了十轮)。session 的元数据在 Postgres 的 TraceSession 模型里,
聚合视图则在查询时算出来(第 26 课)。所以严格说,Langfuse 的核心数据是「三支柱 + 会话聚合」。
举个会话的例子:用户在客服 bot 上连问了三轮——「我的订单到哪了?」→「那能改地址吗?」→「帮我改成公司地址」。这三轮各自是一个独立的 trace
(每轮一次完整问答),但它们带着同一个 sessionId。于是在「会话」视图里,你能把这三个 trace 当成一段连续对话来看:整段聊了多久、
一共花了多少钱、用户在第几轮开始不耐烦。这种「单次看 trace、连续看 session」的双视角,正是因为 sessionId 这一个字段把关联关系提前埋在了写入里,
查询时不必再做复杂的会话切分。
把三支柱合起来看,你会发现一个漂亮的分工:trace 负责「关联」、observation 负责「记录」、score 负责「评判」、session 负责「串联」。 四者各司其职、字段不重复堆砌,又都能在一次查询里被关联起来。后面五十多课无论讲摄取、查询、评估还是仪表盘,操作的都是这四种对象—— 现在把它们的形状刻进脑子里,后面会轻松很多。
userId/sessionId/tags/bookmarked/public),职责是关联。ObservationType 有 10 种(核心三型 SPAN/EVENT/GENERATION),靠 parentObservationId 拼树,内联 model/usage/cost/prompt/tool 等富属性。API/EVAL/ANNOTATION)× 数据类型(NUMERIC/CATEGORICAL/BOOLEAN/CORRECTION/TEXT),可挂 trace 或 observation。sessionId 把多个 trace 串成会话。domain/*.ts schema,就拿到了理解后面所有功能的钥匙,因为评估、数据集、仪表盘最终都在操作它们。
Lesson 1 introduced the names trace / observation / score; this lesson opens them up: exactly which fields each
has, why it's designed that way, and how each lands in one of three ClickHouse tables. Their "true form" is three Zod schemas under
packages/shared/src/domain/ — read these three schemas and you hold the key to every later Langfuse
feature, because evaluation, datasets, dashboards… all ultimately operate on these three objects.
parentObservationId pointing at its parent, and the UI reconstructs the call tree from that (L25). The root's parent is null. Storing only a parent pointer lets observations be independent and arrive out of order at write time — ideal for async ingestion.domain/observations.ts; values illustrative): each observation points at its parent via parentObservationId, the root being null; so "who called whom, taking how long" is just this tree's shape plus each row's latency. A score can attach to the trace or any observation.Start with the simplest, the trace. Its domain model TraceDomain has few fields, almost all identity and
markers, no "heavy" data:
export const TraceDomain = z.object({ id: z.string(), // the trace's unique id name: z.string().nullable(), timestamp: z.date(), environment: z.string(), // tenancy isolation dimension (L10) tags: z.array(z.string()), bookmarked: z.boolean(), public: z.boolean(), sessionId: z.string().nullable(), // strung into a session (L26) userId: z.string().nullable(), input: jsonSchema.nullable(), // the whole interaction's I/O output: jsonSchema.nullable(), metadata: MetadataDomain, projectId: z.string(), });
Notice there's almost no "cost", "token" or "model" field on the trace — those all live on observations. The
trace's job is to correlate all observations of one interaction, plus a few searchable markers: userId
(which user), sessionId (which conversation), tags (custom labels), bookmarked (human
favorite), public (shareable). This confirms Lesson 1's line: the trace is a correlation handle, not the
primary analytical unit.
Don't underrate those "marker" fields — each maps to a real product feature: bookmarked lets you favorite
a suspicious trace during triage to revisit later; public controls whether the trace can produce a public share
link (L27), so you can hand a bad case to a colleague without making them log in; environment
isolates prod / staging / dev data (L10) so test traffic doesn't pollute production dashboards; release
and version record "which app version this trace came from", so after a deploy you can compare quality and cost
by version. In short, the trace is thin, but every field is hand-picked for "easy to find, share and categorize later".
The observation is the "heavy" one. Types first — many assume there are only 3, but the current ObservationType has
10:
Before the fields, grasp one key design behind that tree figure: the parent-child relationship among observations is expressed
only by a parentObservationId pointer on the child — the parent has no idea which children it has. Simple
as it looks, this is tailor-made for async ingestion: because each observation carries "who my
parent is", they can arrive independently and out of order at the server — a child arriving before its parent is
fine, since the UI rebuilds the tree from the pointers at query time (L25). Flip it — make the parent maintain a children list — and
you'd have to "wait for all children before writing the parent", a disaster in a high-concurrency async pipeline. One small
choice of pointer direction underwrites the whole ingestion path's feasibility.
| Type | Meaning | Typical use |
|---|---|---|
| GENERATION | one LLM call | the kind with model / token / cost |
| SPAN | a timed unit of logic | retrieval, preprocessing, a whole flow |
| EVENT | an instantaneous event | a marker, a state change |
| AGENT | an agent step | one decision round in an agent framework |
| TOOL | a tool call | function/tool call |
| CHAIN | a chain | a LangChain-style chain |
| RETRIEVER | a retrieval | vector/keyword recall |
| EMBEDDING | an embedding | embedding call |
| EVALUATOR | an evaluation | a judging step |
| GUARDRAIL | a guardrail check | safety/compliance gate |
Of the 10, SPAN / EVENT / GENERATION are the three foundational types (the original
LegacyPrismaObservationType originally had only these, now extended to 10 too); the other 7 are "more specific spans" added to describe agent/RAG flows
more precisely. Besides type, an observation has a level (DEBUG/DEFAULT/WARNING/ERROR) for severity. What truly makes
it "heavy" is the pile of rich-attribute fields below:
parentObservationId: z.string().nullable(), // parent pointer for the tree model: z.string().nullable(), // which model modelParameters: jsonSchema.nullable(), input: jsonSchema.nullable(), output: jsonSchema.nullable(), promptId / promptName / promptVersion, // which prompt version (L37) latency, timeToFirstToken, // latency / time to first token usageDetails, costDetails, // usage / cost breakdown (Map) inputUsage / outputUsage / totalUsage, // aggregated token counts inputCost / outputCost / totalCost, // aggregated cost toolDefinitions, toolCalls, toolCallNames, // tool-call info
See it — one observation captures "which model this step used, how many tokens, how much money, how long, which prompt version, which tools" all at once. This is exactly Lesson 2's "wide event": high-cardinality context inlined on the row, so "cost by model" and "latency by prompt version" become ordinary queries over this wide table.
One easily-confused detail that shows real design care: usage and cost each have two sets of fields —
providedUsageDetails / providedCostDetails are what the SDK "brought" at report time (if your
app knows the token count and price, it can send them directly), while usageDetails / costDetails are
what Langfuse "computed" itself (at ingestion, from the model pricing table, L16). Keeping both has a clear payoff:
respect what you sent, backfill what you didn't — apps can control things precisely, yet even if an app sends
nothing, Langfuse can match the model name to pricing and fill in the cost. This "provided wins, computed backfills" pattern recurs
in the cost lesson.
Two more humble-but-invaluable fields for debugging: level (DEBUG / DEFAULT / WARNING / ERROR) and
statusMessage. The former tags each observation with a severity; the latter records a status
line (e.g. an error message). With them you can filter tens of thousands of observations down to those with
level = ERROR in one click — jumping straight to "which step failed and what it said" instead of scanning the whole
tree. Again the value of "keep high-cardinality context on each step": even "did this step error" is a queryable, aggregatable
column.
The third pillar, score, upgrades "observable" into "evaluable". Its two core dimensions are source and
dataType, both defined in packages/shared/src/domain/scores.ts:
A score's dataType is one of 5 (ScoreDataTypeArray): NUMERIC, CATEGORICAL,
BOOLEAN, CORRECTION, TEXT. Its source (ScoreSourceArray) is one
of 3: API / EVAL / ANNOTATION. One rule worth remembering: an ANNOTATION-sourced score
must carry a matching configId (the sole exception is the CORRECTION type), so it renders correctly in the
annotation-queue UI — see isAnnotationScoreMissingConfigId in scores.ts.
| dataType | What the value looks like | Typical use |
|---|---|---|
| NUMERIC | a number, e.g. 0.9 | relevance, helpfulness — continuous scores |
| CATEGORICAL | a label, e.g. "correct" | bucket the output into classes |
| BOOLEAN | true / false | passed?, safe? |
| CORRECTION | a corrected text | a human fixes a wrong output (no configId needed) |
| TEXT | free text (≤500 chars) | a comment, a rationale |
The three sources aren't arbitrary either — they correspond to different "scoring authors" with different
permissions: EVAL is the output of Langfuse's internal evaluators (LLM-as-judge, code evals, L29–31) and
is reserved for the system; ANNOTATION is a human labeling in the UI; API is your app
submitting directly via the SDK (e.g. reporting a user's "👍/👎" as a score). A source-code detail confirms this: the public
create-score endpoint allows only API and ANNOTATION sources
(PublicApiCreateScoreSourceDomain), deliberately excluding EVAL — because it's platform-generated and
shouldn't be impersonated from outside. This little "permission by source" design keeps "who scored" trustworthy.
Why do the three pillars land in three separate ClickHouse tables rather than one big table? Because their access patterns differ: observations are the largest, most-queried, widest; scores are few and usually queried by trace/observation association; traces sit in the middle as the list-page entry point. Separate tables let each use the ordering key and partitioning best for itself (L08) without dragging on the others. This is again "choose storage by access pattern" — the same idea as "why Postgres + ClickHouse coexist" (L07), just at finer granularity.
These three domain objects map one-to-one to three ClickHouse tables in analytical storage (detailed in L08). Keep
two layers distinct: the Zod schema in domain/*.ts is the "shape contract" — frontend, backend and SDK
all read data by it; the ClickHouse CREATE TABLE SQL is the "physical storage" — deciding how data is ordered,
compressed and scanned on disk. Same concept: one governs "what it looks like", the other "how it's stored":
domain/traces.tsdomain/observations.tsdomain/scores.ts
shape shared by frontend & backend
0001_traces.up.sql0002_observations.up.sql0003_scores.up.sql
ReplacingMergeTree · monthly partitions
There's an easily-missed "fourth" aggregation: the session. It isn't a wide-event table; it's the trace's
sessionId stringing multiple traces into one continuous conversation (e.g. ten back-and-forth turns
with your bot). Session metadata lives in Postgres' TraceSession model; the aggregate view is computed at query time
(L26). So strictly, Langfuse's core data is "three pillars + session aggregation".
A session example: a user asks a support bot three turns in a row — "where's my order?" → "can I change the address?" → "change it
to my office address". Those three turns are each an independent trace (one full Q&A each), but they carry the
same sessionId. So in the "session" view you can see the three traces as one continuous conversation:
how long the whole chat took, how much it cost in total, at which turn the user got impatient. This "single trace vs continuous
session" dual view works precisely because the one sessionId field plants the relationship at write time,
so queries need no complex session segmentation.
Put the pillars together and a clean division of labor appears: trace correlates, observation records, score judges, session links. Each does its job, no field is piled up redundantly, yet all can be joined in one query. Whether later lessons cover ingestion, querying, evaluation or dashboards, they all operate on these four objects — carve their shapes into your mind now and the rest gets much easier.
userId/sessionId/tags/bookmarked/public); its job is to correlate.ObservationType has 10 values (core three SPAN/EVENT/GENERATION), builds a tree via parentObservationId, inlines model/usage/cost/prompt/tool rich attributes.API/EVAL/ANNOTATION) × dataType (NUMERIC/CATEGORICAL/BOOLEAN/CORRECTION/TEXT); attaches to a trace or observation.sessionId.domain/*.ts schemas and you hold the key to every later feature.