coze-loop · 查询、视图与会话

约 7 分钟1,835 字更新于 2026/10/22

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

四、查询：列表、详情、树、过滤语法、排序分页、聚合

接口

• 列表是 POST /api/observability/v1/spans/list（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L626）。
• 详情是 GET /api/observability/v1/traces/:trace_id，树是 POST .../traces/search_tree，批量 token 是 POST .../traces/batch_get_advance_info（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L628-L630）。
• OpenAPI 查询有 traces/search、traces/search_tree、spans/search、pre_span/search、traces/list、traces/trajectory（idl/thrift/coze/loop/observability/coze.loop.observability.openapi.thrift L234-L239）。
• OpenAPI 的 traces/list 按给定 trace_ids 返回 token 和 size，不返回 span 树（backend/modules/observability/application/openapi.go L1051-L1092）。
• 另有 traces/meta_info（字段元数据）和 traces/metadata/list（标签键值统计，最多 300 个 span）（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L632、idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L650、backend/modules/observability/domain/trace/service/trace_service.go L1800-L1830）。

过滤语法

• 过滤是 FilterFields，含 query_and_or 和 filter_fields 列表（idl/thrift/coze/loop/observability/domain/filter.thrift L40-L43）。
• 每个 FilterField 有 field_name、field_type、values、query_type、query_and_or、sub_filter、is_custom、extra_info，支持嵌套（idl/thrift/coze/loop/observability/domain/filter.thrift L45-L54）。
• QueryType 有 12 种：match、eq、not_eq、lte、gte、lt、gt、exist、not_exist、in、not_in、not_match（idl/thrift/coze/loop/observability/domain/filter.thrift L5-L17）。
• FieldType 有 string、long、double、bool（idl/thrift/coze/loop/observability/domain/filter.thrift L23-L27）。
• 字段名先过安全检查，再按 IsCustom、IsSystem、超级列的顺序映射到列或 Map 键（backend/modules/observability/infra/repo/ck/spans.go L488-L528）。
• status 过滤把 success 转成 status_code = 0，把 error 转成 status_code NOT IN (0)（backend/modules/observability/domain/trace/service/trace_filter_helper.go L95-L119）。
• 按标注过滤时，用子查询从标注表取 span_id，并加 SETTINGS final = 1（backend/modules/observability/infra/repo/ck/spans.go L440-L482）。
• 可过滤字段由配置 trace_field_meta_info.available_fields 描述，含 input、output、status、duration、latency_first_resp、span_name、trace_id、span_type、input_tokens、output_tokens、tokens、message_id、user_id、prompt_key、feedback_manual（release/deployment/docker-compose/conf/observability.yaml L96-L208）。
• 字段元数据按平台和列表类型分组，平台有 default、cozeloop、prompt 三组（release/deployment/docker-compose/conf/observability.yaml L209-L328）。
• 列表范围 SpanListType 有 root_span、all_span、llm_span，平台类型有 cozeloop、prompt、evaluator、evaluation_target 等（idl/thrift/coze/loop/observability/domain/common.thrift L3-L25）。
• 列表未传类型时默认 root_span（backend/modules/observability/application/trace.go L235-L243）。
• Coze Loop 平台的基础过滤固定加 call_type = Custom 和 workspace 条件（backend/modules/observability/domain/trace/service/trace/span_filter/cozeloop_filter.go L16-L30）。

排序与分页

• 请求里有 order_bys（field、is_asc），请求只允许 0 或 1 个（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L21、idl/thrift/coze/loop/observability/domain/common.thrift L35-L38、backend/modules/observability/application/trace.go L193-L201）。
• 后端只看 order_bys 是否非空，非空时固定按 start_time DESC, span_id DESC 排序，不读 field 和 is_asc（backend/modules/observability/application/trace.go L217-L225、backend/modules/observability/infra/repo/ck/spans.go L251-L256）。
• 没有 order_bys 时，单表 SQL 不加 ORDER BY（backend/modules/observability/infra/repo/ck/spans.go L238-L262）。
• 多表时用 UNION ALL 合并，再按同样规则排序（backend/modules/observability/infra/repo/ck/spans.go L210-L228）。
• 分页是游标式：多取 1 条判断 has_more，游标编码最后一条的 start_time 和 span_id（backend/modules/observability/infra/repo/trace.go L215-L221、backend/modules/observability/infra/repo/trace.go L268-L277）。
• 页大小上限 1000，默认 100，OpenAPI 上限 200（backend/modules/observability/application/trace.go L44-L51）。
• 查询时间窗按 trace_max_duration_day 校正，开源默认是 180 天，缺配置时为 7 天（backend/modules/observability/application/trace.go L202-L215、release/deployment/docker-compose/conf/observability.yaml L74-L79、backend/modules/observability/infra/config/trace.go L132-L151）。
• 查出 span 后，默认再按 span_id 拉标注并挂回 span（backend/modules/observability/infra/repo/trace.go L247-L266）。

聚合

• 列表接口没有 group by 或聚合参数。
• 聚合只出现在三处：指标接口（见第八节）、GetThreadStat（按 thread 汇总，见第六节）、ListMetadata（标签键统计）（backend/modules/observability/domain/trace/service/trace_service.go L3370-L3427、backend/modules/observability/domain/trace/service/trace_service.go L1800-L1830）。
• 另有轨迹（trajectory）查询 POST /api/observability/v1/traces/trajectory，配合 trajectory_config 过滤（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L647-L649、backend/modules/observability/domain/trace/service/trace_service.go L1102-L1147）。

五、视图、列表列配置、导出

视图（保存的过滤条件）

• 视图 CRUD 路由是 /api/observability/v1/views（POST、PUT、DELETE、list）（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L633-L636）。
• 视图存在 MySQL 表 observability_view，含 workspace、平台、span 列表类型、filters（varchar 2048）、scope（release/deployment/docker-compose/bootstrap/mysql-init/init-sql/observability_view.sql L1-L22）。
• scope 取值：1 列表、2 详情树、3 详情对话（release/deployment/docker-compose/bootstrap/mysql-init/init-sql/observability_view.sql L17、idl/thrift/coze/loop/observability/domain/view.thrift L5-L9）。
• 视图按创建人隔离：ListViews 带 created_by = userID，最多返回 100 条（backend/modules/observability/infra/repo/mysql/view.go L59-L74）。
• 创建与列表分别检查 createLoopTraceView、listLoopTraceView 动作；更新走 CheckViewPermission（backend/modules/observability/application/trace.go L706-L731、backend/modules/observability/application/trace.go L733-L771、backend/modules/observability/application/trace.go L796-L820）。
• 系统视图来自配置，开源默认有 Exceptions（status = error）和 High-latency（duration >= 10000），响应里标 IsSystem（release/deployment/docker-compose/conf/observability.yaml L44-L50、backend/modules/observability/application/trace.go L822-L848）。
• 前端有视图的创建、更新、删除交互，直接调 observabilityTrace.CreateView/UpdateView/DeleteView（frontend/packages/loop-components/observation-components/src/shared/components/filter-bar/custom-view.tsx L154-L182、frontend/packages/loop-components/observation-components/src/shared/components/filter-bar/custom-view.tsx L359-L370）。

列表列配置

• 前端列的显示状态存在浏览器 localStorage，不走后端（frontend/packages/loop-components/observation-components/src/features/trace-list/hooks/use-column.ts L27-L36、frontend/packages/loop-components/observation-components/src/features/trace-list/hooks/use-column.ts L100-L108）。
• 后端另有 column_extract_config：按 workspace、平台、列表类型、agent 名保存列提取规则 JSON（release/deployment/docker-compose/bootstrap/mysql-init/init-sql/observability_column_extract_config.sql L1-L22、backend/modules/observability/application/trace.go L1585-L1643）。
• 前端业务源码里没有 column_extract_config 的调用。已在 frontend/packages/loop-components/observation-components/src、frontend/packages/loop-pages/observation-pages/src 搜索 ColumnExtract、column_extract，无命中。

导出

• 导出到数据集：POST /api/observability/v1/traces/export_to_dataset 和 preview_export_to_dataset（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L642-L643）。
• 导出要求 exportLoopTrace 权限，预览要求 previewExportLoopTrace（backend/modules/observability/application/trace.go L1095-L1130、backend/modules/observability/domain/component/rpc/auth.go L17-L18）。
• 导出服务取 span、按字段映射建数据集条目，并在成功后异步给 span 回写标注（backend/modules/observability/domain/trace/service/trace_export_service.go L136-L201、backend/modules/observability/domain/trace/service/trace_export_service.go L480-L526）。
• 导出到文件（CSV/Excel/JSON 下载整个列表）：无。已在 backend/modules/observability、idl/thrift/coze/loop/observability、frontend/packages/loop-pages/observation-pages/src、frontend/packages/loop-components/observation-components/src 搜索导出相关入口。只找到数据集导出，以及查看大字段时的 fileDownload（frontend/packages/loop-components/observation-components/src/features/trace-data/components/view-all.tsx L16、frontend/packages/loop-components/observation-components/src/features/trace-data/components/view-all.tsx L42）。
• 前端业务源码没有 ExportTracesToDataset 的调用，Trace 页面看不到导出入口。已在 frontend/packages、frontend/apps（排除 api-schema）搜索，无命中。

六、Session / thread / chat 视图

• thread_id 是 span 字段名常量，不是 Trace 结构字段（backend/modules/observability/domain/trace/entity/loop_span/span.go L61）。
• OTel 的 session.id 会写成 thread_id 标签（backend/modules/observability/lib/otel/otel_convert.go L44-L48）。
• ListTraceChat 按 trace_id 拉 model 和 tool span，再拆成对话消息（backend/modules/observability/domain/trace/service/trace_service.go L3016-L3093）。
• model span 的 input 记为 user，output 记为 assistant，tool span 记为 tool（backend/modules/observability/domain/trace/service/trace_service.go L3430-L3467）。
• ListThreadChat 按 thread_id 只拉 model span，支持前后游标和锚点定位（backend/modules/observability/domain/trace/service/trace_service.go L3102-L3207）。
• GetThreadStat 在同一 thread_id 的 model span 上汇总开始时间、时长、user、token 和模型（backend/modules/observability/domain/trace/service/trace_service.go L3370-L3427）。
• GetAdjacentTrace 在同一 thread 内按方向取相邻 trace，时间窗是锚点前后各 7 天（backend/modules/observability/domain/trace/service/trace_service.go L3297-L3367）。
• 四个会话接口的 HTTP 路径是 traces/chat/list、threads/chat/list、threads/stat、threads/adjacent_trace（idl/thrift/coze/loop/observability/coze.loop.observability.trace.thrift L651-L654）。
• 视图 scope 里预留了 trace_detail_chat（idl/thrift/coze/loop/observability/domain/view.thrift L5-L9）。
• IDL 的 Session 只有 user_id，用于任务和评测 RPC，不是 thread 对象（idl/thrift/coze/loop/observability/domain/common.thrift L66-L68）。
• 没有独立的 session 表或 thread 表。会话完全靠 span 标签 thread_id 聚合。
• 前端业务源码没有 ListTraceChat、ListThreadChat、GetThreadStat、GetAdjacentTrace 的调用。已在 frontend/packages/loop-components/observation-components/src、frontend/packages/loop-pages/observation-pages/src 搜索，仅在生成的 API 客户端出现。