第 24、25 课讲的是单条 trace 的列表与详情。可真实的对话往往是多轮的——用户问一句、AI 答一句,来回十几轮,每一轮是一条 trace。把它们串成一段完整对话的,就是
session(会话)。这一课的关键洞察出奇地简洁:会话的全部「指标与列表」都不单独存储,而是 traces 按 session_id 的一次「分组聚合」现算出来
(仅有一个极轻的元数据存根落库,下面会讲)。更妙的是,会话表几乎原样复用了第 24 课那套表格机制——说白了,它就是 trace 表,分了个组。
回想第 8 课:session_id 只是 traces 宽表上的一个普通列。所以会话的指标与列表不必单独存——只要把同一个 session_id 的 traces GROUP BY 聚到一起,
就得到一行「会话」,它的各项指标都是对组内 traces 的聚合:
session_id 的 traces 经 GROUP BY session_id 聚成一行会话;各指标是对组内 traces 的聚合——user_ids(去重谁参与)、trace_count(计数)、duration(最晚 − 最早)、session_total_cost(求和)。源码:packages/shared/src/server/services/sessions-ui-table-service.ts:86,123。traces 的 sessionId;值为示例):每一轮用户问答是一条独立 trace,它们共享一个 sessionId,于是能按时间排成一条对话泳道。这样既能单看某轮的细节(钻进 trace 看第 25 课的瀑布),又能整体看一次会话的时长、轮数、平均分。// 和第 24 课的 getTracesTableGeneric 同一个套路:一个函数,几种「形状」(会话用 count/rows/metrics 三种) const getSessionsTableGeneric = async <T>(props: { select: "count" | "rows" | "metrics" }) => { switch (select) { case "rows": sqlSelect = "session_id, min/max_timestamp, trace_ids, user_ids, trace_count …"; // 便宜 case "metrics": sqlSelect = "… + duration, total_observations, session_total_cost …"; // 要算 } // 底层就是对 traces(及其 observations 求成本)GROUP BY session_id }
这里有个值得留意的细节:会话的「总成本」并不直接长在 trace 上,而是要下钻到每条 trace 的 observations去求和(成本是第 16 课在 observation 上算出来的)。
所以一个会话的总成本,本质是「这个会话里所有 trace 的所有 observation 的成本」之和——一个两层的聚合。这也是为什么 session_total_cost 属于「贵」的 metrics 形状、要后补:
它和第 24 课列表里的成本指标一样,得跨表算。而便宜的 rows 形状只取会话身份(谁、几轮、哪些 trace_id),不碰成本,于是会话列表能先秒开、再补指标。
看出来了吗——getSessionsTableGeneric 和第 24 课的 getTracesTableGeneric 简直是一个模子:同样的「按 select 取不同形状」(会话有 count / rows / metrics 三种,比 traces 少一个 identifiers),
同样的「紧凑行 vs 指标」拆分。会话列表也是:先把便宜的会话身份行画出来,昂贵的聚合指标(duration、总成本)后到补入。第 24 课的所有性能技巧,会话白白继承:
分页、回看时间窗、按需聚合、URL 状态、列预设、行选择——这些在第 24 课里费心打磨的能力,会话表一行新代码都不用写就全有了,因为它走的是同一套通用机制。
这就是把表格系统做成「实体无关的通用件」的回报:再来一个「按某个维度聚合的列表」(会话、用户、模型……),都能套同一个模子。
rows 取会话身份与它含的 trace_ids(便宜、先渲染),metrics 取 duration、session_total_cost 等聚合(贵、后补)。源码:sessions-ui-table-service.ts:132-160。| 会话指标 | 怎么从组内 traces 算出来 |
|---|---|
user_ids | 去重收集组内所有 trace 的 user_id(谁参与了对话) |
trace_count | 计数:这个会话里有几条 trace(聊了几轮) |
duration | 最晚时间戳 − 最早时间戳(整段对话持续多久) |
session_total_cost | 对组内所有 trace 的成本求和(这段对话总共花了多少) |
trace_ids | 收集组内所有 trace 的 id(点开会话即按序展开它们) |
会话的各项指标不预先存,靠 GROUP BY 从 traces 现算。新来一条带 session_id=S1 的 trace,它自动就被算进会话 S1 的统计——指标永远和底层 traces 一致,无需同步聚合值。
若把每个会话的计数、成本、时长预先算好存进一张表,每条 trace 进来都得去更新对应会话的这些聚合值——多一套写入、多一处可能与底层 traces 不一致的状态。能现算就别预存。
需要厘清一个细节:会话并非完全不落库。摄取时,如果一条 trace 带了 session_id,worker 会往 Postgres 的 trace_sessions 表
upsert 一个极轻的「存根」行(只有 id、project_id、environment、时间戳,且 ON CONFLICT DO NOTHING——同一会话只登记一次)。这行的作用是「登记这个会话存在」、
以及挂一些会话级元数据(如收藏、公开标记)。但请注意:真正昂贵的那些——user_ids、轮数、时长、总成本、trace 列表——全都不在这张表里,它们一律由 ClickHouse 对 traces 现场 GROUP BY 算出。
所以准确的说法是:会话有一个轻量元数据实体被持久化,但它的全部指标与列表是派生的。这正是关键取舍——该存的(身份、元数据)才存,能算的(聚合指标)就别存。
点开一个会话,看到的是它含的那些 trace按时间排成一条对话时间线——第一轮、第二轮……每一轮点进去又是第 25 课那棵观测树。从列表到详情,会话只是在 trace 之上加了一层「对话」的视角, 让你不再孤立地看单条调用,而是看清「一整段交互」的来龙去脉。这对调试多轮 agent 尤其重要:很多问题不在某一轮,而在轮与轮之间——上一轮的输出怎样影响了下一轮、对话从哪里开始跑偏。
每行一个会话:谁参与、几轮、多久、花了多少(聚合指标后补,同第 24 课)。
用该会话的 trace_ids 把它含的 traces 取回,按时间排序成一条时间线。
时间线上每一项是一轮 trace(一问一答);想细看哪轮,点进去就是第 25 课的观测树(IO 懒加载)。
会话视角让你一眼看出「这段对话怎么演进、在哪轮变贵、哪轮出错」——这是单看一条 trace 给不了的。
session_id 本就是第 8 课宽表上的一列,按它分组是免费的;而且这种「现算」天然永远和底层一致——新来一条 trace 带着某 session_id,它自动就被算进那个会话的统计,
不需要任何「更新会话聚合」的同步步骤,也就不存在「trace 写进去了、会话计数却忘了加」这种不一致 bug。Langfuse 只在 Postgres 落一个极轻的会话存根(登记存在 + 挂元数据),
把所有昂贵的聚合留给查询时现算——既避免了预存聚合的同步负担,又保留了一个挂收藏/公开等元数据的落点。更划算的是:因为会话表原样复用了第 24 课的表格机制,
它白嫖了那套「紧凑行 vs 指标、按需聚合、URL 状态」的全部性能与体验。一个看起来很实在的新功能,列表与指标本质上只是一句 GROUP BY + 复用已有机制——这是「正交设计」最省力的红利。
session_id 分组(一段多轮对话 = 一个会话 = 多条 trace);其指标与列表是派生的,仅一个轻量元数据存根(trace_sessions)在摄取时落 Postgres。session_id 只是第 8 课宽表的一列,GROUP BY session_id 即得会话;各指标是对组内 traces 的聚合(不预存)。user_ids(去重谁参与)、trace_count(计数)、duration(最晚−最早)、session_total_cost(求和)、trace_ids(收集)。getSessionsTableGeneric 同样的紧凑行 vs 指标拆分(会话有 count/rows/metrics 三种形状,比 traces 少一个 identifiers)——性能技巧白白继承。
Lessons 24 and 25 covered the list and detail of a single trace. But a real conversation is often multi-turn — the user asks, the AI answers,
back and forth a dozen rounds, each round a trace. What threads them into one whole conversation is the session. This lesson's key
insight is strikingly lean: a session's metrics and listing aren't stored separately; they're computed on the fly by grouping traces on session_id (only a tiny metadata stub is persisted, more below). Better still,
the sessions table reuses Lesson 24's table machinery nearly verbatim — bluntly, it's the trace table, grouped.
Recall Lesson 8: session_id is just an ordinary column on the traces wide table. So a session's metrics and listing needn't be stored separately — just
GROUP BY session_id over traces sharing the same id and you get one "session" row, whose metrics are all aggregates over the grouped
traces:
session_id grouped by GROUP BY session_id into one session row; each metric is an aggregate over the grouped traces — user_ids (distinct who), trace_count (count), duration (latest − earliest), session_total_cost (sum). Source: packages/shared/src/server/services/sessions-ui-table-service.ts:86,123.sessionId on traces; values illustrative): each user turn is its own trace; sharing a sessionId lets them line up into a conversation swimlane. You can drill into one turn's detail (the Lesson 25 waterfall) or view the whole session's duration, turn count and average score.// the same pattern as Lesson 24's getTracesTableGeneric: one function, several "shapes" (sessions: count/rows/metrics) const getSessionsTableGeneric = async <T>(props: { select: "count" | "rows" | "metrics" }) => { switch (select) { case "rows": sqlSelect = "session_id, min/max_timestamp, trace_ids, user_ids, trace_count …"; // cheap case "metrics": sqlSelect = "… + duration, total_observations, session_total_cost …"; // computed } // under the hood: GROUP BY session_id over traces (and their observations for cost) }
A detail worth noting: a session's "total cost" doesn't sit directly on the trace; it must drill into each trace's observations to sum (cost is
computed on the observation in Lesson 16). So a session's total cost is essentially "the sum of all observations' costs across all traces in the session" — a
two-level aggregation. That's why session_total_cost belongs to the "expensive" metrics shape, filled in later: like the cost metric in
Lesson 24's list, it must be computed across tables. The cheap rows shape takes only the session identity (who, how many rounds, which trace_ids), never
touching cost, so the session list can open instantly, then fill metrics.
See it? getSessionsTableGeneric and Lesson 24's getTracesTableGeneric are cut from the same mold: the same four
shapes (count / rows / metrics), the same "compact rows vs metrics" split. The session list too: paint the cheap session-identity rows first,
the expensive aggregates (duration, total cost) filled in later. All of Lesson 24's performance tricks the session inherits free:
pagination, look-back windows, on-demand aggregation, URL state, column presets, row selection — all the capabilities polished in Lesson 24, the sessions table gets
without writing a line, because it rides the same generic machinery. This is the payoff of making the table system "an entity-agnostic generic
part": any new "list aggregated by some dimension" (sessions, users, models…) fits the same mold.
rows takes session identity and its trace_ids (cheap, rendered first), metrics takes duration, session_total_cost etc. (expensive, later). Source: sessions-ui-table-service.ts:132-160.| session metric | how it's computed from grouped traces |
|---|---|
user_ids | distinctly collect every grouped trace's user_id (who took part in the conversation) |
trace_count | count: how many traces in this session (how many rounds) |
duration | latest timestamp − earliest timestamp (how long the whole conversation lasted) |
session_total_cost | sum of all grouped traces' costs (total spent in this conversation) |
trace_ids | collect every grouped trace's id (open the session to expand them in order) |
A session's metrics aren't pre-stored; they're computed from traces by GROUP BY. A new trace with session_id=S1 is automatically counted into session S1's stats — metrics always consistent with the underlying traces, no aggregate to sync.
Pre-compute each session's count, cost, duration into a table and every incoming trace must update its session's aggregates — an extra write path, an extra piece of state that could drift from the underlying traces. Compute rather than pre-store.
One detail to set straight: a session isn't entirely absent from storage. On ingestion, if a trace carries a session_id, the worker
upserts a tiny "stub" row into Postgres's trace_sessions table (just id, project_id, environment, timestamps, with ON CONFLICT DO
NOTHING — registered once per session). Its job is to "register that this session exists" and to hang some session-level metadata
(like bookmarked, public). But note: the truly expensive parts — user_ids, round count, duration, total cost, the trace list — are none of them in this
table; they're all computed by ClickHouse grouping traces on the fly. So the precise statement is: a lightweight session metadata entity is persisted,
but all of its metrics and listing are derived. That's exactly the trade-off — store what should be stored (identity, metadata), don't store what can be
computed (aggregate metrics).
Open a session and you see its traces laid out as a conversation timeline by time — round one, round two… click into a round and it's Lesson 25's observation tree. From list to detail, a session just adds a "conversation" lens on top of traces, so you no longer see a call in isolation but the whole arc of an interaction. This matters especially for debugging multi-turn agents: many problems aren't in one round but between rounds — how the previous output shaped the next, where the conversation started to go off the rails.
One session per row: who took part, how many rounds, how long, how much spent (aggregates filled later, same as Lesson 24).
Use the session's trace_ids to fetch its traces, ordered by time into a timeline.
Each timeline item is a trace (one Q&A); to inspect a round, click in to Lesson 25's observation tree (IO lazy-loaded).
The session lens shows at a glance "how this conversation evolved, which round got costly, which round errored" — something one trace alone can't give.
session_id is already a column on Lesson 8's wide table, so grouping by it is free; and this on-the-fly form is
naturally always consistent with the underlying traces — a new trace bearing some session_id is automatically counted into that
session's stats, no "update the session aggregates" sync step, hence no "the trace got written but the session count was forgotten" inconsistency bug. Langfuse
persists only a tiny session stub in Postgres (registering existence + holding metadata), leaving all the expensive aggregates to query-time
computation — avoiding the sync burden of pre-stored aggregates while keeping a place to hang metadata like bookmarked/public. Better still: because the
sessions table reuses Lesson 24's machinery verbatim, it freeloads all of that "compact rows vs metrics, on-demand aggregation, URL
state". A seemingly substantial new feature's listing and metrics are essentially one GROUP BY plus reusing existing machinery — the most effortless
dividend of orthogonal design.
session_id (one multi-turn conversation = one session = many traces); its metrics and listing are derived, with only a lightweight metadata stub (trace_sessions) persisted to Postgres on ingestion.session_id is just a column on Lesson 8's wide table; GROUP BY session_id yields the session; each metric is an aggregate over the grouped traces (not pre-stored).user_ids (distinct who), trace_count (count), duration (latest − earliest), session_total_cost (sum, a two-level aggregation into observations), trace_ids (collect).getSessionsTableGeneric has the same select-driven shapes (count/rows/metrics — one fewer than traces, no identifiers) and the same compact-rows-vs-metrics split — all the performance tricks inherited free.