Capture and replay an execution

Capture a development request through DRC, find its execution ID, replay it, and inspect the first divergence.

Initialize each service

Capture is organized per service, and each service needs its own initialization and port capture. Run drc init in the service's own codebase root once. It writes the service identity into .drc/drc.toml; give the service a stable name with --service so its executions are easy to find later:

cd path/to/your/service
drc init --service checkout-api

A system with several services (an API, a worker, a database) initializes each service root separately. Each service is then captured on its own ports, so replays, comparisons, and Signals stay scoped to one service at a time.

Start capture

Assume the service listens on port 3000:

drc run --port 8080 --target-port 3000

drc run proxies the service's traffic on port 8080 to the application on port 3000 and runs as a background daemon. Send development traffic through the proxy; each request is recorded as an execution for this service.

For a service that listens on several ports, add only the ports that are part of the test:

drc run --port 8080 --target-port 3000 \
  --extra-port 5432 --extra-port 6379

Watch the live event stream while traffic flows, then stop the daemon and flush its buffer when the scenario finishes:

drc watch
drc stop --flush

Never capture production secrets or customer payloads without an approved data policy.

Find the execution

drc search --service checkout-api --format table

Use JSON for automation, or omit --service to search every service in the workspace:

drc search --format json

The execution ID is the stable handle used by trace, replay, diff, share, and hosted investigation workflows.

Replay the execution

drc replay <execution-id>

Strict replay validates the captured event stream before replaying it. The output includes the execution ID, replay mode, storage authority, events loaded, and events replayed.

Inspect the first divergence

drc diff <baseline-id> <candidate-id>
drc trace <execution-id>

A divergence identifies the earliest observable difference; it is not automatically a root-cause claim. Use the surrounding trace and event metadata to investigate the cause.

Use the result in CI

drc replay <execution-id> --json

Treat the JSON status and exit code as the contract. Do not parse human-oriented table output in CI.

Hosted investigations

Team and Enterprise workspaces add tenant-scoped comments, assignees, browser timeline, OpenTelemetry correlation, external issue links, and resolution history. Open the hosted execution by ID to move from a report to an exact replay without copying raw payloads into a ticket.

Retention

Execution payload retention depends on the configured policy. Pin or export evidence before a retention boundary when the execution must remain available for an investigation or audit.

Next: configure Continuous Verification and Continuous Compliance in [.drc/signal.yml](signal-yml.md).