🪢 Langfuse 图解教程Langfuse Visual Guide 第一部分 · 宏观全景Part 1 · The Big Picture 03 / 55
第一部分 · 宏观全景Part 1 · The Big Picture

三大支柱深入:trace/observation/scoreThe three pillars in depth

第 1 课认识了 trace / observation / score 三个名字,这一课把它们拆开看里子:每个到底有哪些字段、为什么这样设计、 又怎么落到 ClickHouse 的三张表上。它们的「真身」是 packages/shared/src/domain/ 下的三个 Zod schema—— 读懂这三个 schema,等于拿到了理解 Langfuse 后面所有功能的钥匙,因为评估、数据集、仪表盘……最终都在操作这三种对象。 打个比方,如果说第 1 课给了你一张「Langfuse 全景照」,这一课就是把照片里的三个主角拉到跟前,挨个看清他们的五官—— 记住他们长什么样,后面无论他们出现在哪一课的剧情里,你都能一眼认出。

🔌 生活类比
把一次完整的用户交互想成医院里一个病历夹(trace):夹子封面只写几行身份信息(谁、什么时候、贴了哪些标签)。 夹子里一页页具体记录才是重点(observation):这页是「拍了 CT」、那页是「开了药」、再一页是「医生下了诊断」—— 每页都详细写明用了什么、花了多久、多少钱。最后,页边的红笔批注(score)给某一页或整个夹子评分:「这个诊断准确吗?9 分」。 封面薄、内页厚、批注点睛——这正是三大支柱的分工。把这套「夹子—内页—批注」的画面记住,下面看字段时就不会迷路:凡是「整次交互级」的信息往封面(trace)放,凡是「某一步级」的信息往内页(observation)放,凡是「评判级」的信息就是批注(score)。
observation 靠 parentObservationId 拼成一棵树 trace(关联句柄)· traceId 把下面这些 observation 串起来 A · span: agent-run parentObservationId = null(根) B · span: retrieve parent = A C · generation: gpt-4o parent = A · 1,240 tok · $0.012 latency 1.8s · prompt v3 D · span: rerank parent = B parentObservationId →
树是「指」出来的:observation 表里并没有「children」字段;每个 observation 只记一个 parentObservationId 指向父节点,UI 再据此反向拼出整棵调用树(第 25 课)。根节点的 parent 为 null。这种「只存父指针」的设计,让写入时各 observation 互相独立、可乱序到达——非常契合异步摄取。
observation 靠 parentObservationId 嵌成调用树 trace · id=agent_7(外壳,本身不是 observation) SPANagent-runparent = null(根)2.4s GENERATIONplan · gpt-4oparent = agent-run0.6s SPANtool: searchparent = agent-run0.5s GENERATIONsummarizeparent = tool: search0.3s scorename=relevance · value=0.85 · dataType=NUMERIC
嵌套 = 一棵树(字段对齐 domain/observations.ts;值为示例):每个 observation 用 parentObservationId 指向父节点,根节点为 null;于是「谁调用了谁、各花多久」就是这棵树的结构 + 每行的 latency。score 可挂在 trace 或任一 observation 上。

trace:薄薄的关联句柄

先看最简单的 trace。它的领域模型 TraceDomain 字段很少,几乎都是身份与标记,没有什么「重」数据:

packages/shared/src/domain/traces.tsTraceDomain
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:真正的主角

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) 表示严重程度。真正让它「厚」的,是下面这一大堆富属性字段:

packages/shared/src/domain/observations.tsObservationSchema(节选)
  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:评判

第三支柱 score 把「可观测」升级成「可评估」。它的两个核心维度是来源(source)和数据类型(dataType),都定义在 packages/shared/src/domain/scores.ts:

score:从三种来源,打给 trace 或 observation EVALLLM/代码自动评审 ANNOTATION人工标注 APISDK 直接提交 scorevalue + dataType trace给整次交互评分 observation给某一步评分
score 的两端:左边是「谁打的分」——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一个标签,如「正确」把输出分到若干类别
BOOLEANtrue / 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 课)是同一种思路,只是粒度更细。

三支柱 → 三张表:访问模式不同,所以分开存 traces 表列表页主入口量居中排序键/分区为「按时间列表」优化 observations 表量最大·字段最宽查询最频繁宽事件主场为聚合/过滤优化 scores 表量最少常按关联查为「按 trace/obs 取分」优化 traceId traceId/obsId 同「Postgres+ClickHouse 并存」(第7课)一脉:按访问模式选存储,只是粒度更细到「一支柱一张表」
三支柱 → 三张表:observation(量最大、字段最宽、查询最频繁)、trace(列表主入口)、score(量少、常按关联查)访问模式各异,分三张表各用最适合的排序键/分区(第 8 课),互不拖累。score 经 traceId/observationId 关联回去。

三者如何落到 ClickHouse 与 sessions

这三个领域对象,在分析存储里一一对应三张 ClickHouse 表(第 8 课细讲)。要区分两个层次:domain/*.ts 里的 Zod schema 是 「形状契约」——前端、后端、SDK 都按它理解数据;而 ClickHouse 的建表 SQL 是「物理存储」——决定数据在磁盘上怎么排、怎么压、怎么扫。 同一个概念,一个管「长什么样」,一个管「怎么存」:

领域模型(TS)

domain/traces.ts
domain/observations.ts
domain/scores.ts
前端后端共用的形状

ClickHouse 表(宽事件)

0001_traces.up.sql
0002_observations.up.sql
0003_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 负责「串联」。 四者各司其职、字段不重复堆砌,又都能在一次查询里被关联起来。后面五十多课无论讲摄取、查询、评估还是仪表盘,操作的都是这四种对象—— 现在把它们的形状刻进脑子里,后面会轻松很多。

🎯 设计取舍
为什么把「重」字段都堆在 observation,而让 trace 这么薄? 因为查询绝大多数发生在「步」这个粒度:你想按模型、按 prompt 版本、 按工具调用去聚合和过滤,这些维度天然属于某一步,而不是整次交互。把它们放在 observation 上,常用查询就成了对 observations 宽表的直接列谓词; trace 只需保留关联和少数检索标记。代价是同一信息(如 userId)可能要在 trace 和 observation 间冗余一份——这正是第 2 课「谨慎反范式化」的体现。 反过来理解这个取舍:Langfuse 主动付出一点重复,换来用户每天高频运行的查询无需连表、足够快。在可观测的数据规模下,这笔账几乎总是划算的。
🎯 本课要点
  • trace 很薄:几乎只有身份与标记(userId/sessionId/tags/bookmarked/public),职责是关联。
  • observation 很厚:ObservationType 有 10 种(核心三型 SPAN/EVENT/GENERATION),靠 parentObservationId 拼树,内联 model/usage/cost/prompt/tool 等富属性。
  • score 两维度:来源(API/EVAL/ANNOTATION)× 数据类型(NUMERIC/CATEGORICAL/BOOLEAN/CORRECTION/TEXT),可挂 trace 或 observation。
  • 三者 1:1 落到 三张 ClickHouse 宽事件表;session 靠 sessionId 把多个 trace 串成会话。
  • 读懂这三个 domain/*.ts schema,就拿到了理解后面所有功能的钥匙,因为评估、数据集、仪表盘最终都在操作它们。

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

1. 为什么 Langfuse 把 model/token/cost/prompt 等“重”字段都放在 observation 上,而让 trace 只有身份与少数标记?
  1. 因为 trace 不允许有任何字段
  2. 因为这样能减少 SVG 数量
  3. 因为绝大多数查询发生在“步”这个粒度(按模型、按 prompt 版本聚合过滤),把这些维度放在 observation 上,常用查询就成了对宽表的直接列谓词;trace 只需负责关联
  4. 因为 observation 存在 Postgres,trace 存在 ClickHouse
看答案与解析 点击展开
答案:C。查询的粒度决定了字段的归属。把高频过滤/聚合维度放在 observation 上,热查询变成列谓词、无需 JOIN;trace 保持薄、只做关联。代价是 userId 等可能在两边冗余,这正是“谨慎反范式化”。
2. observation 之间的父子关系只用子节点上的一个 parentObservationId 指针表达。这个设计对“异步摄取”有什么关键好处?
  1. 每个 observation 自带“我爸是谁”,于是它们能各自独立、乱序到达服务端;子节点先于父节点到也没关系,查询时 UI 再按指针拼出整棵树
  2. 它把树结构存成了一张额外的关系表
  3. 它要求所有 observation 必须按顺序写入
  4. 它让父节点能实时统计自己有几个孩子
看答案与解析 点击展开
答案:A。若反过来让父节点维护 children 列表,就得“等所有孩子到齐才能写父节点”,在高并发异步管线里是灾难。只存子节点的父指针,写入彻底解耦、可乱序,是摄取链路可行的关键(第 25 课拼树)。
3. observation 上为什么同时有 providedUsageDetails 和 usageDetails(成本同理)两套字段?
  1. provided 给前端用,usage 给后端用
  2. provided 是 SDK 上报时自带的,usage 是 Langfuse 摄取时按模型定价自己算的;“你报的我尊重、你没报的我兜底”
  3. 一个存 token,一个存金额
  4. 两者完全相同,纯属冗余
看答案与解析 点击展开
答案:B。两套并存兼顾“应用精确控制”和“平台兜底”:应用知道精确用量就直接报(provided),不报时 Langfuse 按 model 名匹配定价表算出来(computed)。这套“provided 优先、computed 兜底”在成本计算课(第 16 课)会展开。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 如果让你设计 score 的“来源”枚举,你会不会也像 Langfuse 一样禁止外部 API 提交 EVAL 来源的分数?说说这么做在“信任谁打的分”上的意义。

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.

🔌 Analogy
Picture one full user interaction as a hospital chart folder (trace): the cover has just a few identity lines (who, when, which tags). The pages inside are the point (observations): this page is "ran a CT scan", that one "prescribed a drug", another "the doctor reached a diagnosis" — each page detailing what was used, how long it took, how much it cost. Finally, red-pen margin notes (score) rate a page or the whole folder: "is this diagnosis accurate? 9/10". Thin cover, thick pages, pinpoint notes — exactly the division of the three pillars. Hold this "folder — pages — notes" image and you won't get lost in the fields below: whatever is "whole-interaction level" goes on the cover (trace), whatever is "single-step level" goes on a page (observation), and whatever is "judgment level" is a margin note (score).
observations form a tree via parentObservationId trace (correlation handle) · its traceId strings the observations below A · span: agent-run parentObservationId = null (root) B · span: retrieve parent = A C · generation: gpt-4o parent = A · 1,240 tok · $0.012 latency 1.8s · prompt v3 D · span: rerank parent = B parentObservationId →
The tree is "pointed" into existence: the observations table has no "children" field; each observation stores one 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.
observations nest into a call tree via parentObservationId trace · id=agent_7 (the shell, not an observation itself) SPANagent-runparent = null (root)2.4s GENERATIONplan · gpt-4oparent = agent-run0.6s SPANtool: searchparent = agent-run0.5s GENERATIONsummarizeparent = tool: search0.3s scorename=relevance · value=0.85 · dataType=NUMERIC
Nesting = a tree (fields per 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.

trace: the thin correlation handle

Start with the simplest, the trace. Its domain model TraceDomain has few fields, almost all identity and markers, no "heavy" data:

packages/shared/src/domain/traces.tsTraceDomain
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".

observation: the real star

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.

TypeMeaningTypical use
GENERATIONone LLM callthe kind with model / token / cost
SPANa timed unit of logicretrieval, preprocessing, a whole flow
EVENTan instantaneous eventa marker, a state change
AGENTan agent stepone decision round in an agent framework
TOOLa tool callfunction/tool call
CHAINa chaina LangChain-style chain
RETRIEVERa retrievalvector/keyword recall
EMBEDDINGan embeddingembedding call
EVALUATORan evaluationa judging step
GUARDRAILa guardrail checksafety/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:

packages/shared/src/domain/observations.tsObservationSchema (excerpt)
  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.

score: the verdict

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:

score: from three sources, onto a trace or observation EVALLLM/code auto-judge ANNOTATIONhuman annotation APIsubmitted via SDK scorevalue + dataType tracerate the whole interaction observationrate one step
Score's two ends: on the left, "who scored" — EVAL (auto-judge, L29–31), ANNOTATION (human, L32), API (SDK); on the right, "scored what" — attaches to a trace (whole interaction) or an observation (one step). The score itself carries a value and a dataType.

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.

dataTypeWhat the value looks likeTypical use
NUMERICa number, e.g. 0.9relevance, helpfulness — continuous scores
CATEGORICALa label, e.g. "correct"bucket the output into classes
BOOLEANtrue / falsepassed?, safe?
CORRECTIONa corrected texta human fixes a wrong output (no configId needed)
TEXTfree 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.

Three pillars → three tables: different access patterns, stored apart traces tablelist-page main entrymedium volumeordering/partitionoptimized for "list by time" observations tablelargest · widest fieldsmost-queriedhome of wide eventsoptimized for aggregate/filter scores tablelowest volumequeried by relationoptimized for "fetch by trace/obs" traceId traceId/obsId Same lineage as "Postgres+ClickHouse coexist" (L07): choose storage by access pattern, just finer — "one pillar, one table"
Three pillars → three tables: observation (largest, widest, most-queried), trace (list main entry), score (low volume, queried by relation) have different access patterns, so three tables each with its best ordering key/partition (L08), no mutual drag. score relates back via traceId/observationId.

How the three land in ClickHouse and sessions

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 model (TS)

domain/traces.ts
domain/observations.ts
domain/scores.ts
shape shared by frontend & backend

ClickHouse table (wide event)

0001_traces.up.sql
0002_observations.up.sql
0003_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.

🎯 Design trade-off
Why pile the "heavy" fields on the observation and keep the trace so thin? Because the vast majority of queries happen at the "step" granularity: you aggregate and filter by model, by prompt version, by tool call — dimensions that naturally belong to one step, not the whole interaction. Put them on the observation and common queries become direct column predicates over the observations wide table; the trace just keeps correlation and a few search markers. The cost is that some info (e.g. userId) may be redundant across trace and observation — exactly Lesson 2's "denormalize carefully". Read the trade the other way: Langfuse chooses to pay a little duplication so that the queries users run all day stay JOIN-free and fast. At observability scale, that trade almost always wins.
🎯 Key points
  • trace is thin: mostly identity and markers (userId/sessionId/tags/bookmarked/public); its job is to correlate.
  • observation is heavy: ObservationType has 10 values (core three SPAN/EVENT/GENERATION), builds a tree via parentObservationId, inlines model/usage/cost/prompt/tool rich attributes.
  • score has two dimensions: source (API/EVAL/ANNOTATION) × dataType (NUMERIC/CATEGORICAL/BOOLEAN/CORRECTION/TEXT); attaches to a trace or observation.
  • The three map 1:1 to three ClickHouse wide-event tables; a session strings traces via sessionId.
  • Read these three domain/*.ts schemas and you hold the key to every later feature.

🧪 Self-test - think about the design

1. Why does Langfuse put the 'heavy' fields (model/token/cost/prompt) on the observation while the trace has only identity and a few markers?
  1. Because a trace may not have any fields
  2. Because it reduces the number of SVGs
  3. Because most queries happen at the 'step' granularity (aggregate/filter by model, by prompt version); putting those dimensions on the observation makes common queries direct column predicates over the wide table, while the trace just correlates
  4. Because observations live in Postgres and traces in ClickHouse
Show answer & explanation click to expand
Answer: C. Query granularity decides where fields belong. Put the hot filter/aggregate dimensions on the observation so hot queries become column predicates without JOINs; keep the trace thin for correlation. The cost is some redundancy (e.g. userId) — exactly 'denormalize carefully'.
2. Parent-child links among observations are expressed only by a parentObservationId pointer on the child. What's the key benefit for async ingestion?
  1. Each observation carries 'who my parent is', so they can arrive independently and out of order; a child arriving before its parent is fine, and the UI rebuilds the tree from pointers at query time
  2. It stores the tree as an extra relational table
  3. It requires all observations to be written in order
  4. It lets the parent count its children in real time
Show answer & explanation click to expand
Answer: A. If the parent maintained a children list, you'd have to 'wait for all children before writing the parent' — a disaster in a high-concurrency async pipeline. Storing only the child's parent pointer fully decouples writes and allows any order, key to the ingestion path (tree rebuilt in L25).
3. Why does an observation carry both providedUsageDetails and usageDetails (and similarly for cost)?
  1. 'provided' is for the frontend, 'usage' for the backend
  2. 'provided' is what the SDK reported, 'usage' is what Langfuse computed at ingestion from model pricing; 'respect what you sent, backfill what you didn't'
  3. One stores tokens, the other money
  4. They are identical, pure redundancy
Show answer & explanation click to expand
Answer: B. Having both balances 'app precision' and 'platform backfill': if the app knows exact usage it reports it (provided); if not, Langfuse computes it from the model pricing table (computed). This 'provided wins, computed backfills' is expanded in the cost lesson (L16).
💭 Open questions (no single right answer - just think or try)
  • If you designed the score 'source' enum, would you also forbid external API callers from submitting EVAL-sourced scores like Langfuse does? Discuss what this means for trusting 'who scored'.