Charts 可观测仪表盘与已退役 Org 接口

Charts API 把 workspace 内的 tracing 指标定义为 Section → Chart/Text Block → Series 的层级。配置和数据读取是两件事：同一 Chart 只有结合时间窗、时区、stride 和 filter 后才产生可比较的数据。

Workspace Charts 生命周期

资源	创建	读取	更新	删除
Section	`POST /api/v1/charts/section`	`GET .../section`；`POST .../section/{id}`	`PATCH .../section/{id}`	`DELETE .../section/{id}`
Chart/Text	`POST /api/v1/charts/create`	`POST /api/v1/charts`；`POST .../{chart_id}`	`PATCH .../{chart_id}`	`DELETE .../{chart_id}`

额外操作：

POST /api/v1/charts/preview：不保存就运行 chart 预览；
POST /api/v1/charts/section/clone：用 section_id 和可选 session_id 复制 dashboard；
GET /api/v1/charts/section：limit=100, offset=0，可按 title、IDs、sort、tag 筛选。

“读 Charts”使用 POST，因为时间窗和查询配置在 body；它在业务语义上是只读，但 CDN/浏览器不会像 GET 一样默认缓存。如要应用级缓存，key 必须包含 workspace/permission、规范化 body、Chart 版本和时间桶。

Section、Chart 与 Text Block

Series 包含 name、metric/project metric/feedback key/workspace、新式 metric definition、group-by definitions 和 filter definition。通用 filters 中可有 filter、trace_filter、tree_filter、session IDs；group-by 支持 name/run_type/tag/metadata path 并用 max_groups 限制基数。

Chart/Text 同时是 union schema，客户端应先按 chart_type 或返回形状做鉴别再解析。Markdown 按不可信输入消毒，禁止 script、事件属性、危险 URL scheme 和任意 iframe。

PATCH schema 用 Missing 区分“未传”与 null：未改字段要省略，只在契约明确允许清空时传 null。不要将本地默认值序列化成全量 PATCH，否则会覆盖并发编辑。

时间桶、预览和载荷控制

Charts 读取的公共请求字段：

timezone 默认 UTC；
start_time/end_time；
stride={days,hours,minutes}；
omit_data默认 false；
列表还可用 after_index 与 tag，Section 读取可 group-by。

Preview 必填 bucket_info 和待测 chart。编辑器应采用 debounce/cancel stale request，为预览限最大窗口、系列数和 group cardinality；先 omit_data=true 取元数据/布局，可见区域再加载数据。趋势对比必须保持 timezone/stride/filter 一致，不将空桶等同 0。

Organization Charts 全部已退役

以下 11 个 /api/v1/org-charts... 端点的描述都明确：organization usage charts have been retired (HTTP 410)：创建/读取/预览/更新/删除 Chart 与 Section 全部不再可用。

当前 OpenAPI 仍为这些 operation 列出空 200 响应，且多个含 {chart_id} 或 {section_id} 的退役路径不再声明对应 path parameter。这是已验证的文档/形式 schema 不一致，不代表运行时仍会 200。新客户端不生成/暴露这些能力；老客户端对 410 停止重试、禁用界面，并迁移到 workspace Charts 或当前用量报表。

删除、并发和可观测性

删 Section 前先枚举 chart count 与子 section/layout 依赖；文档未声明是拒绝、级联还是孤立 Chart，未实测前必须当高风险操作。OpenAPI 未提供 ETag/版本字段，多人编辑应在业务层对比 last-read 快照并提示冲突。

监控 Chart API 本身的 p50/p95、扫描窗口、系列/数据点数、超时、422、缓存命中和废弃 410 调用量；不在日志中完整输出 filter 、metadata 或图表数据。