DRC
tutorial developer public

Quickstart

This tutorial takes you from a local service to a captured execution, a structured analysis result, and an optional hosted replay job.

What you are building


service → DRC capture → execution ID → replay/trace/diff → human review

DRC stores execution data for replay and analysis. Choose a capture path that observes the boundaries relevant to your application.

Prerequisites

Install the CLI from source


cargo build --manifest-path drc-rust/Cargo.toml --locked --release -p drc-cli
export PATH="$PWD/drc-rust/target/release:$PATH"
drc --version

The CLI is a Rust binary. Release builds use the workspace release profile; see deployment for packaged and service deployment paths.

Initialize a project


drc init \
  --codebase . \
  --language auto \
  --non-interactive \
  --telemetry off \
  --auto-update off

drc init detects common Node.js, Python, Go, Rust, Ruby, PHP, Java, and C# project families when the relevant project files are present. Framework detection is intentionally conservative; verify the generated configuration before capture.

Capture through the transparent proxy

If the application already listens on port 3000, place DRC on port 8080:


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

Send traffic to http://127.0.0.1:8080. For a second dependency port, repeat --extra-port:


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

Available capture modes are headers-only, metadata-plus, full-body, and sample. Use --sample-rate 0.1 with sample to request a 10% sample. Avoid full-body capture until redaction and retention have been reviewed.

The daemon runs in the background. Watch or stop it with:


drc watch --filter error
drc stop --flush

Local analysis

List local executions:


drc search --service checkout --format json

Trace one execution:


drc trace EXECUTION_ID --json

Replay an event stream in strict mode:


drc replay --execution-id EXECUTION_ID --mode strict

Compare two execution IDs:


drc diff BASELINE_ID CANDIDATE_ID --show-fields --format json

Find the first divergence between a baseline and mutated execution:


drc bisect --baseline BASELINE_ID --mutated MUTATED_ID --json

Scan local history for a similar pattern:


drc blast-radius --execution-id EXECUTION_ID --max-scan 100 --json

Result semantics

A successful event-stream comparison means that the captured event representations matched under the selected comparison rules. It does **not** prove that an application was re-executed successfully, that all side effects were captured, or that a deployment is safe. Incomplete, envelope-only, simulated, or unknown results must remain distinguishable from verified application behavior.

Counterfactual fix comparison

A fix spec describes a change to the captured envelope:


{
  "description": "Change the cache value used by the failing event",
  "changes": [
    {
      "event_sequence": 5,
      "field_path": "data.rate",
      "new_value": 1.0
    }
  ]
}

Run the comparison:


drc replay --execution-id EXECUTION_ID --fix fix.json --json

Interpret the result as a **counterfactual comparison**. It is not an independent application replay and does not establish production safety.

Hosted API path

Set credentials without putting them in shell history:


export DRC_API_URL="https://your-drc-api.example"
export DRC_API_KEY="..."

Check readiness:


curl -fsS "$DRC_API_URL/health/ready"

Create a capture envelope:


curl -fsS -X POST "$DRC_API_URL/api/v1/executions" \
  -H "Authorization: ApiKey $DRC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_name":"checkout","environment":"staging","tags":["candidate"]}'

Create a replay job and poll it until status is completed or failed:


curl -fsS -X POST "$DRC_API_URL/api/v1/replays" \
  -H "Authorization: ApiKey $DRC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"execution_id":"EXECUTION_ID","mode":"strict"}'

curl -fsS "$DRC_API_URL/api/v1/replays/JOB_ID" \
  -H "Authorization: ApiKey $DRC_API_KEY"

Hosted replay is asynchronous. Clients should persist the job ID, poll with backoff, treat retries as normal, and use the returned status and divergence fields rather than parsing human-readable messages.

SDK or API capture

Use an SDK when the proxy cannot observe the relevant boundary or when you need application-level event metadata. See SDK integration and API reference.

Evidence

Evidence signing is available to Team and Enterprise users in the authenticated Evidence workspace after execution and analysis are available.

Next steps