SOP Observabilidad y Auditoría

Esta página cubre dónde se almacena la evidencia de la ejecución de SOP y cómo inspeccionarla.

1. Persistencia de auditoría

Las entradas de auditoría de SOP se persisten a través de SopAuditLogger en el backend de memoria configurado, categoría sop.

Patrones de clave comunes:

• sop_run_{run_id}: instantánea de ejecución (actualizaciones de inicio y finalización)
• sop_step_{run_id}_{step_number}: resultado por paso
• sop_approval_{run_id}_{step_number}: registro de aprobación del operador
• sop_timeout_approve_{run_id}_{step_number}: registro de aprobación automática por tiempo de espera

2. Rutas de inspección

2.1 Registros de ejecución

Cada llamada al proveedor, llamada a herramienta y evento de ciclo de vida emitido dentro de un paso de SOP hereda la atribución estable zeroclaw.sop_run_id. La página de detalle de ejecución de la puerta de enlace muestra estos eventos como una línea de tiempo. La CLI y el panel de registros de ZeroCode consultan la misma traza de ejecución persistida y depurada, en lugar de mantener almacenamientos de registros de SOP independientes:

Cada paso completado, fallido u omitido también emite un evento de resultado estructurado. Su message contiene un breve resumen del resultado, y su attributes.output contiene hasta 4.096 caracteres de salida depurada de credenciales, junto con el número de paso, el estado, el agente efectivo y el recuento de llamadas a herramientas capturadas. El resultado completo y sin truncar del paso permanece en el registro de auditoría de SOP; la proyección acotada mantiene seguro para mostrar y buscar el registro de ejecución compartido.

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

En ZeroCode, abre Logs y pulsa r para introducir un ID de ejecución; pulsa R para borrar el filtro de ejecución. Los clientes de API pueden usar GET /api/logs?sop_run_id=<run-id> y paginar con next_cursor_line_offset igual que con cualquier otra consulta de logs.

El lector incluye un puente de compatibilidad acotado para los eventos escritos antes de que existiera zeroclaw.sop_run_id, cuando esas filas contenían attributes.run_id o un mensaje heredado de inicio/fin de auditoría de SOP. Los eventos de proveedor y de herramienta de ejecuciones anteriores no pueden reconstruirse si nunca contuvieron el ID de ejecución.

Los registros de ejecución siguen la política de persistencia y retención configurada para la traza de tiempo de ejecución. La gateway lee únicamente el archivo JSONL activo actual, por lo que una ejecución suficientemente antigua puede no tener filas retenidas tras el recorte continuo o la rotación. La UI y la CLI informan cuando la persistencia está deshabilitada; los archivos rotados permanecen como artefactos de diagnóstico sin conexión.

Una compilación de observability-otel con backend = "otel" también exporta estos mismos eventos canónicos como LogRecords estándar de OTLP/HTTP en formato protobuf. Las filas de proveedor, herramienta y paso conservan zeroclaw.sop_run_id como atributo de OTel, de modo que un colector o proveedor puede consultar la misma ejecución sin reemplazar la ruta local de panel/CLI/TUI. Consulte Logs y observabilidad.

2.2 CLI a nivel de definición

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

2.3 Herramientas de estado de ejecución en tiempo de ejecución

El estado de ejecución de la SOP se consulta desde las herramientas del agente:

• sop_status: ejecuciones activas/finalizadas y métricas opcionales
• sop_status con include_gate_status: true: fase de confianza y estado del evaluador de puertas (cuando esté disponible)
• sop_approve: aprobar paso de ejecución en espera
• sop_advance: enviar el resultado del paso y avanzar la ejecución

3. Métricas

• /metrics expone las métricas de observación cuando [observability] backend = "prometheus".
• Los nombres exportados actualmente son las familias zeroclaw_* (métricas generales del tiempo de ejecución).
• Los agregados específicos de SOP están disponibles a través de sop_status con include_metrics: true.