系统可观测性与健康监控

Clouisle 提供面向平台管理员的运行可观测性 API，所有路由挂载在 /api/v1/admin/observability 下。读取端点需要 admin:dashboard:access 权限；确认告警、静默告警与规则更新需要 admin:observability:manage 权限。

时间窗口参数

summary、runs、dependencies 三个端点接受统一的时间窗口参数：

非法窗口参数返回 422。

控制台视图

管理台可观测性页（/dashboard/observability）有六个视图，共用顶部时间范围：

时间范围按钮弹出双月日历：选择起止日期并应用后，两端都包含浏览器本地时区当天的完整范围（含夏令时切换）；取消或关闭弹层保持已应用区间。弹层底部的快捷范围为最近 15 分钟、1 小时、24 小时。自定义区间以 period=custom 加 ISO 8601 start_time / end_time 传递，后端按 UTC 处理；缺失、naive、相等或反向的区间，以及预设与显式边界同时出现，返回 422。URL 会保留所选区间，刷新、切换视图和运行翻页后仍生效。遥测保留 30 天，选择更早的区间不会恢复已过期样本。

运行汇总（Summary）

端点：GET /api/v1/admin/observability/summary

返回紧凑的运行汇总与趋势（提交数、成功率、分位数、Token、趋势桶、待办事项）。样本不足时，分位数与成功率为 null，调用方不得将其按 0 处理。

运行列表与详情（Runs）

列表端点：GET /api/v1/admin/observability/runs

列表只返回摘要字段，详情需单独获取。列表支持 keyset 分页：响应中的 next_cursor 传入下一次请求的 cursor 即翻页。

详情端点：GET /api/v1/admin/observability/runs/{source}/{run_id}

• {source} 仅支持 agent 或 workflow，不支持 all；run_id 为 UUID。
• 不存在的运行返回 404。权限在加载 trace 内容之前校验。

按需载荷端点（读取权限，未采集或不存在时返回 404）：

• GET /api/v1/admin/observability/runs/{source}/{run_id}/tools/{tool_call_id}：读取一条已记录的工具入参/结果对；只有 agent 运行记录工具载荷，其他来源返回 404。
• GET /api/v1/admin/observability/runs/{source}/{run_id}/trajectory/{entry_id}：读取一条模型、工具或工作流节点快照。

依赖聚合（Dependencies）

端点：GET /api/v1/admin/observability/dependencies

接受与 summary 相同的时间窗口参数。返回 models、tools 与 retrieval 三组聚合，每组包含请求数、完成数、失败数、成功率、p50/p95 延迟、Token 与样本数（模型组另含首 Token p95）。

队列与基础设施快照（Queues & Infrastructure）

• GET /api/v1/admin/observability/queues：当前队列与 Worker 的有界快照，无查询参数。
• GET /api/v1/admin/observability/infrastructure：有界基础设施快照、依赖健康状态与安全显示的 pg_stat_statements 慢查询，无查询参数。缺失的探针报告为 unknown，不可用的统计不伪装成 0。

运维细节

队列快照按需采集（非常驻后台任务），带 5 秒的按 API 进程缓存：Celery 检查用独立 inspector 并发采集活跃任务、预留任务、定时任务与活跃队列，每个检查的回复收集超时为 0.5 秒，整个检查阶段的总期限为 2.2 秒；Redis 队列长度随后并发读取。

基础设施快照同样带 5 秒的按 API 进程缓存（页面 30 秒刷新一次）：主健康采样、实例注册表读取、慢查询统计各自期限为 2 秒；Celery 沿用 1.5 秒期限，其中回复收集占 0.5 秒，Celery 延迟包含回复收集时间。实例发现或慢查询失败不掩盖依赖健康：发现失败返回空实例与部分元数据，而不伪造仅本地列表。

每个 API 实例身份每 10 秒向共享 Redis 上报一次资源采样，同一身份的 Gunicorn 进程通过可续期、带属主校验的租约选举出唯一的汇报者。以 Redis 服务端时间为准判断新鲜度：30 秒内的采样保留实测健康状态，超过 30 秒标记为 stale，超过 60 秒标记为 offline；旧值与时间戳保留可见但标记为非当前，5 分钟无成功发布后记录消失。

Span 上限：每个 Agent 运行最多保留 128 个依赖 span，超限时运行详情会标记 trace 不完整；工作流详情最多保留 100 个节点 span，同样会报告不完整；历史运行不回填。

运行摘要为尽力而为的遥测，AgentRun 记录为准：API 维护任务每分钟对账一次，每批最多 100 条；运行在记录的结束时间 60 秒后才符合对账条件，且只在 30 天遥测保留期内；对账从运行记录与最终消息恢复状态、耗时、模型与 Token 字段并保留已采集的依赖 span，不改动进行中的运行、不重放模型/工具调用，大积压需要多个周期消化，缺失或已过期的历史摘要行不会重建。

告警（Alerts）

列表端点：GET /api/v1/admin/observability/alerts

告警事件字段：id、rule_id、kind、severity（critical、warning、info）、title、detail、affected_count、status（active、resolved）、opened_at、resolved_at、acknowledged_at、silenced_until。

告警操作（均需 admin:observability:manage 权限，对已解决或不存在的告警返回 404）：

• POST /api/v1/admin/observability/alerts/{alert_id}/acknowledge：确认告警。
• POST /api/v1/admin/observability/alerts/{alert_id}/silence?duration_seconds=...：静默告警，duration_seconds 必填，取值 60–604800（1 分钟至 7 天）。

规则端点：

• GET /api/v1/admin/observability/alerts/rules：列出告警规则（读取权限即可）。
• PUT /api/v1/admin/observability/alerts/rules/{rule_id}：更新规则（需 admin:observability:manage）。请求体字段均为可选：threshold（0–1）、enabled、evaluation_window_seconds（60–604800）、recovery_window_seconds（60–604800）。规则不存在返回 404。

记录边界

• 运行摘要保存在紧凑索引记录中，保留 30 天；无提交时间戳的历史运行不回填。
• 运行摘要只写白名单字段：时序、状态、模型名、Token 数、资源/团队标识符与错误代码。工具入参与结果、模型与节点轨迹等诊断载荷按需单独存储并设大小上限（单条工具载荷最大 256 KiB，超限只标记未记录），可能包含用户消息、检索文档与工具输出——因此 admin:dashboard:access 等同于敏感运行内容的访问权限，而不只是聚合指标。
• 新 Agent 记录包含模型聚合与安全的运行根 span；工具与检索子 span 已采集，每个运行最多保留 128 个依赖 span，超出时标记 trace 不完整，历史运行不回填。