学习笔记 · Obsidian
Tracing Project 生命周期、过滤视图与 Dashboard
Smith API 中 Tracing Project 仍使用历史名称 Tracer Session，路径是 /api/v1/sessions。它是 Run/Trace、统计、过滤视图、Dashboard 和 Insights 的授权/存储边界，不是一次用户会话。
Project CRUD
| 能力 | 方法与路径 | 关键参数 |
|---|---|---|
| 创建 | POST /api/v1/sessions | query upsert=false；body TracerSessionCreate |
| 列表 | GET /api/v1/sessions | 过滤、排序、offset/limit、stats/facets |
| 读单个 | GET /api/v1/sessions/{session_id} | include_stats、stats_start_time |
| 更新 | PATCH /api/v1/sessions/{session_id} | name/description/dataset/end/extra/trace tier |
| 删单个 | DELETE /api/v1/sessions/{session_id} | 200，无响应体 |
| 批量删 | DELETE /api/v1/sessions?session_ids=... | 可重复 UUID query |
创建模型包含 name/description、可选稳定 id、start/end time、extra、default/reference dataset、tag values、实验次数/评估键以及 trace_tier=longlived|shortlived。upsert 只是服务端选项，调用方仍应提供稳定 ID/名称和业务幂等键，并在超时后先查再创建。
列表与统计的成本边界
列表默认 offset=0, limit=100，可按 ID/name/name contains、reference dataset、dataset version、metadata JSON、tag、filter 和是否 reference-free 筛选；可按 name/start/last run/latency/error rate/feedback 排序。
include_stats、facets、use_approx_stats、stats_select、stats_filter 会显著改变查询成本和响应体。项目响应可包含 Run 数、latency/first-token P50/P99、token/cost、feedback stats、facets、error/streaming rate 和实验进度。列表页默认不取全统计；将指标查询限制到显式时间窗，并对一页中的项目数设上限。
GET /sessions/{session_id}/metadata 按可选 metadata keys 返回每个 key 的 top-K 值，默认 k=10，可限时间并只看根 Run。它是构建 filter/facet 候选项的接口，不应用来枚举高基数、PII 或密钥型 metadata。
Filter View 是保存的查询语义
| 操作 | 方法与路径 |
|---|---|
| 创建 / 列表 | POST / GET /api/v1/sessions/{session_id}/views |
| 读 / 更新 / 删除 | GET / PATCH / DELETE .../views/{view_id} |
| 只重命名 | PATCH .../views/{view_id}/rename |
创建必填 display_name，可存 filter_string、trace_filter_string、tree_filter_string、description、start/end/duration。type 枚为 runs|threads|single_run。rename 只修改 display name/description，而通用 update 可改过滤与时间语义；UI 应将两种变更区分审计，避免用户以为“只改名”却改变数据范围。
固定 start/end 是可重现快照，duration 是滚动窗口；产品层应明示时区、实际解析时间和 filter 版本。服务端仍需对 view 中的 session 做授权，不能因 view ID 可猜测就绕过 workspace 边界。
预制 Dashboard
POST /api/v1/sessions/{session_id}/dashboard 接受 timezone（默认 UTC）、start/end、stride、omit_data 和 group-by，返回包含图表的 section。omit_data=true 适合先取布局/配置，不要在初始页面无条件拉取所有时序数据。相同 dashboard 的缓存 key 需包含 workspace、session、timezone、窗口、stride、group-by 和权限版本。
更新、保留与删除
trace_tier 会影响 Trace 保留/存储策略，修改前必须评估合规、成本、回溯和下游导出。删 Project 前列出 Run/Trace 数、公开 share、rules/alerts、filters/charts、Feedback、bulk export 和 dataset 关联，先停止新 ingest 再导出/审批/分批删除。OpenAPI 只给 200/422，没有承诺级联、软删除或恢复；运行时未实测前不应宣称下游已一同清理。