> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprobe.co/llms.txt
> Use this file to discover all available pages before exploring further.

# How It Works

> A deep-dive explanation of the HyperProbe lifecycle, instrumentation engine, and production safety guardrails.

HyperProbe supports two production debugging workflows. You can place and inspect probes manually in VS Code, or let an MCP-connected coding agent investigate an incident and produce an evidence-backed Root Cause Analysis (RCA). Both workflows use the same runtime instrumentation and safety controls, with no restarts, redeployments, or paused threads.

***

## The Probe Lifecycle

Choose how you want to drive the investigation:

<Tabs>
  <Tab title="Manual with VS Code">
    <Steps>
      <Step title="Set a Probe in VS Code">
        Right-click any line in an open source file and choose a probe type — **Snapshot, Log, Counter, Metric, or Tic & Toc**. The extension registers the probe definition with the broker.
      </Step>

      <Step title="SDK Agent Retrieves the Probe">
        The SDK agent polls the broker for active probes and dynamically instruments the target line in-memory. This happens live, with no process restarts.
      </Step>

      <Step title="Capture Runtime Data">
        When execution hits the instrumented line, the SDK agent captures variables, logs, counters, or metrics. **The agent never pauses application threads.**
      </Step>

      <Step title="Enqueue and Flush Telemetry">
        Captured telemetry is queued in a bounded in-memory buffer and flushed to the broker in asynchronous batches. Network I/O stays off the application request path.
      </Step>

      <Step title="Inspect Results in VS Code">
        The extension fetches the captured data and renders it inside your editor's **HyperProbe** panel, presenting complete variable trees and call stacks.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Agentic with MCP">
    <Steps>
      <Step title="Describe the Production Issue">
        Ask your MCP-connected coding agent to investigate an incident in natural language. The coding agent examines your local source, stack traces, and incident context to identify the relevant execution path.
      </Step>

      <Step title="Plan and Verify the Investigation">
        The coding agent forms testable hypotheses and selects targeted probe locations. HyperProbe verifies the service, environment, and deployed commit before collecting runtime evidence.
      </Step>

      <Step title="Collect Live Evidence">
        The coding agent places short-lived, bounded probes through MCP. When relevant production traffic reaches those lines, the SDK agent captures live variables and call stacks and returns them as investigation evidence.
      </Step>

      <Step title="Analyze and Iterate">
        The coding agent correlates runtime evidence with your source code, updates its hypotheses, and can place focused follow-up probes. If matching traffic has not arrived, the investigation waits for evidence instead of guessing.
      </Step>

      <Step title="Produce an Evidence-Backed RCA">
        The coding agent returns a **Confirmed**, **Probable**, or **Inconclusive** RCA with supporting findings, captured evidence, limitations, and a recommended remediation. It can then propose a minimal fix and regression tests for your approval.
      </Step>
    </Steps>

    Learn how to connect your coding agent in the [AI-native debugging with MCP guide](/ai-native/mcp-server).
  </Tab>
</Tabs>

***

## Runtime Instrumentation Mechanics

HyperProbe does not modify your source files or your deployed build artifacts. Instead, it hooks into the runtime's native introspection capabilities:

* **Node.js (V8):** The Node SDK connects to the V8 debugger runtime using the native `inspector` protocol. It places virtual break-hooks on specific compiled script locations. When hit, the callback grabs the local scope and call stack, returning control in **microseconds**.
* **Java (JVM):** The Java Agent attaches via the standard `-javaagent` flag. It performs lightweight, runtime bytecode manipulation using byte code libraries to inject capture instructions on-the-fly.
* **Python (CPython):** The Python SDK uses the `sys.monitoring` API available in Python 3.12 and later. It listens for line events, reads the active frame to capture locals and the call stack, and then enqueues bounded telemetry for asynchronous delivery. It does not rewrite source files, patch frameworks, or use `sys.settrace`.

Because instrumentation happens at the engine layer, HyperProbe maps compiled output back to original source coordinates seamlessly as long as **source mappings** (Node.js) or debug symbols (Java) are provided. No special handling required in Python.

***

## Architectural Topology

The VS Code extension and MCP-connected coding agents are two developer clients for the same HyperProbe backend. Both create probes through the broker and consume telemetry captured by the in-process SDK agent.

<Frame>
  <img src="https://mintcdn.com/hypertest-cee1a811/cHWd4cEMrq8SXZlC/images/architecture.svg?fit=max&auto=format&n=cHWd4cEMrq8SXZlC&q=85&s=d4e080f75fea87838ca74a1e61a47f93" alt="HyperProbe architecture for VS Code and MCP clients" width="800" height="400" data-path="images/architecture.svg" />
</Frame>

***

## Built-In Safety Guardrails

The SDK agent runs a continuous safety monitor alongside your host application to prevent resource contention or performance impact:

* **Overhead Suspension:** The agent tracks event loop lag and CPU usage. If thresholds are crossed, all probes are immediately suspended and the agent enters a cooldown status before automatically resuming.
* **Global Throughput Throttling:** Limits the maximum number of captures per second. Hits beyond this ceiling only increment the execution counter and bypass data serialization to save resources.
* **Strict Payload Boundaries:** Snapshots are restricted by maximum object depth, array length, and string size to ensure minimal memory usage.
* **Local and Global Hit Limits:** Each probe has a configurable hit limit. Once reached, its instrumentation is automatically and instantly uninstalled.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.