Observability

March 4, 2026 · View on GitHub

本页说明 Job 执行可观测（Execution Trace UI、时间线、节点延迟与重试原因）。HTTP 请求级 OpenTelemetry 见 tracing.md。

Execution Trace UI

当 jobstore.type 为 postgres 或 API 使用事件存储时，可为单个 Job 打开 Trace 回放页，查看执行时间线、每步延迟、重试原因与节点输入输出。

Multi-job / agent aggregation page: GET /api/trace/overview/page?agent_ids=<a1,a2>
聚合多个 agent 的 Job 列表，并可一键跳转每个 Job 的 trace 页。
Step-level replay control: 在 GET /api/jobs/:id/trace/page 详情区可对当前选中 step 执行 replay 查询（调用 GET /api/jobs/:id/replay?step_node_id=<step>）。
State diff view: 详情区继续展示 state before/after、changed keys、external state changes（来自 state_checkpointed）。

URL：GET /api/jobs/:job_id/trace/page（需替换 :job_id 为实际 Job ID）。
示例：Job ID 为 job-xxx 时，在浏览器打开 http://localhost:8080/api/jobs/job-xxx/trace/page（若 API 启用了认证，需带 Cookie 或 Token）。
JSON 接口：GET /api/jobs/:job_id/trace 返回时间线与执行树 JSON，供自定义前端或脚本使用。
Step replay query：GET /api/jobs/:job_id/replay?step_node_id=<node_id> 返回 step_replay（该步 state/result 快照）。

时间线条：按时间顺序展示 plan、node、tool、recovery 等片段；每段可带 duration_ms、status（ok / failed / retryable）。
步骤列表：左侧步骤列表，点击可在右侧查看该步的 Step 详情（node_id、result_type、reason、duration_ms、attempts）、推理/决策（若有）、Tool 输入输出、状态变更 diff（state_checkpointed）。
执行树：可折叠的树形结构（job → plan → node → tool），与 design/execution-trace.md 对应。

字段	说明
duration_ms	该步执行耗时（毫秒）
result_type	世界语义：pure / success / side_effect_committed / retryable_failure / permanent_failure / compensatable_failure
reason	失败或重试原因（从 node_finished 等事件解析）
attempts	该步尝试次数

Trace 数据由事件流推导（ListEvents(job_id) → BuildExecutionTree + BuildNarrative），与 design/event-replay-recovery.md、design/execution-state-machine.md 一致。

若 API 未配置 JobEventStore（或 jobstore.type 为空），访问 trace 接口会返回 503 "Trace 未启用"。使用 Postgres 事件存储并正确注入 SetJobEventStore 后即可使用。

GET /api/observability/summary：返回 queue_backlog（按队列的 Pending 数）、stuck_job_ids（status=Running 且 updated_at 超过阈值的 job_id）、stuck_threshold_seconds。查询参数 older_than 可指定卡住阈值（如 1h），默认 1 小时。
GET /api/observability/stuck：仅返回 stuck_job_ids 与 stuck_threshold_seconds，与 summary 中 stuck 字段一致，便于脚本或前端直接消费。
Prometheus：aetheris_queue_backlog{queue="default"}、aetheris_stuck_job_count；调用 summary 接口时会同步更新这些指标。
Stuck Job 定义：Running 且 updated_at 早于 (now - threshold)；可能表示 Worker 卡死或未心跳，需结合 Reclaim 与租约过期处理。

调用 GET /api/observability/summary 或 GET /api/observability/stuck（可选查询参数 older_than，如 ?older_than=1h）。
从返回的 stuck_job_ids 中取需要排查的 job_id。
打开 GET /api/jobs/:id/trace/page（将 :id 替换为上述 job_id）查看该 Job 的执行时间线与步骤耗时，定位卡在何步、是否有重试或超时。

Trace 页与 GET /api/jobs/:id/trace 已提供按 step 的 timeline_segments（含 duration_ms），即 Job 时间线视图。