Request access

Debug Mode

Debug mode is the operator view for understanding why a request behaved the way it did. It focuses on trace-level evidence: route decision, run output, blocked checks, and replay candidate models.

During closed beta, treat debug mode as an engineering workflow for incident handling and quality checks.

What Debug Mode Is

Debug mode helps you answer:

  • What model was selected and why
  • Whether a request was blocked, rerouted, or completed
  • Which step added cost or latency
  • Which trace should be replayed for comparison

It is not a replacement for your application logs or SIEM pipeline.

When To Use Debug Mode

Use debug mode when:

  • A request output looks wrong and you need step-by-step context
  • A customer reports latency regressions
  • Spend increases and you need to find expensive traces quickly
  • Guardrails block traffic and you need to confirm the triggering reason

Safe Usage In Regulated Environments

Debug mode is designed for operational review, not unrestricted data browsing.

  • Keep metadata minimal and avoid direct PII values in trace labels
  • Use stable IDs (user_id, tenant_id, case_id) instead of raw personal fields
  • Limit debug access to members who handle incident response
  • Use replay for controlled comparison, not production-side retries

Example Flow

Create a trace, run the request, complete the trace, then open the debug workspace with the trace id.

const trace = await client.traces.create({
  metadata: { user_id: "usr_42", feature: "claims_review" }
});

const result = await client.execute({
  traceId: trace.data.id,
  input: "Summarize the attached claims note."
});

await client.traces.complete(trace.data.id);

// open the debug workspace for this trace
window.location.href = `/dashboard/debug?trace_id=${trace.data.id}`;
trace = client.traces.create(
    metadata={"user_id": "usr_42", "feature": "claims_review"}
)

result = client.execute(
    trace_id=trace["id"],
    input="Summarize the attached claims note."
)

client.traces.complete(trace["id"])

# open /dashboard/debug?trace_id=<id> in your dashboard session
trace = client.traces.create(
  metadata: { user_id: "usr_42", feature: "claims_review" }
)

result = client.execute(
  trace_id: trace["id"],
  input: "Summarize the attached claims note."
)

client.traces.complete(trace["id"])

# open /dashboard/debug?trace_id=<id> in the dashboard

Expected Output Shape

A debug trace includes workflow and safety detail. Typical fields:

{
  "id": "trace_123",
  "status": "completed",
  "intent": "claims_review",
  "totalCost": 0.0041,
  "optimizationGrade": "B",
  "routingDecision": {
    "decision": "economy-model",
    "metadata": {
      "selected_from": "project_policy",
      "reasoning": "medium complexity, low risk",
      "resolution": { "fallback_used": false }
    }
  },
  "forensics": {
    "blockedSteps": [],
    "guardrailChecks": [],
    "riskScore": 0.09
  },
  "steps": [
    { "type": "route", "model": null, "latencyMs": 11.8 },
    { "type": "run", "model": "economy-model", "cost": 0.0041, "latencyMs": 842.6 }
  ]
}

Next Steps

Edit this page
Was this page helpful?