---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - tracing-project
  - dashboard
topic: LangSmith Smith API Tracing Project 生命周期、过滤视图与 Dashboard
sources:
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/create-filter-view
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/create-tracer-session
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/delete-filter-view
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/delete-tracer-session
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/delete-tracer-sessions
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/get-tracing-project-prebuilt-dashboard
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/read-filter-view
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/read-filter-views
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/read-tracer-session
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/read-tracer-sessions
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/read-tracer-sessions-runs-metadata
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/rename-filter-view
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/update-filter-view
  - https://docs.langchain.com/langsmith/smith-api/tracer-sessions/update-tracer-session
last_verified: 2026-08-11
---

# 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，没有承诺级联、软删除或恢复；运行时未实测前不应宣称下游已一同清理。