🪢 Langfuse 图解教程Langfuse Visual Guide 第四部分 · 查询链路Part 4 · The Read Path 25 / 55
第四部分 · 查询链路Part 4 · The Read Path

trace 详情与观测树Trace detail & the observation tree

🧭 读前Before you start
先读 第3课 的 observation 树与 第19课 的媒体存储,本课讲 trace 详情页怎么拼出来。
Read Lesson 3 (the observation tree) and Lesson 19 (media storage); this lesson covers how the trace detail page is assembled.

第 24 课是列表——给几千条 trace 各取一行紧凑数据、把昂贵的都推迟。这一课是它的反面:详情页。点开一条 trace,你要看的是整棵观测树 + 所有评分—— 一次全量取。为什么敢全取?因为「一条 trace」本身是有界的(不是几千条的列表)。但树里每个观测的 input/output 可能巨大,所以详情依然有纪律: 树查询不带 IO(点开某节点才懒加载),再用一个 verbosity 旋钮给 trace 自身的 IO 封顶。同一套「限制无界维度」的功夫,换了个尺度施展。

📖 生活类比
把列表和详情想成图书馆目录与一本书。目录(列表)给你几千本书的小卡片,谁也不会把整本书抄上去。可当你抽出某一本(详情), 你要的是整本书的结构——目录、章节、页码一览无余。但你不会一上来就把每一页的长篇脚注全复印下来;只有翻到某页、想细看时,才去读那条脚注(某个观测的 IO 懒加载)。 「整本书的骨架一次给全,单页的长内容用到才取」——这就是详情页在「全量」与「克制」之间的平衡。

一次取全树,但树上不挂 IO

详情页的主查询是 byIdWithObservationsAndScores。它跑在 protectedGetTraceProcedure 上——这道门(第 21 课)已经预取了 trace 本体并校验过访问权(还允许公开分享的 trace)。 然后它并行取两样:整棵观测树和这条 trace 的全部评分:

详情:一次取全树(结构+时序),IO 留到点开再取 门已预取 traceprotectedGetTraceProcedure校验访问权(含公开) getObservationsForTrace(树) getScoresAndCorrections(评分) ↑ Promise.all 并行 ↑ 组装partition 出 CORRECTION从起止派生 latency观测 IO 置空includeIO:false 返回:树 + 评分结构、时序,无 IO 点开某节点 →懒加载该观测 IO 一棵观测树(结构与时序): ▸ trace▸ span: 检索• generation: LLM 调用(IO 点开才取)右侧:getAgentGraphData → agent 图视图
取全骨架、缓取血肉:byIdWithObservationsAndScores 并行取观测树(includeIO:false)与评分,partition 出 CORRECTION 类分数、从观测起止派生 latency,返回不含 IO 的树;点开某节点才懒加载它的 IO。另有 getAgentGraphData 供 agent 图。源码:web/src/server/api/routers/traces.ts:368,610。
示例:span 瀑布——按时间看一条 trace 0s~2.5s → agent-run (SPAN) 2.4s retrieve (SPAN) 120ms plan (GEN gpt-4o) 0.6s tool: search (SPAN) 340ms summarize (GEN) 1.8s 红框=关键路径:plan→summarize 两次 generation 串行,占了大半时长
瀑布图把「时间」画出来(基于 observation 的 start_time/end_time;值为示例):每条横条按 start_time 左右偏移、按 latency 定宽,父子用缩进表示嵌套。一眼就能看出谁在等谁、哪步最慢——这里 plan 与 summarize 两次 generation 串行占了大半时长(关键路径)。这是 trace 详情页最有价值的一张图。
web/src/server/api/routers/traces.tsbyIdWithObservationsAndScores :368
// ctx.trace 已由门预取(含权限校验);并行取树与评分
const [observations, traceScores] = await Promise.all([
  getObservationsForTrace({ traceId, projectId, includeIO: false }), // 树不带 IO
  getScoresAndCorrectionsForTraces({ projectId, traceIds: [traceId] }),
]);
// CORRECTION 类分数单独分出来
const [corrections, scores] = partition(scores, (s) => s.dataType === "CORRECTION");
// 从观测的最早起、最晚止派生整条 trace 的延迟
const latencyMs = maxEnd - minStart;
return { ...trace, observations: obs.map((o) => ({ ...o, input: undefined, output: undefined })) };

注意 includeIO: false 这个不起眼的参数——它是详情页性能的关键。设想一条 agent trace 有三百个观测,每个观测的 input/output 又是一段不短的 JSON: 如果开树时就把全部 IO 一并拉回,光这一个请求就可能是几十 MB、几秒钟。Langfuse 的选择是树先到、IO 后取:

整条 trace 的延迟:从观测的最早起、最晚止派生(不单独存) 时间 → span: 检索 generation: LLM 调用 tool: 调外部 API span: 汇总 minStart maxEnd latencyMs = maxEnd − minStart(派生口径,永远和观测一致)

😖 树带全 IO

一次拉回三百个观测 + 它们的全部 IO,请求几十 MB、慢且占内存。可你打开详情时,大多数节点你压根不会展开——绝大部分 IO 是白拉的。

😀 树先到,IO 懒加载

树查询只带结构与时序(轻、快),整棵树立刻可见;你点开哪个观测,才去取那一个的 IO。按需付费,绝不为没看的节点买单——这也让超大 trace 的详情页依然能秒开。

verbosity 旋钮:给「巨型 trace」的 IO 封顶

就算是一条 trace,它自身的 input/output 也可能是个几 MB 的大 JSON(比如塞了整段长上下文)。为此,单条 trace 的查询 byId 带一个 verbosity 参数(compact / truncated / full), 在服务端就决定 IO 要不要解析、要不要截断——别让一个超大 trace 把响应撑爆:

为什么要在服务端而不是前端截断?因为等数据传到前端再裁,已经晚了——那几 MB 已经从 ClickHouse 读出、序列化、走完网络。verbosity 让裁剪发生在最靠近数据源的地方: 该不带 IO 的(compact)压根不取,该截断的(truncated)在序列化前就截短,只有明确要看全(full)才完整返回。同一个 byId 接口,因此能既服务「列表里要个轻量预览」又服务「详情页要看全文」,靠一个参数切换姿态。

verbosity:在服务端就给 IO 定档 compact不带 IO,最轻列表/概览场景载荷最小 truncatedIO 截断到上限巨型 trace 也不撑爆够看个大概 full(默认)完整 IO单条详情、要看全载荷最大
三档封顶:byId 的 verbosity(compact / truncated / full,默认 full)在服务端决定 trace 自身 IO 是否解析/截断,给超大 trace 的响应封顶。源码:web/src/server/api/trpc.ts:480,524-525(parseIO(input, verbosity))。

从用户视角看,打开一条 trace 详情的完整体验是这样五步——树几乎瞬间出现,细节随你的点击逐步充实:

1

进门预取 + 校验

protectedGetTraceProcedure 已把 trace 本体取好、并确认你有权访问(公开分享的 trace 也放行)。

2

并行取树与评分

Promise.all 同时拉观测树(不带 IO)与全部评分,两者谁慢等谁、但一起发出。

3

组装并渲染骨架

partition 出 CORRECTION、派生 latency,整棵观测树的结构与时序立刻画出——你马上能看清这次调用的全貌。

4

点开节点,懒加载 IO

你点某个 generation 想看它的 prompt/completion,前端才去取那一个观测的 IO,按 verbosity 决定完整还是截断。

5

(可选)切到 agent 图

想看 agent 的步骤拓扑?getAgentGraphData 另起一路,把这棵树渲染成一张有向图(trace-graph-view),让多步 agent 的调用关系一眼看清。

把第 24、25 两课摆在一起,「同一套纪律、两个尺度」就一目了然了——无论列表还是详情,都先圈定有界的维度、把无界的维度往后推:

列表(第 24 课)详情(本课)
有界的,先取几千条 trace 的紧凑行(每条 ~12 列)一条 trace 的整棵观测树(结构+时序)
无界的,缓取成本/延迟/评分指标(要 JOIN)→ 并行后到每个观测的 IO(可能巨大)→ 点开懒加载
封顶手段分页、回看时间窗、按需 FINAL/JOIN树查询不带 IO、verbosity 截断 trace 自身 IO
🎯 设计取舍
为什么详情敢「一次取全树」,列表却要「极力推迟」? 关键在有界性。列表面对的是无界的行数(几千、几万条 trace),所以连一行里稍贵的列都得推迟; 详情面对的是一条 trace——它的观测数量再多也是有界的,而且「看清这一条的全貌」正是详情页的价值,所以结构与时序值得一次取全。 但有界的实体里仍藏着无界的维度:单个观测的 IO 可以是 2MB 的 JSON,几百个观测叠起来又会爆。于是同一套「圈定有界、推迟无界」的纪律下沉到树内部—— 树取全(有界的结构),IO 缓取(无界的内容),再用 verbosity 给 trace 自身 IO 封顶。不是「列表克制、详情放纵」,而是两者都在各自的尺度上做同一件事:只急着取你扛得住的那部分。
🎯 本课要点
  • 详情页主查询 byIdWithObservationsAndScores 跑在 protectedGetTraceProcedure 上(门已预取 trace 并校验访问权,含公开分享)。
  • 并行取观测树 + 评分;partition 出 CORRECTION 类分数;从观测起止派生 latency。
  • 树不带 IO(includeIO:false,观测 input/output 置空)——点开某节点才懒加载它的 IO,避免一次拉几百个观测的巨型内容、让超大 trace 详情也能秒开。
  • verbosity(compact / truncated / full)在服务端给 trace 自身 IO 定档/截断,防超大 trace 撑爆响应。另有 getAgentGraphData 供 agent 图视图。
  • 与第 24 课「同一纪律、两个尺度」:先取有界维度(列表=紧凑行 / 详情=树结构),推迟无界维度(列表=指标 / 详情=观测 IO)——只急着取你扛得住的那部分。

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

1. 详情页要看一条 trace 的整棵观测树,可 byIdWithObservationsAndScores 取观测时却传 includeIO:false(不带 input/output)。为什么?
  1. 为了隐藏 IO 不让用户看
  2. 因为 IO 存在另一个数据库
  3. 因为观测没有 IO 字段
  4. 树查询只带结构与时序(轻、快),整棵树立刻可见;某个观测的 IO 可能是几 MB JSON、几百个叠起来会爆,所以点开哪个节点才懒加载那一个的 IO——按需付费,不为没看的节点买单
看答案与解析 点击展开
答案:D。一条 agent trace 可能有几百个观测,每个 IO 是不短的 JSON。开树就拉全部 IO 会是几十 MB、好几秒,而你大多数节点根本不展开——白拉。Langfuse 让树先到(结构+时序)、IO 点开懒加载,于是超大 trace 详情也能秒开。
2. 第 24 课列表「极力推迟」、第 25 课详情「一次取全树」,看似相反。它们其实遵循同一条原则,是哪条?
  1. 列表用 ClickHouse、详情用 Postgres
  2. 先取有界的维度、推迟无界的维度:列表面对无界行数→连稍贵的列都推迟;详情面对一条 trace(观测数有界)→结构取全,但树内单个观测 IO 仍是无界维度→懒加载。只急着取你扛得住的那部分
  3. 都尽量多取数据
  4. 都尽量少取数据
看答案与解析 点击展开
答案:B。关键是有界性。列表的行数无界(几千几万),故连一行里稍贵的指标都推迟;详情面对一条 trace,观测数虽多但有界,且看全这一条正是详情价值,故结构与时序一次取全。但有界实体内仍藏无界维度(单观测 IO),于是同一纪律下沉到树内:树取全、IO 缓取、verbosity 封顶。
3. byId 接口带一个 verbosity 参数(compact/truncated/full),在服务端决定 trace 自身 IO 是否解析/截断。为什么要在服务端而不是前端做这个截断?
  1. 前端不能截断字符串
  2. 因为服务端更安全
  3. 为了让前端代码更简单
  4. 等数据传到前端再裁已经晚了——那几 MB 已从 ClickHouse 读出、序列化、走完网络。verbosity 让裁剪发生在最靠近数据源处:compact 压根不取、truncated 序列化前截短、full 才完整返回
看答案与解析 点击展开
答案:D。截断的目的是省「读取+序列化+传输」的成本;这些成本在数据离开 ClickHouse 时就已发生,到前端再裁只是徒劳。verbosity 在服务端、最靠近数据源处定档:compact 不取 IO、truncated 序列化前截短、full 完整。于是同一个 byId 既能给列表轻量预览、又能给详情看全文。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 「圈定有界维度先取、推迟无界维度」——这条原则你能用到自己做的「列表 + 详情」界面吗?想想你的实体里哪些维度是有界的(适合一次取)、哪些是无界的(该懒加载或封顶)?你会在哪一层、用什么手段给无界维度封顶?

Lesson 24 was the list — fetch one compact row each for thousands of traces, defer everything expensive. This lesson is its opposite: the detail page. Open one trace and you want the whole observation tree + all scores — one full fetch. Why dare to fetch it all? Because "one trace" is bounded (not a list of thousands). But each observation's input/output in the tree could be huge, so the detail still has discipline: the tree query carries no IO (lazy-loaded per node when you expand it), with a verbosity knob capping the trace's own IO. The same "bound the unbounded dimension" craft, applied at a different scale.

📖 Analogy
Think of list vs detail as a library catalog vs one book. The catalog (list) gives you tiny cards for thousands of books — nobody transcribes a whole book onto a card. But when you pull one book (detail), you want the whole book's structure — table of contents, chapters, page numbers at a glance. Yet you don't photocopy every page's long footnotes upfront; only when you flip to a page and want the detail do you read that footnote (an observation's IO, lazy-loaded). "The whole book's skeleton at once, a page's long content fetched on demand" — that's the detail page's balance between "complete" and "restraint".

Fetch the whole tree at once, but hang no IO on it

The detail page's main query is byIdWithObservationsAndScores. It runs on protectedGetTraceProcedure — that door (Lesson 21) has already prefetched the trace itself and verified access (allowing publicly shared traces too). It then fetches two things in parallel: the whole observation tree and all of this trace's scores:

Detail: fetch the whole tree (structure+timing), IO on click door prefetched traceprotectedGetTraceProcedureaccess verified (incl. public) getObservationsForTrace (tree) getScoresAndCorrections (scores) ↑ Promise.all parallel ↑ assemblepartition out CORRECTIONderive latency from spansstrip observation IOincludeIO:false return: tree + scoresstructure, timing, no IO open a node →lazy-load that IO one observation tree (structure & timing): ▸ trace▸ span: retrieval• generation: LLM call (IO fetched on click)right: getAgentGraphData → agent graph view
Fetch the skeleton, defer the flesh: byIdWithObservationsAndScores fetches the observation tree (includeIO:false) and scores in parallel, partitions out CORRECTION-type scores, derives latency from observation start/end, returns the IO-less tree; opening a node lazy-loads its IO. Plus getAgentGraphData for the agent graph. Source: web/src/server/api/routers/traces.ts:368,610.
Example: a span waterfall — a trace over time 0s~2.5s → agent-run (SPAN) 2.4s retrieve (SPAN) 120ms plan (GEN gpt-4o) 0.6s tool: search (SPAN) 340ms summarize (GEN) 1.8s red box = critical path: the two serial generations plan→summarize dominate the duration
The waterfall draws "time" (based on observation start_time/end_time; values illustrative): each bar is offset by start_time and sized by latency, with indentation for nesting. At a glance you see who waits on whom and which step is slowest — here the two serial generations plan and summarize dominate the duration (the critical path). This is the trace detail page's most valuable figure.
web/src/server/api/routers/traces.tsbyIdWithObservationsAndScores :368
// ctx.trace prefetched by the door (with access check); fetch tree & scores in parallel
const [observations, traceScores] = await Promise.all([
  getObservationsForTrace({ traceId, projectId, includeIO: false }), // tree without IO
  getScoresAndCorrectionsForTraces({ projectId, traceIds: [traceId] }),
]);
// split out CORRECTION-type scores
const [corrections, scores] = partition(scores, (s) => s.dataType === "CORRECTION");
// derive the whole trace's latency from earliest start, latest end of observations
const latencyMs = maxEnd - minStart;
return { ...trace, observations: obs.map((o) => ({ ...o, input: undefined, output: undefined })) };

Note the unremarkable includeIO: false — it's the key to the detail page's performance. Imagine an agent trace with three hundred observations, each observation's input/output a sizeable JSON: load all the IO when opening the tree and that one request could be tens of MB and several seconds. Langfuse's choice is tree first, IO later:

the trace's latency is derived from the observations' earliest start and latest end (not stored) time → span: retrieve generation: LLM call tool: external API span: summarize minStart maxEnd latencyMs = maxEnd − minStart (derived, always consistent with the observations)

😖 tree with all IO

Fetch three hundred observations + all their IO at once: a tens-of-MB request, slow and memory-heavy. But when you open the detail, you won't expand most nodes — most of that IO was fetched for nothing.

😀 tree first, IO lazy

The tree query carries only structure and timing (light, fast), so the whole tree is visible immediately; expand an observation and only that one's IO is fetched. Pay on demand, never for nodes you didn't look at — so even a huge trace's detail page opens instantly.

The verbosity knob: capping IO for "giant traces"

Even one trace's own input/output could be a multi-MB JSON (say, stuffed with a long context). For this, the single-trace query byId carries a verbosity param (compact / truncated / full) that decides server-side whether IO is parsed or truncated — don't let a giant trace blow up the response:

Why truncate server-side, not on the frontend? Because trimming after the data reaches the frontend is too late — those few MB already got read from ClickHouse, serialized, and crossed the network. verbosity puts the trimming closest to the data source: what should carry no IO (compact) isn't fetched at all, what should be truncated (truncated) is cut before serialization, and only an explicit "show all" (full) returns the whole thing. So one byId endpoint serves both "a lightweight preview in a list" and "see the full text on a detail page", switching posture by a single parameter.

verbosity: tier the IO server-side compactno IO, lightestlist/overview casessmallest payload truncatedIO cut to a capgiant traces don't blow upenough for the gist full (default)complete IOsingle detail, see it alllargest payload
Three-tier cap: byId's verbosity (compact / truncated / full, default full) decides server-side whether the trace's own IO is parsed/truncated, capping the response for huge traces. Source: web/src/server/api/trpc.ts:480,524-525 (parseIO(input, verbosity)).

From the user's view, opening a trace detail is five steps — the tree appears almost instantly, details fill in as you click:

1

door prefetch + verify

protectedGetTraceProcedure has already fetched the trace and confirmed your access (publicly shared traces pass too).

2

parallel fetch tree & scores

Promise.all pulls the observation tree (no IO) and all scores at once — both fired together, wait for the slower.

3

assemble & render skeleton

Partition out CORRECTION, derive latency, and the tree's structure and timing paint immediately — you see the whole call at once.

4

open a node, lazy-load IO

Click a generation to see its prompt/completion and the frontend fetches that one observation's IO, full or truncated per verbosity.

5

(optional) switch to the agent graph

Want the agent's step topology? getAgentGraphData takes another path, rendering the tree as a directed graph (trace-graph-view).

Place Lessons 24 and 25 side by side and "one discipline, two scales" is plain — whether list or detail, fence the bounded dimension first and defer the unbounded one:

list (Lesson 24)detail (this lesson)
bounded — fetch firstthousands of traces' compact rows (~12 cols each)one trace's whole observation tree (structure+timing)
unbounded — defercost/latency/score metrics (need JOINs) → parallel, latereach observation's IO (possibly huge) → lazy-load on click
capping meanspagination, look-back windows, conditional FINAL/JOINtree query without IO, verbosity truncating the trace's own IO
🎯 Design trade-off
Why does detail dare to "fetch the whole tree", while the list "defers aggressively"? The key is boundedness. The list faces an unbounded number of rows (thousands, tens of thousands of traces), so even a slightly pricey column per row must be deferred; the detail faces one trace — however many observations it has, that count is bounded, and "seeing this one in full" is precisely the detail page's value, so the structure and timing are worth fetching all at once. But a bounded entity still hides an unbounded dimension inside: a single observation's IO can be a 2MB JSON, and hundreds stacked up explode again. So the same "fence the bounded, defer the unbounded" discipline descends into the tree — fetch the tree in full (the bounded structure), defer the IO (the unbounded content), and cap the trace's own IO with verbosity. It's not "list restrained, detail indulgent"; both do the same thing at their own scale: only rush to fetch the part you can bear.
🎯 Key points
  • The detail page's main query byIdWithObservationsAndScores runs on protectedGetTraceProcedure (the door prefetched the trace and verified access, including public shares).
  • Parallel fetch of the observation tree + scores; partition out CORRECTION-type scores; derive latency from observation start/end.
  • Tree without IO (includeIO:false, observation input/output stripped) — opening a node lazy-loads its IO, avoiding pulling hundreds of observations' huge content at once.
  • verbosity (compact / truncated / full) tiers/truncates the trace's own IO server-side, preventing huge traces from blowing up the response. Plus getAgentGraphData for the agent graph view.
  • With Lesson 24, "one discipline, two scales": fetch the bounded dimension first (list=compact rows / detail=tree structure), defer the unbounded one (list=metrics / detail=observation IO) — only rush to fetch the part you can bear.

🧪 Self-test - think about the design

1. The detail page shows a trace's whole observation tree, yet byIdWithObservationsAndScores fetches observations with includeIO:false (no input/output). Why?
  1. to hide IO from users
  2. because IO lives in another database
  3. because observations have no IO fields
  4. the tree query carries only structure and timing (light, fast) so the whole tree shows instantly; one observation's IO can be a multi-MB JSON and hundreds explode, so only opening a node lazy-loads that one's IO — pay on demand, never for nodes you didn't look at
Show answer & explanation click to expand
Answer: D. An agent trace may have hundreds of observations, each IO a sizeable JSON. Loading all IO when opening the tree would be tens of MB and seconds, yet you won't expand most nodes — wasted. Langfuse sends the tree first (structure+timing) and lazy-loads IO on click, so even a huge trace's detail opens instantly.
2. Lesson 24's list 'defers aggressively' while Lesson 25's detail 'fetches the whole tree' — seemingly opposite. What single principle do they share?
  1. list uses ClickHouse, detail uses Postgres
  2. fetch the bounded dimension first, defer the unbounded one: the list faces unbounded rows → defer even slightly pricey columns; the detail faces one trace (bounded observation count) → fetch structure in full, but a single observation's IO is still an unbounded dimension within → lazy-load. Only rush to fetch the part you can bear
  3. both fetch as much data as possible
  4. both fetch as little data as possible
Show answer & explanation click to expand
Answer: B. The key is boundedness. The list's row count is unbounded (thousands+), so even per-row metrics are deferred; the detail faces one trace whose observation count, though large, is bounded, and seeing this one in full is the detail's value, so structure and timing are fetched at once. But a bounded entity hides an unbounded dimension (per-observation IO), so the same discipline descends into the tree: fetch the tree, defer IO, cap with verbosity.
3. byId carries a verbosity param (compact/truncated/full) deciding server-side whether the trace's own IO is parsed/truncated. Why truncate server-side rather than on the frontend?
  1. the frontend can't truncate strings
  2. because the server is more secure
  3. to simplify frontend code
  4. trimming after data reaches the frontend is too late — those MB already got read from ClickHouse, serialized, crossed the network. verbosity puts trimming closest to the source: compact doesn't fetch, truncated cuts before serialization, only full returns it whole
Show answer & explanation click to expand
Answer: D. Truncation aims to save 'read+serialize+transfer' cost; those costs already happen as data leaves ClickHouse, so trimming at the frontend is futile. verbosity tiers server-side, closest to the source: compact fetches no IO, truncated cuts before serialization, full returns whole. So one byId serves both a list's lightweight preview and a detail's full text.
💭 Open questions (no single right answer - just think or try)
  • 'Fence the bounded dimension and fetch it first, defer the unbounded one' — can you apply this to your own 'list + detail' UIs? Which dimensions of your entities are bounded (fetch at once) and which unbounded (lazy-load or cap)? At which layer and by what means would you cap the unbounded ones?