Error Tracing — Inline Diagnostics & Fix Hints

DebuggAI’s Error Tracing overlays real‑time diagnostics in your editor.
When runtime errors, failing tests, or type‑checking exceptions flow through our SDK, the extension re‑maps them to your current working copy and marks the exact lines with a red underline. Hover the squiggle to read a concise explanation of what went wrong and a ranked list of fix strategies.

---

Why it matters

Traditional flow	With Error Tracing
Run code → inspect console → find file/line manually	Buggy line is highlighted instantly
Search docs / Stack Overflow	Hover tooltip summarizes root cause
Figure out a fix yourself	Click “Apply Fix” in tooltip or open PR patch

---

Prerequisites

Component	Minimum Version	Install / Enable
DebuggAI VS Code Extension	≥ 0.6.0	Marketplace → DebuggAI
DebuggAI JetBrains Plugin	≥ 0.3.0	Preferences → Plugins
Runtime SDK	≥ 0.9.0	npm i @debuggai/sdk / pip install debuggai
Language server	Built in	Extension spins up an LSP bridge automatically

💡 Dev Containers & Codespaces are auto‑detected; no special setup.

---

How to use

1. Run your app as usual (npm run dev, pytest, etc.).

2. The DebuggAI SDK ships stack traces to the backend.

3. The extension polls for new diagnostics and overlays them:

   • Red squiggle – blocking runtime crash
   • Orange – deprecation / high‑impact warning
   • Blue – performance hint

4. Hover ‑→ Tooltip appears:

   NullReferenceError: 'user' is undefined when calling .email
   
   • Check that 'user' is assigned before line 87
   • If optional, guard with `if (user)`
   • Consider using the `?` optional‑chaining operator

5. Click “Fix it” (when available) to insert a quick patch, or “View RCA” to open the full root‑cause analysis in the side panel.

---

Configuration

Add overrides in settings.json (VS Code) or Settings → Tools → DebuggAI (JetBrains):

Setting	Default	Description
debuggai.diagnostics.enabled	true	Master toggle
debuggai.diagnostics.pollInterval	2000 ms	How often to fetch new errors
debuggai.diagnostics.severityFilter	"error,warning"	Comma‑separated list (info, hint)
debuggai.diagnostics.maxTooltipItems	3	Number of suggestions shown

Example VS Code snippet:

{
  "debuggai.diagnostics.severityFilter": "error,warning,info",
  "debuggai.diagnostics.maxTooltipItems": 5
}

---

How it works

1. Error ingestion – Runtime events arrive with file path, line, column, commit SHA.
2. Source mapping – The backend aligns traces with your repo; the extension checks out the matching file revision in memory.
3. Embedding + Retrieval – We embed the stack + code context, search for similar issues, and generate a Root‑Cause Analysis (RCA) using GPT‑4o.
4. LSP push – Diagnostics are streamed to the extension over WebSockets; we implement the textDocument/publishDiagnostics method to paint squiggles.

Privacy – Only stack traces and surrounding 200 LOC are sent; never full repo.

---

Tips & Tricks

• Quick fix shortcut – ⌘ . (macOS) or Alt + Enter (JetBrains) triggers the first suggested fix without opening the tooltip.
• Link to Slack – Hover tooltip → Copy link to share a permalink to the RCA with your team.
• Unit‑test mode – Enable DEBUGGAI_TEST_MODE=1 to surface diagnostic hints while running Jest/PyTest, even if the app didn’t crash.

---

Troubleshooting

Issue	Solution
Squiggles show but tooltip is empty	Check extension logs (DebuggAI: Show Logs) for blocked API calls; ensure your token is valid.
Diagnostics lag behind code edits	Increase pollInterval or run the SDK in local direct mode (export DEBUGGAI_MODE=direct).
No squiggles at all	Verify the SDK is initialized (console.info("DebuggAI onLine")). Look for “Diagnostics channel connected” in extension output.

---

Next Up

• Live Replay – click “Replay request” in tooltip to open a sandbox with identical inputs.
• Autofix PR – promote a quick fix to a branch + PR for code review.
• Telemetry Dashboards – aggregate diagnostic counts per file or team.

Jump to Jump to Error › if you’d rather hop straight from terminal to the problem line.

---

Debug smarter, ship faster 🚀.