跳到主要内容

Langfuse · 查询、视图与会话

约 9 分钟2,399 字更新于 2026/10/22

本页覆盖：列表与详情、过滤、聚合、视图预设、导出、会话视图。每条事实链到固定提交（f75c661d）。回到 Langfuse 总览。

4. 查询：列表、详情、树/时间线/图、过滤语法、排序分页、聚合​

4.1 tRPC 与 v3/v4 双路径​

  • tRPC 根路由注册了 traces、sessions、users、scores、models、events 等（web/src/server/api/root.ts L77，permalink、web/src/server/api/root.ts L90，permalink）。
  • 许多路由有成对的 v3 与 v4 过程：如 sessions.all 与 sessions.allFromEvents（web/src/server/api/routers/sessions.ts L197，permalink、web/src/server/api/routers/sessions.ts L260，permalink）。
  • users 路由同样成对：all 与 allFromEvents（web/src/server/api/routers/users.ts L139，permalink）。
  • scores 路由也有 allFromEvents（web/src/server/api/routers/scores.ts L212，permalink）。
  • v4 的主入口是 events 路由：all（分页）、listCursor（游标）、countAll、filterOptions、metadataValues、byTraceId、getAgentGraphData 等（web/src/features/events/server/eventsRouter.ts L134，permalink、web/src/features/events/server/eventsRouter.ts L215，permalink、web/src/features/events/server/eventsRouter.ts L496，permalink）。
  • events.all 先应用评论过滤，再调 getEventList，传入 page 与 limit（web/src/features/events/server/eventsRouter.ts L159-L168，permalink）。
  • events.listCursor 固定按 startTime DESC 排序，用 cursor 翻页（web/src/features/events/server/eventsRouter.ts L242-L249，permalink）。
  • getTraceById 在写入模式不是 events_only 时读旧 traces 表，否则读 events 聚合（packages/shared/src/server/repositories/events.ts L1217-L1223，permalink）。
  • 该函数标了 @deprecated，新用途应直接用 getTraceByIdFromEventsTable（packages/shared/src/server/repositories/events.ts L1213，permalink）。
  • 单条 Trace 的 Observation 读取默认上限来自 LANGFUSE_MAX_OBSERVATIONS_PER_TRACE（packages/shared/src/server/repositories/events.ts L428-L429，permalink）。
  • hasAnyTracingData 先看项目的 hasTraces 标记，未命中再查 ClickHouse（packages/shared/src/server/repositories/events.ts L1300-L1312，permalink）。

4.2 详情：树、时间线、图​

  • 详情路由是 /project/[projectId]/traces/[traceId]（web/src/pages/project/[projectId]/traces/[traceId].tsx L9，permalink）。
  • 桌面布局是左侧导航加右侧 TracePanelDetail（web/src/features/traces/components/Trace.tsx L294，permalink）。
  • 移动端 tab 是 Tree、Timeline、Graph、Info（web/src/features/traces/components/Trace.tsx L305，permalink）。
  • 树用 @tanstack/react-virtual 做虚拟滚动（web/src/features/traces/components/VirtualizedTree.tsx L87，permalink）。
  • 时间线组件在 TraceTimelineDense，详情页引入 TraceTimelineCompact（web/src/features/traces/components/Trace.tsx L27，permalink）。
  • Graph 视图不可用时回退到 tree（web/src/features/traces/components/TracePanelNavigationHeader/TracePanelNavigationHeader.tsx L150，permalink）。
  • 图数据由 getAgentGraphData 提供：v3 在 traces 路由，v4 在 events 路由（web/src/server/api/routers/traces.ts L684，permalink、web/src/features/events/server/eventsRouter.ts L536，permalink）。
  • 图渲染用 ELK 算布局、HTML 节点叠在 SVG 边上、d3-zoom 管视口（web/src/features/trace-graph-view/README.md L3，permalink）。
  • 图支持 LangGraph 元数据转换（web/src/features/trace-graph-view/README.md L13，permalink）。

4.3 过滤语法​

  • 过滤状态 FilterState 是类型化条件列表，类型包括 datetime、string、number、stringOptions、arrayOptions、stringObject、numberObject、booleanObject、null、positionInTrace（packages/shared/src/interfaces/filters.ts L4-L29，permalink）。
  • 字符串操作符有 =、contains、does not contain、starts with、ends with、is not empty（packages/shared/src/interfaces/filters.ts L6-L13，permalink）。
  • 数组操作符有 any of、none of、all of（packages/shared/src/interfaces/filters.ts L16，permalink）。
  • 另有全文匹配操作符 matches，只支持 input、output、metadata（packages/shared/src/interfaces/filters.ts L34，permalink、packages/shared/src/server/queries/clickhouse-sql/fts.ts L16，permalink）。
  • 过滤条件在 URL 里用竖线分隔编码，值里的竖线会被转义（packages/shared/src/features/filters/filterQueryEncoding.ts L26，permalink）。
  • 内存过滤有 InMemoryFilterService，用于自动化触发条件匹配（packages/shared/src/server/automations.ts L34，permalink）。
  • 排序状态是 { column, order: ASC | DESC }（packages/shared/src/interfaces/orderBy.ts L3，permalink）。
  • 前端有自然语言过滤：naturalLanguageFilter.createCompletion，自托管部署里不可用（web/src/features/natural-language-filters/server/router.ts L45，permalink）。

4.4 query-ast​

  • query-ast 是基于 Kysely 的 ClickHouse 编译器，强制注入租户条件 project_id = {projectId}（packages/shared/src/server/query-ast/README.md L12，permalink）。
  • 注入通过插件 TenancyInjectionPlugin 实现，缺 projectId 时抛错（packages/shared/src/server/query-ast/tenancy.ts L67，permalink）。
  • 唯一入口是 compileClickhouseQuery(query, ctx)（packages/shared/src/server/query-ast/README.md L23，permalink）。
  • 目前仓储层只有 environments.ts 调用了它（packages/shared/src/server/repositories/environments.ts L4，permalink）。
  • 其他仓储仍用手写 SQL 与 event-query-builder（packages/shared/src/server/queries/clickhouse-sql/event-query-builder.ts L1358，permalink）。

4.5 排序、分页、聚合​

  • v3 列表用 page + limit；v4 有 listCursor 的游标分页（web/src/features/events/server/eventsRouter.ts L215，permalink）。
  • 公共 API v1 的 GET /api/public/traces 用 page/limit（web/src/pages/api/public/traces/index.ts L158，permalink）。
  • 公共 API v2 的 observations 用 cursor/limit，并支持 fields 字段组与 expandMetadata（web/src/pages/api/public/v2/observations/index.ts L60，permalink、web/src/pages/api/public/v2/observations/index.ts L29，permalink）。
  • 公共 API v3 的 scores 用 cursor（web/src/pages/api/public/v3/scores/index.ts L8，permalink）。
  • 公共 API 的 Trace 字段组是 core、io、scores、observations、metrics（packages/shared/src/server/repositories/traces.ts L1512-L1516，permalink）。
  • 聚合走第 8 节的 Dashboard/Metrics 查询引擎（聚合函数 sum/avg/count/max/min/p50/p75/p90/p95/p99/histogram/uniq，见 packages/shared/src/features/query/types.ts L4-L18，permalink）。
  • 时间粒度 granularities 含 auto、minute、hour、day、week、month 和 5m…1w（packages/shared/src/features/query/types.ts L194-L211，permalink）。

5. 表格视图预设、列配置、批量导出、批量操作​

5.1 视图预设与列配置​

  • Postgres 表 TableViewPreset 存视图预设，含 filters、columnOrder、columnVisibility、searchQuery、orderBy（packages/shared/prisma/schema.prisma L1704-L1727，permalink）。
  • 预设在 (projectId, tableName, name) 上唯一（packages/shared/prisma/schema.prisma L1727，permalink）。
  • 预设的 tableName 枚举含 traces、observations、observations-events、scores、sessions、session-detail、datasets、experiments、users 等（packages/shared/src/domain/table-view-presets.ts L5-L18，permalink）。
  • DefaultView 记录每个视图的默认预设；userId 为空表示项目级默认，非空表示用户级默认（packages/shared/prisma/schema.prisma L1731-L1753，permalink）。
  • viewId 不加外键，允许前端定义的系统预设（以 __langfuse_ 开头）（packages/shared/prisma/schema.prisma L1743，permalink）。
  • tRPC 路由 TableViewPresets 提供 create、update、updateName、delete、getByTableName、getById（web/src/server/api/routers/tableViewPresets.ts L28，permalink、web/src/server/api/routers/tableViewPresets.ts L139，permalink）。
  • 路由注册在 root.ts（web/src/server/api/root.ts L123，permalink）。
  • 列可见性由 hook useColumnVisibility 管理，存储键是传入的 localStorageKey，基于 useLocalStorage（web/src/features/column-visibility/hooks/useColumnVisibility.ts L3，permalink、web/src/features/column-visibility/hooks/useColumnVisibility.ts L24，permalink）。
  • Session 详情页也有预设：session-detail-presets.ts 和 ModernSessionSaveViewDialogContent.tsx（路径存在，见 web/src/features/sessions/session-detail-presets.ts L1，permalink）。

5.2 批量导出​

  • Postgres 表 BatchExport 记录导出任务：status、query、format、url、expiresAt、log（packages/shared/prisma/schema.prisma L1435-L1457，permalink）。
  • 导出状态有 QUEUED、PROCESSING、COMPLETED、FAILED、CANCELLED（packages/shared/src/features/batchExport/types.ts L14-L20，permalink）。
  • 导出格式有 JSON、CSV、JSONL（packages/shared/src/features/batchExport/types.ts L22-L26，permalink）。
  • 可导出的表由 BatchTableNames 定义：scores、sessions、traces、observations、events、datasets、dataset_run_items、dataset_items、audit_logs（packages/shared/src/interfaces/tableNames.ts L6-L16，permalink）。
  • tRPC batchExport 提供 create、cancel、downloadUrl、all（web/src/features/batch-exports/server/batchExport.ts L86，permalink、web/src/features/batch-exports/server/batchExport.ts L163，permalink、web/src/features/batch-exports/server/batchExport.ts L182，permalink、web/src/features/batch-exports/server/batchExport.ts L256，permalink）。
  • create 把任务放进 BatchExportQueue，任务名 BatchExportJob（web/src/features/batch-exports/server/batchExport.ts L143-L145，permalink）。
  • Worker 用 getDatabaseReadStreamPaginated 分页读数据，再经 streamTransformations[format] 转换（worker/src/features/batchExport/handleBatchExportJob.ts L218，permalink、worker/src/features/batchExport/handleBatchExportJob.ts L251，permalink）。
  • 结果通过 uploadFileBuffered 流式上传到对象存储（worker/src/features/batchExport/handleBatchExportJob.ts L295-L298，permalink）。
  • 下载链接过期后不可用；过期判断用 expiresAt，旧记录有兜底（web/src/features/batch-exports/server/batchExport.ts L33-L41，permalink）。
  • 公共 API 没有批量导出端点。无。已搜索：web/src/pages/api/public/ 顶层目录（含 traces、observations、scores、sessions、metrics、otel 等，没有 export 相关目录）。

5.3 批量操作​

  • Postgres 表 BatchAction 记录批量操作：actionType、tableName、status、query、config、totalCount、processedCount、failedCount（packages/shared/prisma/schema.prisma L1459-L1484，permalink）。
  • BatchActionType 只有 create 和 delete（packages/shared/src/features/batchAction/types.ts L11-L14，permalink）。
  • 具体动作 ActionId 有：trace-delete、score-delete、dataset-delete、trace-add-to-annotation-queue、session-add-to-annotation-queue、observation-add-to-annotation-queue、observation-add-to-dataset、observation-run-batched-evaluation、experiment-compare（packages/shared/src/features/batchAction/types.ts L24-L35，permalink）。
  • 批量操作的状态有 QUEUED、PROCESSING、COMPLETED、FAILED、PARTIAL（packages/shared/src/features/batchAction/types.ts L16-L22，permalink）。
  • 前端通过 TableSelectionManager、TableActionMenu、TableActionDialog 选择行并触发操作（web/src/features/table/components/TableSelectionManager.tsx L1，permalink、web/src/features/table/components/TableActionMenu.tsx L1，permalink）。
  • 服务端在 createBatchActionJob.ts 创建任务（web/src/features/table/server/createBatchActionJob.ts L1，permalink）。
  • Worker 入口是 handleBatchActionJob，按动作分发到 processAddToQueue、processAddObservationsToDataset、processBatchedObservationEval、processDeleteDatasets、processTraceDeleteBatchAction（worker/src/features/batchAction/handleBatchActionJob.ts L187，permalink，同目录文件名见 worker/src/features/batchAction/processAddToQueue.ts L1，permalink）。
  • 设置页有批量操作列表：BatchActionsSettingsPage（web/src/features/batch-actions/components/BatchActionsSettingsPage.tsx L1，permalink）；服务端 batchActionRouter 提供 byId 和 all（web/src/features/batch-actions/server/batchActionRouter.ts L16，permalink、web/src/features/batch-actions/server/batchActionRouter.ts L55，permalink）。

6. Session 视图与 User 视图​

6.1 Session​

  • Session 不是独立实体。它由 Trace 或 Observation 行上的 session_id 聚合而成（events_full 的 session_id 列：packages/shared/clickhouse/migrations/canonical/0039_create_events_full.up.sql L19，permalink；布隆索引：packages/shared/clickhouse/migrations/canonical/0039_create_events_full.up.sql L104，permalink）。
  • Postgres 的 TraceSession 只存 bookmarked、public、environment，主键 (id, projectId)（packages/shared/prisma/schema.prisma L501-L514，permalink）。
  • tRPC sessions 路由有列表（all、allFromEvents）、计数（countAll、countAllFromEvents）、指标（metrics、metricsFromEvents）、筛选项（filterOptions、filterOptionsFromEvents）（web/src/server/api/routers/sessions.ts L197，permalink、web/src/server/api/routers/sessions.ts L463，permalink）。
  • 详情有 byIdWithScores、byIdWithScoresFromEvents、tracesFromEvents、observationsForTraceFromEvents、observationFullIOFromEvents（web/src/server/api/routers/sessions.ts L706，permalink、web/src/server/api/routers/sessions.ts L774，permalink、web/src/server/api/routers/sessions.ts L980，permalink）。
  • Session 可收藏和公开：bookmark、publish（web/src/server/api/routers/sessions.ts L1008，permalink、web/src/server/api/routers/sessions.ts L1048，permalink）。
  • v4 的 Session 列表服务是 getSessionsTableFromEvents，指标服务是 getSessionsWithMetricsFromEvents（packages/shared/src/server/services/sessions-ui-table-events-service.ts L135，permalink、packages/shared/src/server/services/sessions-ui-table-events-service.ts L162，permalink）。
  • 页面路由：列表 /project/[projectId]/sessions，详情 /project/[projectId]/sessions/[sessionId]（web/src/pages/project/[projectId]/sessions/index.tsx L1，permalink、web/src/pages/project/[projectId]/sessions/[sessionId].tsx L1，permalink）。
  • 详情页组件有 SessionDetailPage、ModernSession、ModernSessionSidebar、SessionReviewWorkspace（web/src/features/sessions/SessionDetailPage.tsx L1，permalink、web/src/features/sessions/ModernSession.tsx L1，permalink、web/src/features/sessions/SessionReviewWorkspace.tsx L1，permalink）。
  • Session 内相邻 Trace 间隔超过 5 分钟算「空闲间隔」（web/src/features/sessions/sessionIdleGap.ts L1，permalink）。
  • Session 详情页的评论与标注共用同一个评审面板（web/src/features/sessions/README.md L3，permalink）。
  • 公共 API：GET /api/public/sessions 与 GET /api/public/sessions/[sessionId]（web/src/pages/api/public/sessions/index.ts L13，permalink、web/src/pages/api/public/sessions/[sessionId].ts L14，permalink）。
  • 这两个公共端点在 events_only 下返回 404（web/src/pages/api/public/sessions/index.ts L21，permalink、web/src/pages/api/public/sessions/[sessionId].ts L24，permalink；404 行为见 web/src/features/public-api/server/createAuthedProjectAPIRoute.ts L166，permalink）。

6.2 User​

  • User 同样不是独立实体，来自 user_id 列（packages/shared/clickhouse/migrations/canonical/0039_create_events_full.up.sql L18，permalink）。
  • Postgres 里没有 User 业务表给被观测的终端用户用。已搜索：packages/shared/prisma/schema.prisma 的 model 列表，只有登录用户 User，没有终端用户表。
  • tRPC users 路由有 hasAny、all、metrics、byId 及对应的 *FromEvents（web/src/server/api/routers/users.ts L43，permalink、web/src/server/api/routers/users.ts L198，permalink）。
  • v4 用户读取函数有 getUsersFromEventsTable、getUserMetricsFromEventsTable（packages/shared/src/server/repositories/events.ts L3038，permalink、packages/shared/src/server/repositories/events.ts L3122，permalink）。
  • 页面：/project/[projectId]/users 与 /users/[userId]；组件 UsersTable、UserDetailPage（web/src/pages/project/[projectId]/users/index.tsx L1，permalink、web/src/features/users/UserDetailPage.tsx L1，permalink、web/src/features/users/UsersTable.tsx L1，permalink）。
  • 公共 API 没有 users 端点。无。已搜索：web/src/pages/api/public/ 顶层目录列表（无 users），以及全文搜索 api/public/users（web/src 下无匹配）。