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

一条 trace 的一生·鸟瞰Life of a trace (bird's-eye)

🧭 读前Before you start
先读 第3课 摸清 trace / observation / score 三件套,本课才好把它们串成一条端到端流水线。
Read Lesson 3 to nail down trace / observation / score first; this lesson strings them into one end-to-end pipeline.

第一部分快收尾了。你已经知道数据长什么样(trace/observation/score)、代码住在哪(monorepo 与窄腰)、 背后的设计哲学(宽事件)。这一课把它们串成一条线:跟着一条具体的 trace,从你应用里 langfuse.trace(...) 那一刻起, 一路走到它出现在 UI 列表里、被你点开、甚至被自动评分。这是一支「预告片」——每一段路都标好了由后面哪一课详细展开,看完你就有了整张地图的行车路线。 换句话说,前四课是把零件一个个拆给你看,这一课是把它们装回去、发动一次,让你看见数据真正流动起来的样子——有了这个动态全景,再去逐课深挖每个零件,就不会只见树木不见森林。

🔌 生活类比
把一条 trace 的一生想成寄一件快递:你在家下单封箱(SDK 里创建 trace/observation);快递员上门收件,扫码入袋 (公共 API 收下事件、快速入队);包裹进了分拣中心排队,由后台分拣处理(worker 从队列取出、合并、算运费=成本); 然后上架入库(写进 ClickHouse);最后你打开手机查物流(在 UI 里看到这条 trace)。关键是——下单那一刻并不等于已入库, 中间隔着收件、分拣、上架几步,所以会有短暂的处理延迟。这正是 Langfuse 摄取「异步」的本质。
写入:SDK → … → ClickHouse(上行) 读取:ClickHouse → … → UI(下行) SDK / OTel你的应用 公共 APIweb · 校验入队 Redis 队列BullMQ worker合并·算成本 ClickHouse宽事件表 L12 L14 L15 L17 S3 / blob事件日志·媒体 L19 — — — — — 数据已落库,下面是读取 — — — — — ClickHouse同一张宽表 repository拼 SQL 查询 L22 tRPC类型安全 API L21 UI列表·详情 L20·25 上行写入异步(秒级延迟)· 下行读取实时(用户点一下就查)
一条 trace 的完整旅程:上半是写入链路(SDK→API→Redis→worker→ClickHouse,旁挂 S3),每段标了对应课号(第 12–19 课);下半是读取链路(ClickHouse→repository→tRPC→UI,第 20–27 课)。两条链路在 ClickHouse 这张宽表上「碰头」:写入把数据放进去,读取把它取出来。
写路径时序:早返回 + 异步落库 SDK web /ingestion Redis 队列 worker ClickHouse+S3 ① POST /ingestion {batch:[…]} ② 校验 + 入队 ③ 207 Multi-Status(早返回) ⟵ 异步边界:最终一致窗口(几十毫秒~几秒)⟶ ④ 取出事件 ⑤ 合并 + 批量写 ⑥ ack
写路径=一次异步握手(依据 api/public/ingestion 与 packages/shared/src/server/queues.ts):SDK 发批量事件 → web 校验并入 Redis → 立刻回 207 Multi-Status(带每事件 successes/errors,不等落库);越过异步边界后,worker 才慢慢取出、合并、写 ClickHouse+S3。所以「写完」到「查得到」之间有个最终一致窗口——这正是 trace 偶尔「刚发还看不到」的原因。

上行 · 写:从 SDK 到 ClickHouse

先看包裹「寄出到入库」的全过程。它被刻意设计成异步的——API 只负责飞快地收下并入队,真正的重活交给 worker 慢慢做:

1

SDK 创建事件(第 6 课)

你的应用调用 SDK 或发 OTel span,生成 trace-create / observation-create / score-create 等事件。

2

公共 API 收件入队(第 12·14 课)

web/src/pages/api/public/ingestion.ts 鉴权、用 Zod 校验一批事件,然后快速塞进 Redis 队列就返回——不等处理完。

3

worker 合并聚合(第 15 课)

IngestionService 从队列取出事件,从 S3 取这条记录的历史事件合并(同一个 observation 的多次 update 会合成一条),再决定最终长什么样。

4

算 token 与成本(第 16 课)

按模型名匹配定价表,把没上报的 usage/cost 兜底算出来(还记得第 3 课的 provided vs computed 吗)。

5

ClickhouseWriter 批量写(第 17 课)

把处理好的记录攒成批,一次性写进 ClickHouse 的 traces/observations/scores 表(ReplacingMergeTree 负责「同 id 后写覆盖先写」)。

这条链路里,S3 扮演了「事件原始底稿」的角色:每个进来的事件先落 S3,worker 合并时再回 S3 取历史。这样即使处理出错也能重放, 而且让「同一条 observation 的多次更新」能被正确合并——这些细节在第 15–17 课会逐一拆开。现在你只需记住这条主干:收件 → 入队 → 合并 → 算钱 → 入库。

这里要特别点出第 3 步「合并」为什么不可省。原因是:SDK 上报一个 observation 往往不是一次性的。比如一次 LLM 调用,SDK 可能先发一个 「observation-create」说「我开始了,模型是 gpt-4o」,等调用返回后再发一个「observation-update」补上「输出是 X、用了 1240 token」。这两条事件分别到达, worker 必须把它们合并成同一条最终记录。这就是为什么要回 S3 取「这个 id 的历史事件」——把先后到达的碎片拼成完整的一行。理解了这一点,你就明白第 3 课说的 「observation 靠 parentObservationId 乱序到达也没关系」是怎么在摄取里真正实现的:事件可以分多次、乱序到,worker 负责把它们收敛成一致的最终态。

分多次、乱序到达 → worker 收敛成一行最终态 事件1 observation-create{id:obs-42, 开始, model:gpt-4o} 事件2 observation-update{id:obs-42, output:X, 1240 token} 两条分别到达、可能乱序 worker 合并回 S3 取 id=obs-42 历史按 id 分组、字段取有值方冲突以更晚 timestamp 为准 一条最终行obs-42:gpt-4o + output:X+ 1240 token,写进 ClickHouse 这正是第3课「乱序到达也没关系」在摄取里的实现,也是第13/15课要细讲的合并逻辑
乱序事件 → 一条最终态:同一 observation 的 create/update 分多次、可能乱序到达;worker 回 S3 取该 id 的历史事件,按 id 分组合并(冲突以更晚 timestamp 为准),收敛成一条最终行写入 ClickHouse。细节见第 13·15 课。

下行 · 读:从 UI 回到 ClickHouse

数据落库后,你在浏览器里看到它,走的是另一条更实时的链路——你点一下,它就去查:

1

UI 发起查询(第 20 课)

你打开 trace 列表页,前端通过 tRPC 的 hook(如 api.traces.all.useQuery)发起一次类型安全的请求。

2

tRPC 鉴权分派(第 21 课)

请求进 web/src/server/api,中间件先校验「你属于这个项目吗」(RBAC),再分派到对应的路由处理函数。

3

仓储层拼查询(第 22·23 课)

路由调用 packages/shared/src/server/repositories 里的函数,把你的过滤条件翻译成 ClickHouse SQL(带时间窗口、只选需要的列)。

4

ClickHouse 返回,UI 渲染(第 24·25 课)

列表页只取紧凑的窄字段(快);你点开某条 trace 时,才去拉完整的 input/output 大字段并拼出观测树。

注意写入和读取在 ClickHouse 这张表上会师:写入链路负责把宽事件放进去,读取链路负责用各种姿势把它查出来。第 2 课说的「列表只读窄字段、详情才读大字段」, 正是在这条读取链路上落地的。

为什么要把「收件」和「处理」分开

这条链路最妙的一步,是 API「收下就返回」。它把整件事掰成了「快路」和「慢路」两半:

快路:API 毫秒级返回 慢路:worker 后台慢慢处理 你的应用等不起 公共 API只校验+入队 事件 毫秒级 200 OK(快路) Redis 队列蓄水池 worker ×N批量·可重试 慢路:洪峰先在队列排队,worker 按自己节奏消费、扛不住就加机器
一刀切开:应用和 API 之间是快路(毫秒级返回,几乎不可能慢);API 之后是慢路(入队 → worker 后台批量处理)。队列像蓄水池,洪峰来了先排队,worker 扛不住就横向加机器。

想想看:一个高流量的 LLM 应用,每秒可能产生成千上万条 observation。如果 API 必须同步地合并、算成本、写 ClickHouse 才返回,那么两件坏事会发生: 其一,你的应用每次调用都要多等这几百毫秒,平白被监控工具拖慢;其二,一旦 ClickHouse 抖动或洪峰打满,API 就会超时、甚至把错误反弹给你的业务。 把「收件」和「处理」一刀切开,API 就退化成一个极轻的「只管校验 + 入队」端点——它几乎不可能慢,也几乎不可能因为下游问题而连累你的应用。

队列则像一个蓄水池:洪峰来了先在队列里排队,worker 按自己的节奏批量消费,扛不住就加 worker(横向扩容)。 Langfuse 甚至把摄取队列分成主/次两条(第 14 课),把高吞吐的大项目和普通项目隔开,避免一个项目的洪峰拖垮所有人。 代价就是后面要说的那点延迟——但只要把 Δ 压到秒级,用户几乎无感。这也是为什么几乎所有高吞吐遥测系统(不只是 Langfuse)都长成这个样子: 轻量接收 + 异步处理 + 批量落库。看懂了这条主干,你就能预判后面第三部分每一课在解决什么问题。

异步的代价:最终一致

把上下行拼起来,有一个你必须心里有数的事实:从 SDK 发出,到 UI 能查到,中间隔着队列处理,有秒级延迟。这叫最终一致。

「最终一致」在实践中意味着什么?意味着你刚在应用里跑完一次调用、马上切到 Langfuse 界面刷新,可能还看不到它——再等一两秒、刷新一下,它就出现了。 这对绝大多数可观测场景完全够用:你是事后来排查、来看板、来评估的,差几秒无所谓。但它也提醒你两件事:第一,别拿 Langfuse 当强一致的业务数据库—— 它是遥测系统,不保证「写完立刻可读」;第二,如果你写自动化测试去验证「埋点对不对」,要记得给摄取留出处理时间,否则会误判成「数据没上来」。 理解这条边界,你就不会对那点延迟感到意外,反而会欣赏它背后「永不拖累业务」的取舍。

t0SDK 发出事件API 入队(毫秒级返回)
t0 + Δworker 排队 → 合并 → 算成本 → 写 ClickHouse
t0 + Δ′UI 才能查到这条 trace
🎯 设计取舍
为什么宁可有这点延迟,也要异步? 因为摄取要扛极高的写入吞吐,而你的应用等不起。如果 API 同步地做完合并、算成本、写库才返回, 你的每次 LLM 调用都会被 Langfuse 拖慢、还可能因为下游抖动而失败。异步把「收件」和「处理」解耦:API 永远毫秒级返回、几乎不可能拖累你的应用; worker 则能批量、可重试、按队列扩容地消化洪峰。代价就是那点处理延迟——而第 2 课提到的「保留近实时调试」原则,要求把这个 Δ 压到秒级, 让可观测性依然「几乎实时」。用一点延迟,换一个永不拖累业务、又扛得住洪峰的摄取层。 这套「轻接收 + 异步处理」的取舍,会在第三部分被你反复看到——它不是某个模块的小聪明,而是贯穿整条摄取链路的指导思想。
🎯 本课要点 · 第一部分收官
  • 一条 trace 的一生:SDK → 公共 API(入队)→ Redis → worker(合并·算成本)→ ClickHouse(写),再 UI → tRPC → repository → ClickHouse(读)。
  • 写入异步(秒级延迟、最终一致,刚埋点要稍等才可见),读取实时;两条链路在 ClickHouse 宽表上会师。
  • S3 存事件原始底稿,支撑合并与重放(出错可重来);Redis 队列解耦收件与处理、并能分主次隔离大项目。
  • 每一段路都对应后面一课:写入是第三部分(第 12–19 课),读取是第四部分(第 20–27 课)。
  • 第一部分到此结束:你已经有了数据模型 + 仓库地图 + 设计哲学 + 端到端链路这张总图,接下来就从第二部分的「前置基础」开始逐段深入。

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

1. Langfuse 的摄取为什么是异步的(API 收下就入队返回,由 worker 后台处理),而不是 API 同步写完 ClickHouse 才返回?
  1. 为了让 API 永远毫秒级返回、几乎不拖累你的应用,并能用队列做缓冲:洪峰先排队、worker 批量可重试地消费、扛不住就横向扩容
  2. 为了故意增加延迟以省钱
  3. 因为 API 不能访问数据库
  4. 因为 ClickHouse 不支持同步写入
看答案与解析 点击展开
答案:A。若 API 同步合并/算成本/写库,你每次 LLM 调用都被拖慢,且下游一抖动 API 就超时甚至把错误反弹给业务。异步把“收件”和“处理”解耦:API 极轻、几乎不可能慢;worker 批量、可重试、可扩容地消化洪峰。代价是秒级延迟(最终一致)。
2. worker 处理时为什么要回 S3 取“这个 id 的历史事件”再合并?
  1. 因为 ClickHouse 会丢数据,要从 S3 恢复
  2. 因为合并必须在前端做
  3. 因为 S3 比队列快
  4. 因为一个 observation 常被分多次、可能乱序地上报(先 create 再 update),worker 必须把这些碎片合并成一条一致的最终记录
看答案与解析 点击展开
答案:D。SDK 上报往往不是一次性的:先发 create(我开始了),调用返回后再发 update(输出/用量)。两条分别到达,worker 回 S3 取历史把碎片拼成完整一行。这也支撑了“事件可乱序到达、worker 收敛成最终态”,正是第 3 课 parentObservationId 设计的运行时体现。
3. “最终一致”对使用 Langfuse 意味着什么实践注意点?
  1. 数据永远不会出现
  2. 刚埋点的数据可能要等一两秒才在 UI 出现;别把它当强一致业务库,写自动化测试验证埋点时要给摄取留处理时间
  3. trace 会随机丢失
  4. 必须手动刷新数据库连接
看答案与解析 点击展开
答案:B。异步摄取有秒级处理延迟,对“事后排查/看板/评估”完全够用,但意味着“写完不一定立刻可读”。所以别拿它当强一致库;自动化验证埋点时要等摄取处理完,否则会误判“数据没上来”。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 回顾第一部分:用你自己的话,把“一条 trace 的一生”讲给一个没用过 Langfuse 的同事听(从 SDK 到 UI)。你觉得哪一段最容易被忽略、但其实最关键?

Part 1 is nearly done. You now know what the data looks like (trace/observation/score), where the code lives (monorepo & narrow waist), and the design philosophy behind it (wide events). This lesson strings them into one line: follow one concrete trace from the moment your app calls langfuse.trace(...) all the way to it appearing in the UI list, being opened, even being auto-scored. It's a trailer — each leg is tagged with the later lesson that covers it, so by the end you have the whole map's route plan. Put differently, the first four lessons took the parts out one by one; this one puts them back and fires the engine once, so you see the data actually flowing — with that dynamic panorama, digging into each part lesson by lesson won't lose the forest for the trees.

🔌 Analogy
Think of a trace's life as shipping a parcel: at home you place the order and seal the box (create trace/observation in the SDK); a courier picks it up, scans it into a bag (the public API accepts the events and quickly enqueues); the parcel queues in a sorting center and is processed in the back (the worker pulls from the queue, merges, computes "shipping cost" = cost); then it's shelved into the warehouse (written to ClickHouse); finally you open your phone to track it (see the trace in the UI). The key: placing the order is not the same as being shelved — pickup, sorting and shelving sit in between, so there's a brief processing delay. That's the essence of Langfuse's "async" ingestion.
Write: SDK → … → ClickHouse (top) Read: ClickHouse → … → UI (bottom) SDK / OTelyour app public APIweb · validate+enqueue Redis queueBullMQ workermerge·cost ClickHousewide-event tables L12 L14 L15 L17 S3 / blobevent log·media L19 — — — — — data is stored; below is reading — — — — — ClickHousesame wide table repositorybuild SQL L22 tRPCtype-safe API L21 UIlist·detail L20·25 writes are async (seconds of lag) · reads are real-time (one click queries)
A trace's full journey: the top half is the write path (SDK→API→Redis→worker→ClickHouse, with S3 alongside), each leg tagged with its lesson (L12–19); the bottom half is the read path (ClickHouse→repository→tRPC→UI, L20–27). The two paths "meet" at the ClickHouse wide table: writes put data in, reads take it out.
Write-path sequence: early return + async persist SDK web /ingestion Redis queue worker ClickHouse+S3 ① POST /ingestion {batch:[…]} ② validate + enqueue ③ 207 Multi-Status (early return) ⟵ async boundary: eventual-consistency window (tens of ms ~ seconds) ⟶ ④ dequeue ⑤ merge + batch write ⑥ ack
The write path is one async handshake (per api/public/ingestion and packages/shared/src/server/queues.ts): SDK sends a batch → web validates and enqueues to Redis → returns 207 Multi-Status immediately (with per-event successes/errors, not waiting for persistence); only across the async boundary does the worker dequeue, merge and write ClickHouse+S3. So between "written" and "queryable" there is an eventual-consistency window — exactly why a just-sent trace is sometimes not visible yet.

Top half · write: SDK to ClickHouse

First the parcel's "shipped to shelved" journey. It's deliberately async — the API only accepts and enqueues fast, leaving the heavy lifting to the worker:

1

SDK creates events (L06)

Your app calls the SDK or emits an OTel span, producing events like trace-create / observation-create / score-create.

2

Public API accepts & enqueues (L12·14)

web/src/pages/api/public/ingestion.ts authenticates, Zod-validates a batch, then quickly drops it into the Redis queue and returns — without waiting for processing.

3

worker merges & aggregates (L15)

IngestionService pulls events from the queue, fetches this record's prior events from S3 and merges (multiple updates to one observation fold into one), deciding the final shape.

4

compute token & cost (L16)

Match the model name to the pricing table and backfill any unreported usage/cost (remember provided vs computed from L03?).

5

ClickhouseWriter batches the write (L17)

Batch processed records and write them to ClickHouse traces/observations/scores in one go (ReplacingMergeTree handles "later write of same id wins").

In this path, S3 plays "the raw event manuscript": each incoming event lands in S3 first, and the worker re-reads S3 when merging. That allows replay on failure and lets "multiple updates to one observation" merge correctly — details unpacked in L15–17. For now, remember the spine: accept → enqueue → merge → cost → store.

It's worth calling out why step 3, "merge", can't be skipped. The reason: an SDK often reports one observation not all at once. For an LLM call, the SDK might first send an "observation-create" saying "I started, model is gpt-4o", then after the call returns send an "observation-update" adding "output is X, used 1240 tokens". Those two events arrive separately, and the worker must merge them into one final record. That's why it re-reads S3 for "this id's prior events" — stitching the fragments that arrived at different times into one complete row. Grasp this and you see how Lesson 3's "observations can arrive out of order via parentObservationId" is actually realized in ingestion: events may come in multiple pieces, out of order, and the worker converges them into a consistent final state.

Arrive in pieces, out of order → worker converges to one final row event1 observation-create{id:obs-42, started, model:gpt-4o} event2 observation-update{id:obs-42, output:X, 1240 tokens} arrive separately, possibly out of order worker mergesfetch id=obs-42 history from S3group by id, each field takes the value sideconflicts: later timestamp wins one final rowobs-42: gpt-4o + output:X+ 1240 tokens, written to ClickHouse This is exactly how Lesson 3's "out-of-order arrival is fine" is realized in ingestion, and the merge logic Lessons 13/15 detail
Out-of-order events → one final state: the same observation's create/update arrive in multiple pieces, possibly out of order; the worker fetches that id's history from S3, groups and merges by id (conflicts resolved by the later timestamp), converging into one final row written to ClickHouse. Details in Lessons 13·15.

Bottom half · read: from UI back to ClickHouse

Once stored, seeing it in your browser takes a different, more real-time path — you click, it queries:

1

UI issues a query (L20)

You open the trace list; the frontend issues a type-safe request via a tRPC hook (e.g. api.traces.all.useQuery).

2

tRPC auth & dispatch (L21)

The request hits web/src/server/api; middleware first checks "do you belong to this project" (RBAC), then dispatches to the right router handler.

3

repository builds the query (L22·23)

The handler calls functions in packages/shared/src/server/repositories, translating your filters into ClickHouse SQL (with time windows, selecting only the needed columns).

4

ClickHouse returns; UI renders (L24·25)

The list reads only compact narrow fields (fast); only when you open a trace does it fetch the full input/output and build the observation tree.

Note that write and read converge on this one ClickHouse table: writes put the wide event in, reads pull it out every which way. Lesson 2's "lists read narrow fields, detail reads big fields" is realized on exactly this read path.

Why separate "accept" from "process"

The cleverest step in this path is the API "accept and return". It splits the whole thing into a "fast lane" and a "slow lane":

Fast lane: API returns in ms Slow lane: worker processes in background your appcan't wait public APIvalidate+enqueue only events 200 OK in ms (fast lane) Redis queuereservoir worker ×Nbatch·retryable slow lane: spikes queue up; the worker consumes at its own pace, scale out if overwhelmed
One clean cut: between app and API is the fast lane (returns in ms, almost never slow); after the API is the slow lane (enqueue → worker batches in the background). The queue is a reservoir: spikes queue up, and you add workers when overwhelmed.

Consider: a high-traffic LLM app may produce thousands of observations per second. If the API had to synchronously merge, compute cost and write ClickHouse before returning, two bad things happen: one, every app call waits those extra hundreds of ms, needlessly slowed by your monitoring tool; two, if ClickHouse hiccups or a spike maxes it out, the API times out and even bounces errors back into your business. Cutting "accept" from "process" reduces the API to a featherweight "validate + enqueue" endpoint — almost impossible to slow, almost impossible to drag your app down via a downstream issue.

The queue is a reservoir: spikes queue up, the worker consumes in batches at its own pace, and you add workers (scale out) when it can't keep up. Langfuse even splits the ingestion queue into primary/secondary lanes (L14), isolating high-throughput big projects from ordinary ones so one project's spike can't drown everyone. The cost is the bit of lag mentioned next — but keep Δ to seconds and users barely notice. This is why nearly every high-throughput telemetry system (not just Langfuse) looks like this: lightweight accept + async process + batched store. Grasp this spine and you can predict what each Part 3 lesson is solving.

The cost of async: eventual consistency

Stitch the halves together and one fact must be clear in your mind: from SDK send to UI visibility there's queue processing in between, a few seconds of lag. This is eventual consistency.

What does "eventual consistency" mean in practice? It means that right after a call runs in your app, if you immediately switch to the Langfuse UI and refresh, you might not see it yet — wait a second or two, refresh, and it appears. For almost all observability use this is perfectly fine: you come after the fact to triage, view dashboards, evaluate — a few seconds don't matter. But it flags two things: first, don't treat Langfuse as a strongly-consistent business database — it's a telemetry system, not a "write-then-read-immediately" store; second, if you write automated tests to verify "is instrumentation correct", remember to allow ingestion time to process, or you'll falsely conclude "the data never arrived". Understand this boundary and the lag won't surprise you — you'll appreciate the "never drag the business" trade behind it.

t0SDK sends eventsAPI enqueues (returns in ms)
t0 + Δworker queues → merge → cost → write ClickHouse
t0 + Δ′only now can the UI query this trace
🎯 Design trade-off
Why tolerate that lag and go async? Because ingestion must absorb very high write throughput while your app can't afford to wait. If the API synchronously merged, computed cost and wrote before returning, every LLM call would be slowed by Langfuse and could fail on downstream hiccups. Async decouples "accept" from "process": the API always returns in milliseconds and almost never drags your app; the worker can digest spikes in batches, retryably, scaling by queue. The cost is that bit of processing lag — and Lesson 2's "preserve near-real-time debugging" principle demands keeping Δ to seconds so observability stays "almost live". Trade a little lag for an ingestion layer that never drags the business and survives spikes. This "lightweight accept + async process" trade recurs throughout Part 3 — it's not one module's trick but the guiding idea across the whole ingestion path.
🎯 Key points · Part 1 wrap-up
  • A trace's life: SDK → public API (enqueue) → Redis → worker (merge·cost) → ClickHouse (write), then UI → tRPC → repository → ClickHouse (read).
  • Writes are async (seconds of lag, eventual consistency), reads are real-time; the two paths converge on the ClickHouse wide table.
  • S3 stores the raw event manuscript for merge and replay; the Redis queue decouples accept from process.
  • Every leg maps to a later lesson: writing is Part 3 (L12–19), reading is Part 4 (L20–27).
  • Part 1 ends here: you now hold the master map — data model + repo map + design philosophy + end-to-end path — and we dive in leg by leg next.

🧪 Self-test - think about the design

1. Why is Langfuse ingestion async (the API enqueues and returns, the worker processes in the background) rather than the API synchronously writing ClickHouse before returning?
  1. So the API always returns in ms and barely drags your app, and the queue buffers: spikes queue up, the worker consumes in batches retryably, and you scale out when overwhelmed
  2. To deliberately add latency to save money
  3. Because the API cannot access the database
  4. Because ClickHouse doesn't support synchronous writes
Show answer & explanation click to expand
Answer: A. If the API synchronously merged/costed/wrote, every LLM call is slowed and a downstream hiccup times out the API or bounces errors into your business. Async decouples accept from process: the API is featherweight and rarely slow; the worker digests spikes in batches, retryably, scalably. The cost is seconds of lag (eventual consistency).
2. Why does the worker re-read 'this id's prior events' from S3 and merge during processing?
  1. Because ClickHouse loses data and must restore from S3
  2. Because merging must happen in the frontend
  3. Because S3 is faster than the queue
  4. Because one observation is often reported in multiple, possibly out-of-order events (create then update), and the worker must merge these fragments into one consistent final record
Show answer & explanation click to expand
Answer: D. SDK reporting often isn't one-shot: a create ('I started') then an update ('output/usage') after the call returns. They arrive separately; the worker re-reads S3 to stitch the fragments into one row. This supports 'events arrive out of order, worker converges to final state' — the runtime realization of L03's parentObservationId design.
3. What practical caveat does 'eventual consistency' imply when using Langfuse?
  1. Data will never appear
  2. Just-instrumented data may take a second or two to appear in the UI; don't treat it as a strongly-consistent business DB, and when testing instrumentation, allow ingestion time to process
  3. Traces are randomly lost
  4. You must manually refresh the DB connection
Show answer & explanation click to expand
Answer: B. Async ingestion has seconds of processing lag — fine for after-the-fact triage/dashboards/eval, but it means 'written isn't instantly readable'. So don't treat it as a strongly-consistent store; when verifying instrumentation in tests, wait for ingestion or you'll falsely conclude 'no data arrived'.
💭 Open questions (no single right answer - just think or try)
  • Recap Part 1: in your own words, tell a colleague who's never used Langfuse the 'life of a trace' from SDK to UI. Which leg do you think is most overlooked yet most crucial?