Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

SOP 可観測性と監査

このページでは、SOP 実行の証拠がどこに保存されているか、およびそれを検査する方法について説明しています。

1. 監査永続化

SOP 監査エントリは SopAuditLogger を介して構成されたメモリバックエンドに永続化され、カテゴリ 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 ログストレージを保持せず、同じ永続化・スクラブ済みのランタイムトレースを参照します。

Each completed, failed, or skipped step also emits a structured result event. Its message contains a short result summary and its attributes.output contains up to 4,096 characters of credential-scrubbed output, together with the step number, status, effective agent, and captured tool-call count. The canonical untruncated step result remains in the SOP audit record; the bounded projection keeps the shared runtime log safe to render and search.

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 が記録されていなかった古い実行のプロバイダーイベントおよびツールイベントは、再構築できません。

Run logs は runtime trace に設定された永続化と保持ポリシーに従います。gateway は現在アクティブな JSONL ファイルのみを読み取るため、十分に古い run は、ローリングトリムまたはローテーションの後に保持された行が存在しない場合があります。UI と CLI は永続化が無効になっている場合にそれを報告します。ローテーション済みのアーカイブは、オフラインの診断用アーティファクトとして残ります。

observability-otel ビルドで backend = "otel" を指定すると、同じ正規イベントを標準の OTLP/HTTP protobuf LogRecord としてもエクスポートします。プロバイダー、ツール、ステップの行には zeroclaw.sop_run_id が OTel 属性として保持されるため、コレクターやベンダーは同じ実行を照会でき、ローカルのダッシュボード/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. メトリクス

  • /metrics は [observability] backend = "prometheus" の場合にオブザーバーメトリクスを公開します。
  • 現在エクスポートされている名前は zeroclaw_* ファミリー (一般的なランタイムメトリクス) です。
  • SOP 固有の集計は sop_status (with include_metrics: true) を通じて利用可能です。