SOP 可观测性与审计

本页介绍 SOP 执行证据的存储位置以及如何检查它。

1. 审计持久化

SOP 审计条目通过 SopAuditLogger 持久化到配置的 Memory 后端，类别为 sop。

常见的密钥模式：

sop_run_{run_id}：运行快照（开始 + 完成更新）
sop_step_{run_id}_{step_number}：每步结果
sop_approval_{run_id}_{step_number}: 操作员审批记录
sop_timeout_approve_{run_id}_{step_number}：超时自动审批记录

2. 检查路径

2.1 运行日志

每个在 SOP 步骤内发出的提供方调用、工具调用和生命周期事件，都会继承稳定的 zeroclaw.sop_run_id 归属标识。网关的运行详情页将这些事件以时间线形式展示。CLI 和 ZeroCode 的日志面板查询的是同一份持久化且已脱敏的运行时追踪数据，而不是各自维护独立的 SOP 日志存储：

每个已完成、失败或跳过的步骤还会发出一个结构化结果事件。其 message 包含简短的结果摘要，attributes.output 包含最多 4,096 个字符的已清除凭据的输出，以及步骤编号、状态、实际生效的 agent 和捕获的工具调用次数。规范的、未截断的步骤结果保留在 SOP 审计记录中；有界投影则确保共享运行时日志可以安全地渲染和搜索。

sh

zeroclaw sop logs <run-id>
zeroclaw sop logs <run-id> --limit 500 --json

在 ZeroCode 中打开日志页面，按 r 输入运行 ID；按 R 清除运行过滤器。API 客户端可以使用 GET /api/logs?sop_run_id=<run-id>，并像其他日志查询一样使用 next_cursor_line_offset 进行分页。

读取器包含一个狭义的兼容桥接层，用于处理在 zeroclaw.sop_run_id 出现之前写入的事件，即这些记录携带 attributes.run_id 或旧版 SOP 审计开始/结束消息的情况。较早运行中从未携带运行 ID 的 Provider 和工具事件无法重建。

Run 日志遵循运行时追踪配置的持久化与保留策略。网关仅读取当前活动的 JSONL 文件，因此在滚动修剪或轮转之后，较旧的运行可能没有任何保留的记录。UI 和 CLI 会在持久化被禁用时进行提示；轮转后的归档文件仍作为离线诊断产物保留。

使用 observability-otel 构建并设置 backend = "otel" 时，同样的规范事件也会以标准 OTLP/HTTP protobuf LogRecord 形式导出。Provider、工具和步骤记录会将 zeroclaw.sop_run_id 保留为 OTel 属性，因此 collector 或供应商可以查询同一次运行，而无需替换本地仪表板、CLI 和 TUI 路径。参见日志与可观测性。

2.2 定义级 CLI

sh

zeroclaw sop list
zeroclaw sop validate [name]
zeroclaw sop show <name>

2.3 运行时运行状态工具

SOP 运行状态是从代理内工具中查询的：

sop_status：活动/已完成的运行以及可选指标
sop_status 启用 include_gate_status: true：信任阶段和门控评估器状态（可用时）
sop_approve：批准等待中的运行步骤
sop_advance：提交步骤结果并推进运行

3. 指标

当 [observability] backend = "prometheus" 时，/metrics 会暴露观测指标。
当前导出的名称为 zeroclaw_* 系列（通用运行时指标）。
通过 sop_status 并设置 include_metrics: true 可以获取特定 SOP 的聚合数据。

Keyboard shortcuts

ZeroClaw Docs