Skip to main content
This page answers the most common questions from developers setting up and using HyperProbe. If you run into an error with a specific message, see Common errors and solutions for step-by-step fixes.
No. All instrumentation is fully asynchronous — HyperProbe never pauses your application to capture data and does not use debugger statements. Built-in safety guardrails monitor overhead in real time and automatically suspend instrumentation if any threshold is breached.The three guardrails you can tune are:
OptionDefaultWhat it controls
hitsPerSec10Maximum probe executions per second
bandwidthKbPerSec200 KB/sMaximum telemetry data throughput
maxLagMs50 msMaximum tolerated instrumentation pause duration
If the agent enters RED status (overhead too high), instrumentation suspends automatically and resumes after the cooldown period (default 10 seconds). See Safety guardrails for full details.
Yes, if your code runs directly without compilation or bundling — for example, a plain Node.js project with no build step. In that case, HyperProbe resolves line numbers directly from your source files.For TypeScript projects, compiled JavaScript, or bundled output (webpack, esbuild, Rollup), source maps are required for accurate line number resolution. Without them, probes may resolve to incorrect lines in your compiled output rather than your source files.
Point sourceMapDir at your compiled output directory (e.g., ./dist) so the agent can find your .js.map files automatically on startup.
HyperProbe does not enforce a hard limit on the number of active probes at the extension or backend level. Each probe adds a small amount of instrumentation overhead, so the practical limit depends on how frequently each probed line executes in your application.Start with a small number of probes (two to five) and monitor the agent’s health status in the extension. If you see YELLOW or RED safety states, reduce the number of active probes or lower hitsPerSec to spread the load.
HyperProbe captures only the local variables and expressions in scope at the exact line you instrumented. It does not log request bodies, trace all function calls, or collect system metrics.Sensitive fields are automatically redacted before any data leaves your process. By default, the following key names are redacted from captured objects:
password, secret, token, authorization, cookie, key, signature
You can extend this list using the redactKeys option (or HYPERPROBE_REDACT_KEYS environment variable) and add value-level patterns with redactValues.
Redaction happens in-process, inside the agent, before data is sent to the broker. Sensitive values never leave your application.
It depends on which SDK you use:
  • Node.js SDK — requires a single HyperProbe.start() call at your application’s entry point. No other code changes are needed.
  • Java agent — requires no code changes. Add the -javaagent JVM flag to your startup command and the agent instruments your bytecode automatically.
Neither SDK requires you to annotate functions, wrap code blocks, or modify the logic you want to debug.
An orange indicator means the probe is registered in the backend but no active agent has connected for that service and environment yet.Check the following:
1

Verify the SDK agent is running

Confirm that HyperProbe.start() is being called in your target service and that the process is running without startup errors.
2

Check the broker URL

Ensure the brokerUrl passed to HyperProbe.start() is reachable from your application. Network policies or misconfigured URLs are the most common cause.
3

Confirm the serviceId matches

The serviceId in your SDK call must exactly match the serviceId in your .hprc file. A mismatch causes the extension and the agent to operate as if they belong to different services.
4

Check the environment selector

Make sure the environment selected in the extension (e.g., production, staging) matches the environment value passed to HyperProbe.start().
Once an agent connects and the probe is live, the indicator turns green.
Probes have a finite lifetime. If the code at the probed line is never executed within that window, the probe expires without capturing anything and its status changes to EXPIRED.Common reasons the line may not have executed:
  • The endpoint or code path was never triggered during the probe’s lifetime.
  • The probe was placed on a branch (e.g., an else block or error handler) that wasn’t reached.
  • The agent hadn’t yet synced the probe before the lifetime elapsed. The agent syncs every 60 seconds by default.
If you need to capture data from an infrequently executed path, create a new probe and make sure to trigger the relevant code path before the probe expires.
The extension connects to your HyperProbe backend using the URL configured in hyperprobe.serverUrl (default: http://localhost:3001).
1

Check the configured URL

Open VS Code settings (Ctrl+, / Cmd+,) and search for hyperprobe.serverUrl. Verify it points to the correct backend address.
2

Verify the backend is running

The extension performs a health check at GET /health on the configured URL. Open that URL in your browser or run:
curl http://your-backend:3001/health
It should return a 200 OK response.
3

Check for network or firewall issues

If the backend is on a remote host, ensure your machine can reach it. VPN configurations and firewall rules are common causes of connection failures in remote or cloud environments.
Yes. When creating a probe, set Hit Limit to a value greater than 1. Each time the instrumented line executes, HyperProbe captures a snapshot and decrements the remaining hit count.For example, set a hit limit of 10 to collect up to ten snapshots from the same line. Once the limit is reached, the probe transitions to COMPLETED status and instrumentation stops automatically.
Use a hit limit greater than 1 when debugging intermittent behavior — you can collect several executions and compare variable state across them.
The default maxObjectDepth is 3. Objects nested deeper than this are truncated to prevent large captures from adding meaningful overhead to your production application. The architecture also enforces a maximum snapshot size of 2 MB.If you need deeper inspection, increase maxObjectDepth in your SDK configuration:
HyperProbe.start({
  // ...required options
  maxObjectDepth: 5,
  maxObjectProperties: 100,
});
Alternatively, use Watch Expressions in the probe configuration to capture a specific nested property by path rather than the entire root object.
The SDK uses the debug package. Set the DEBUG environment variable before starting your application to enable logs for specific subsystems:
# All HyperProbe logs
DEBUG=hyperprobe:* node dist/index.js

# Individual namespaces
DEBUG=hyperprobe:agent   # General agent lifecycle and probe activity
DEBUG=hyperprobe:broker  # Broker communication and sync cycles
DEBUG=hyperprobe:safety  # Safety guardrail events and state changes
DEBUG=hyperprobe:stats   # Probe hit and skip counts (logged every 5 seconds)
Start with hyperprobe:agent and hyperprobe:broker to diagnose most connectivity and sync issues. Add hyperprobe:safety if you suspect the agent is suspending instrumentation due to overhead.