Skip to content

debug-tracing.md

Latest commit

 

History

History
110 lines (87 loc) · 4.51 KB

debug-tracing.md

File metadata and controls

110 lines (87 loc) · 4.51 KB
Raw

Workspace debug tracing

Context debug tracing is an explicit, workspace-local observation mode. It is disabled by default. It does not change Agent Graph facts, route selection, human gates, command eligibility, lifecycle writes, or command exit status.

Enable it while initializing a workspace:

context init context --debug

Or enable it later:

context debug enable

Both forms set package.json context.debug to true. Disabling tracing removes that property but keeps the existing trace for inspection:

context debug disable

Files

Tracing writes only below the ignored workspace .tmp directory:

.tmp/context-runtime/debug/
├── events.jsonl
├── state.json
└── replay.json
  • events.jsonl is the append-only source of truth. Each line conforms to context.debug.event.v1.
  • state.json owns the trace id, monotonic sequence, and last observed graph state. It is recorder state, not workflow state.
  • replay.json is a disposable projection produced by context debug export and conforms to context.debug.replay.v1.

No command stdout, source body, knowledge page, or resource body is copied into the trace. Sensitive option values are redacted. Command receipts contain only status, duration, byte counts, and hashes already available to the managed runner.

Event model

The event stream records:

  • CLI invocation and completion, including parent invocation identity for managed child commands;
  • Agent Graph evaluation revision, status, selected route, alternatives, and whether the observable graph position changed;
  • managed workflow action start and completion with deterministic receipts;
  • execution-scope open and close events, including whether a deterministic action ran in-process or in a child process and whether every short-lived resource was released; normal project write-lock open/close pairs are omitted, while release failures remain visible;
  • performance measurements: errors and operations taking at least one second are written immediately. Short successful operations inside a CLI invocation are aggregated into cli.completed.data.performance by operation and relevant cache/read mode (and requested operation for locks). Each total includes count, summed duration, maximum duration, and summed counters. It excludes the slow/error events already written individually; add those when computing an operation total. Direct SDK calls outside a CLI invocation retain individual measurements;
  • the reason and graph position at which a managed loop stopped.

trace_id groups the workspace-local debug history, sequence defines replay order, invocation_id groups work performed by one CLI process, and parent_invocation_id connects managed child commands to their runner. A UI can animate agent-graph.evaluated events whose data.transition.changed is true, then associate intervening command and action events by sequence and invocation identity.

Execution-scope events are runtime evidence, not workflow facts. They make resource ownership and cleanup observable without changing a Route or adding workspace state. Durable knowledge mutations are still audited through the normal action receipt, revision, close, and verify results.

Performance summaries live only in command memory until normal or error completion; there is no background writer or extra persistent queue. Abruptly killed commands may lack their short-operation summary, but invocation, slow-operation and error events already written remain available. Summary groups are bounded; overflow measurements are recorded individually. Operation durations can be nested, so their sum is not total CLI wall time. In particular, write-lock hold time includes the protected operation; acquisition duration identifies lock contention.

Inspect and export

context debug status --format json
context debug export --format json

Status returns configuration, event counts, and relative trace paths. Export mechanically derives a replay document containing the complete event stream and its changed graph transitions. A custom export path must remain below the workspace .tmp directory:

context debug export --output .tmp/analysis/replay.json --format json

Recorder failures are intentionally non-fatal. They can make a trace incomplete, but they cannot alter the command being observed. Consumers should therefore validate monotonic sequence values before presenting a replay as complete.