> ## 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.

When you set a probe in VS Code, HyperProbe handles everything between your editor and your running application automatically. The VS Code extension registers your probe with the backend, the SDK agent embedded in your application instruments the target line, and captured data flows back to your editor. No restarts, no redeployments, no paused threads.

***

## The Probe Lifecycle

<Steps>
  <Step title="Setting 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="Agent Probe Retrieval">
    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="Asynchronous Execution Hook">
    When execution hits the instrumented line, the agent captures variables, logs, counters, or metrics. **The agent never pauses application threads.**
  </Step>

  <Step title="Telemetry Enqueue & Flush">
    Captured telemetry is queued in-memory and flushed to the broker in asynchronous batches, ensuring zero impact on application request paths.
  </Step>

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

***

## 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.

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

***

## Architectural Topology

<Frame>
  <img src="https://mintcdn.com/hypertest-cee1a811/kV6wEn8JLwpRaN7D/images/architecture.svg?fit=max&auto=format&n=kV6wEn8JLwpRaN7D&q=85&s=ee37ce8e6e64a92d88f1fe951248ea70" alt="HyperProbe Architectural Topology" 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.