# AI-Native Debugging with MCP
Source: https://docs.hyperprobe.co/ai-native/mcp-server
Use your favorite AI assistant (opencode, Cursor, Windsurf, Claude) to autonomously debug and trace production code using HyperProbe Model Context Protocol (MCP) workspace configuration.
HyperProbe is the world's first **AI-native production debugger**. By exposing the HyperProbe engine through a Model Context Protocol (MCP) server, LLM agents can autonomously inspect live running systems to diagnose production incidents, find bugs, and retrieve real-time state.
![AI Debugging Flow]()
***
## Configuring the MCP Server
### π Workspace-Level Isolation (Best Practice)
In professional environments, enabling the HyperProbe MCP server system-wide is not recommended. You should enable it **only inside the specific project workspace** you are actively debugging. This prevents environment variable leakage and ensures the debugger is only active when working on that specific codebase.
To configure, check your tool's documentation to add the HyperProbe server block to your workspace-specific configuration file:
Configure the server in your project's root `opencode.json` file. This locks the debugger strictly to this repository and checks it into Git for team collaboration.
*Note: opencode utilizes **`"environment"`** as the configuration key.*
```json opencode.json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"hyperprobe": {
"type": "local",
"command": ["npx", "-y", "@hyperprobe/mcp-server"],
"enabled": true,
"environment": {
"BACKEND_URL": "https://app.hyperprobe.co"
}
}
}
}
```
For other assistants (such as **Cursor**, **Windsurf**, **Cline**, or **Claude Desktop**), add this block to your tool's workspace-specific or folder-level settings file.
*Note: Most other coding assistants utilize **`"env"`** as the configuration key.*
```json config.json theme={null}
{
"mcpServers": {
"hyperprobe": {
"command": "npx",
"args": [
"-y",
"@hyperprobe/mcp-server"
],
"env": {
"BACKEND_URL": "https://app.hyperprobe.co"
}
}
}
}
```
**Important:** Remember to restart your coding agent (or reload your editor window) after adding the MCP configuration for the changes to take effect.
***
## The Case of the Mystery Stripe Webhook 500
It is 2 AM. Your phone buzzes with a high-severity Sentry alert: **`POST /api/stripe/webhook - 500 Internal Server Error`**.
The error occurs exclusively on subscription renewals. Regular checkout payments go through cleanly, but a handful of automated subscription renewals are failing silently. The stack trace points deep into your billing service: `TypeError: Cannot read properties of null (reading 'country')`.
Debugging third-party asynchronous webhooks is historically miserable:
* **No local reproduction:** You cannot easily replicate the exact Stripe customer state, payment history, and subscription variables locally.
* **No live attached debugger:** Running a debugger in production is out of the question due to blocking connections and latency overhead.
* **The log-deploy cycle:** Your only resort is adding print statements, redeploying, waiting for another renewal failure, and parsing raw logs.
With **HyperProbe + MCP**, you don't debug this. **Your AI Assistant does.**
### How the AI Assistant Autonomously Cracks the Case
When you configure your LLM agent with the HyperProbe MCP server, here is the exact, compressed flow of how it solves the incident:
1. **You ask the AI:** *"Sentry reports a 500 error on Stripe webhooks for renewals. Can you figure out why and fix it?"*
2. **The AI scans your codebase:** It automatically finds `src/webhooks/StripeWebhookHandler.ts` and inspects the database queries and billing logic.
3. **The AI places a probe:** It dynamically registers a conditional probe inside your running application to inspect local variables when a subscription renewal event arrives.
4. **Telemetry Capture:** When the next live renewal hits, HyperProbe captures the exact local variables in scope and sends them back to the AI without interrupting or slowing down your service.
5. **Diagnosis:** The AI inspects the variables and instantly catches the anomaly:
```json theme={null}
{
"user": {
"id": "usr_9A2X1",
"email": "legacy@old.com",
"address": null,
"isLegacyUser": true
}
}
```
**The root cause is revealed:** Users migrated from your legacy billing system do not have an `address` object populated in the database. The new tax calculation logic assumed `address` would always be present, throwing an exception.
6. **The AI writes the fix:** The AI modifies your code to handle null addresses gracefully, runs your test suite to verify, and submits a clean pull request.
# VS Code Extension IDE Guide
Source: https://docs.hyperprobe.co/extension/guide
Install, connect, configure, and manage real-time probes directly inside your IDE.
The HyperProbe VS Code extension brings the entire production debugging workflow straight into your code editor. Insert snapshot points, inject logs, and track performance counters directly on your source codeβwithout switching windows or opening dashboards.
***
## π 1. Installation
You can install the HyperProbe extension using either the visual Extensions Marketplace or keyboard-only Quick Open (works in VS Code, VSCodium, and Gitpod via the Open VSX Registry):
1. Open VS Code and navigate to the Extensions panel (`Cmd+Shift+X` on macOS / `Ctrl+Shift+X` on Windows/Linux).
2. Search for **HyperProbe** and click **Install**.
1. Launch VS Code Quick Open by pressing **`Cmd+P`** (macOS) or **`Ctrl+P`** (Windows/Linux).
2. Paste the following command and press **Enter**:
```text theme={null}
ext install hyperprobe.hyperprobe-extension
```
Once installed, a new **HyperProbe Debugger** icon will appear inside your side Activity Bar instantly without requiring an editor restart!
***
## βοΈ 2. Connection & Configuration
The extension must know where your HyperProbe Server is hosted.
### Setting the Server URL
By default, the **`hyperprobe.serverUrl`** setting is configured to point to:
```text theme={null}
https://app.hyperprobe.co
```
This is correct for general cloud usage. If you are self-hosting or testing locally:
1. Open VS Code Settings (`Cmd+,` / `Ctrl+,`).
2. Search for `hyperprobe.serverUrl`.
3. Set your server URL, for example: `https://app.hyperprobe.co`.
```json .vscode/settings.json theme={null}
{
"hyperprobe.serverUrl": "https://app.hyperprobe.co"
}
```
**Pro-Tip:** Commit a workspace-level `.vscode/settings.json` file to your git repository. This automatically aligns the server URL for your entire engineering team when they clone the codebase!
***
## π― 3. Inserting and Managing Probes
Once configured, placing a probe on any line is as simple as a right-click.
The extension discovers active running services by reading a `.hprc` file placed at the root of your local repository. Create a `.hprc` file containing your Service UUID from the dashboard:
```json .hprc theme={null}
{
"serviceId": ""
}
```
Right-click any executable statement in your editor and choose **Insert a Snapshot** (or Dynamic Log, Counter, etc.).
The probe creation drawer will slide open with context-aware parameters:
* **Watch Expressions:** Enter custom code expressions to evaluate live (e.g., `user.cart.total` or `isNewCustomer()`).
* **Condition:** Filter execution paths. The probe will only capture data when the boolean expression evaluates to true (e.g., `req.headers['x-user-id'] === 'user_1029'`).
* **Hit Limit:** Set how many times the probe fires before self-destructing in-process (snapshots default to `1` for safety, logs default to `100`).
***
## π 4. Inspecting Captured Telemetry
Click any completed or active probe in your side panel to open the **Snapshot Inspector**:
```text theme={null}
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β π’ HIT 1 OF 3 (Captured 2:14:10 PM) β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β ββ βΌ WATCH EXPRESSIONS β
β β ββ user.cart.total: 104.99 β
β β β
β ββ βΌ LOCAL VARIABLES β
β β ββ req: { method: 'POST', path: '/checkout' } β
β β ββ session: { active: true, claims: [...] } β
β β ββ address: "123 Main St, New York" β
β β β
β ββ βΌ CALL STACK β
β β ββ 0: CheckoutController.ts:line 45 β
β β ββ 1: Router.ts:line 102 β
β β ββ 2: Server.ts:line 12 β
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
* **Interactive Call Stack:** Click on any stack frame in the Call Stack block to dynamically switch the Variables panel to inspect the exact heap state of that specific scope level!
* **Text Filters:** Type into the Variables panel search bar to instantly isolate deep keys on heavy payloads (like Express request headers).
# Production Safety, Guardrails & Security Compliance
Source: https://docs.hyperprobe.co/guides/safety-and-security
A comprehensive guide on how HyperProbe protects your application performance and secures production data.
As a production-grade debugging system, HyperProbe is designed from the ground up under two absolute rules:
1. **Never crash or slow down the host application.**
2. **Never leak sensitive data outside the container boundary.**
This document provides our deep technical specifications on safety, guardrails, and secure data sanitization to share with your operations and InfoSec teams.
***
## π‘οΈ Part 1: Automated Safety Guardrails
The SDK agent runs an asynchronous safety monitor on a separate thread/event loop cycle to track host system overhead in real-time.
### Agent Health States
The safety monitor maps the agent into three operational states:
* π’ **GREEN:** Normal operation. All indicators are healthy.
* π‘ **YELLOW (Java Memory \< 15%):** Alert state. Captures are paced to reduce heap allocation speed.
* π΄ **RED (Overhead Spike):** Cooldown shield. **All active probes are instantly uninstalled in-memory** for the duration of the cooldown period (default `10` seconds) before automatically attempting a clean resume.
### Configurable Safety Thresholds
You can configure these limits in code or via environment variables to match your environment's latency budget.
| Code Parameter | Env Variable | Default | Description |
| :------------------ | :---------------------------- | :------ | :---------------------------------------------------------------------------- |
| `hitsPerSec` | `HYPERPROBE_HITS_SEC` | `10` | Maximum probe execution captures allowed per second globally. |
| `bandwidthKbPerSec` | `HYPERPROBE_BANDWIDTH_KB_SEC` | `200` | Caps the outbound network payload rate to prevent broker floods. |
| `maxLagMs` | `HYPERPROBE_MAX_LAG_MS` | `50` | Maximum event-loop lag (Node.js) before triggering the RED cooldown shield. |
| `pauseBudgetMs` | `HYPERPROBE_PAUSE_BUDGET_MS` | `20` | Maximum total cumulative CPU execution budget per second allowed for hooks. |
| `cooldownSec` | `HYPERPROBE_COOLDOWN_SEC` | `10` | Duration (in seconds) the agent remains completely dormant after hitting RED. |
***
## π Part 2: Zero-Trust In-Process Data Redaction
Many debugging tools leak database credentials or user credentials because they capture memory dumps. HyperProbe prevents this using an **In-Process Sanitization Engine**.
**All variable filtering, structural serialization limits, and secret redactions occur inside your container's memory boundary.** Raw, unsanitized variables never reach network packets or leave your secure execution context.
### Default Redacted Keys
By default, any variable whose key matches any of the following patterns (case-insensitive) has its value replaced with `[REDACTED]` before serialization:
```text theme={null}
password, secret, token, authorization, cookie, key, signature, ssn, creditCard
```
### Customizing Redactions
Extend default keys or redact known literal values (like system-wide master tokens):
```typescript theme={null}
HyperProbe.start({
serviceId: '',
environment: process.env.NODE_ENV, // Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
brokerUrl: 'https://logger.app.hyperprobe.co',
redactKeys: ['password', 'secret', 'token', 'authorization', 'apiKey', 'cvv'],
redactValues: [process.env.STRIPE_SECRET_KEY] // Redact actual API key values
});
```
```bash theme={null}
HYPERPROBE_REDACT_KEYS=password,secret,token,authorization,apiKey,cvv
HYPERPROBE_REDACT_VALUES=sk_live_abc123,internal-token-xyz
```
***
## π¦ Part 3: Payload Structural Constraints
To guarantee that capturing a deep object (like an Express request wrapper or a heavy database row result) doesn't result in high memory pressure, HyperProbe strictly enforces hard structural limits on serialized payloads:
| Setting Parameter | Env Variable | Default | What it controls |
| :-------------------- | :--------------------------------- | :------ | :--------------------------------------------------------------------------- |
| `maxObjectDepth` | `HYPERPROBE_MAX_OBJECT_DEPTH` | `3` | Maximum nesting depth for object properties. Excess is marked `[truncated]`. |
| `maxArrayLength` | `HYPERPROBE_MAX_ARRAY_LENGTH` | `3` | Maximum array elements captured. Excess is sliced. |
| `maxObjectProperties` | `HYPERPROBE_MAX_OBJECT_PROPERTIES` | `50` | Maximum key-value pairs captured per object. |
| `maxStringLength` | `HYPERPROBE_MAX_STRING_LENGTH` | `1024` | Maximum character length captured from string properties. |
| `stackFrameDepth` | `HYPERPROBE_STACK_FRAME_DEPTH` | `3` | Maximum call stack frames captured per snapshot. |
These limits apply structurally to each variable during heap traversal. The overall telemetry event size is dynamically throttled and capped by your configured in-process **Bandwidth Cap (`bandwidthKbPerSec`)** before transmission, protecting your network from spikes.
# How It Works
Source: https://docs.hyperprobe.co/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:
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.
The SDK agent polls the broker for active probes and dynamically instruments the target line in-memory. This happens live, with no process restarts.
When execution hits the instrumented line, the SDK agent captures variables, logs, counters, or metrics. **The agent never pauses application threads.**
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.
The extension fetches the captured data and renders it inside your editor's **HyperProbe** panel, presenting complete variable trees and call stacks.
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.
The coding agent forms testable hypotheses and selects targeted probe locations. HyperProbe verifies the service, environment, and deployed commit before collecting runtime 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.
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.
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.
Learn how to connect your coding agent in the [AI-native debugging with MCP guide](/ai-native/mcp-server).
***
## 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.
![HyperProbe architecture for VS Code and MCP clients]()
***
## 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.
# HyperProbe: Production Debugging Without Deployments
Source: https://docs.hyperprobe.co/index
Capture live variable snapshots, inject logs, and trace call stacks in running production codeβwithout pausing execution, redeploying, or changing your source. Get started in under 2 minutes.
You are a senior engineer, so let's skip the marketing speak and talk about last Sunday at 2:00 AM.
## π¨ The Sunday 2:00 AM Incident
A critical checkout API endpoint is failing for 0.5% of users with an obscure error:
`TypeError: Cannot read properties of undefined (reading 'taxRate')`.
It doesn't happen in your local environment, and it doesn't happen in staging. It only happens under specific production database state conditions.
1. **Edit Code:** Open your editor and add `console.log('DEBUG USER STATE:', user, order);`
2. **Push Git Branch:** Commit, push, and open a PR.
3. **Wait for CI/CD:** Spend 15 minutes waiting for unit tests and build steps to pass.
4. **Deploy:** Roll out the new Docker image to your Kubernetes cluster.
5. **Wait for Incident:** Monitor logs, hoping the bug triggers again so you can search CloudWatch/Datadog.
6. **Discover Gaps:** Realize you logged the `user` but forgot to log the nested `address` object. **Start over from Step 1.**
1. **Open VS Code:** Find the failing line in your local repo.
2. **Place a Snapshot:** Right-click and select **Insert a Snapshot**. (The SDK agent instantly applies a microsecond hook in-process).
3. **Capture State:** The next time a failing request hits that line, **the exact local variable tree, call stack frames, and watch expressions populate live inside your VS Code sidebar.**
4. **Inspect & Fix:** You immediately see `address` is an unparsed string instead of an object. You delete the probe and write the fix. **No downtime, no log spam, zero deploys.**
***
## π§ The AI-Native Edge: Let Your Coding Agent Debug Production
HyperProbe exposes its entire debugging engine via the **Model Context Protocol (MCP)**. This means your local desktop AI assistant (like **Claude Desktop, Cursor, or Windsurf**) can autonomously debug production incidents for you.
![AI-Native Production Debugging with MCP]()
You can literally ask your AI assistant:
> *"Our user payment processing is throwing exceptions in prod. Go check the live variables of BillingService.ts, isolate the bad payload structure, and tell me how to fix it."*
The AI will:
1. Scan your local codebase to find the file and line.
2. Connect to the HyperProbe Broker using MCP.
3. Automatically inject a Snapshot Probe on the target line.
4. Block on the telemetry queue until a live request hits it.
5. Read the captured state, identify the exact broken parameter, and write the hotfix.
***
## π Engineered for High-Throughput Production Environments
Attaching a debugger to production sounds terrifying. We built HyperProbe because we were terrified too. Here is why it is completely safe:
HyperProbe does **not** pause the event loop or use standard blocking debugging breakpoints. It binds asynchronous listeners directly to the runtime engine (V8 Inspector API for Node.js, runtime Bytecode Manipulation for JVM). Hooks execute and detach in under **15 microseconds**.
Sensitive properties (`password`, `token`, `cookie`, `creditCard`) are stripped **in-process inside your container** before any payload is compiled or transmitted. Secure credentials never leave your application's memory boundary.
The agent continuously monitors event loop lag and heap memory. If it detects more than 15ms of overhead or free memory dropping below 15%, it activates the **cooldown shield**, instantly purging all active probes in-process.
Every probe is created with an explicit lifetime (e.g., 1 hour) and a strict hit limit (snapshots default to `1`). Once met, the probe is permanently uninstalled, ensuring zero residual overhead.
***
## Ready to Get Started?
Choose your path and have live production telemetry flowing in under 2 minutes.
Set up the extension and Node/Java SDKs in 120 seconds.
Connect your coding agent to live debugging tools.
Pass your InfoSec review with our deep safety specifications.
# Probe Types & Instrumentation Catalog
Source: https://docs.hyperprobe.co/probes/overview
Understand, configure, and compare the four dynamic probe types available inside HyperProbe.
HyperProbe supports four specialized, ultra-lightweight probe types. Each probe is optimized for a different stage of production debugging and telemetry tracking.
***
## β‘ Comparison of Probe Capabilities
| Probe Type | What it captures | CPU Overhead | Memory Overhead | Payload Size | Best for |
| :---------------- | :-------------------------------------------------- | :----------------- | :-------------- | :----------- | :------------------------------------------------------------------------- |
| **Snapshot** | Local variables, watch expressions, full call stack | Low (microseconds) | Low | \~50KB-500KB | Inspecting complex state bugs, null-pointer exceptions, payload structures |
| **Dynamic Log** | Formatted string with interpolated runtime values | Very Low | Very Low | Low (\< 1KB) | Adding telemetry on-the-fly, checking thread execution, debugging routing |
| **Counter** | Numeric hit increment | Negligible | None | Raw Integer | Tracking hot paths (loops, cache misses) without log spam |
| **Custom Metric** | Evaluated float value of any expression | Negligible | None | Raw Float | Tracking latency ratios, queue depths, pool capacities |
***
## πΈ 1. Snapshot Probes
Snapshot probes act like standard breakpoints in local debugging, but they **never pause execution threads**. When hit, the agent grabs the active scope variables and the call stack frames, then instantly resumes control.
### How to Configure Snapshots
* **Hit Limit (Default `1`):** Limits how many snapshots are taken before the probe automatically uninstalls itself in-process. snapshots default to `1` to avoid heap copies.
* **Watch Expressions:** Enter custom evaluations (e.g. `user.profile.isAdmin`) to track deep nested values without serializing entire root objects.
* **Condition:** Filter the execution. Only captures when a boolean evaluation is met (e.g., `cart.total > 5000`).
***
## π 2. Dynamic Log Probes
Dynamic Log probes let you write log lines with interpolated variables (`${expression}`) and inject them into stdout/stderr without redeploying.
### message Formatting Syntax
Wrap runtime variables in standard string interpolation templates:
```text theme={null}
Processing purchase for user: ${user.id} | Items in cart: ${cart.items.length}
```
### Supported Log Levels
* `INFO` - Standard operational traces.
* `WARN` - Unexpected but non-fatal conditions.
* `ERROR` - Critical failures and exceptions.
* `DEBUG` - High-detail engineering diagnostics.
***
## π’ 3. Counter Probes
Counter probes are extremely lightweight. Instead of collecting strings or variable trees, they increment a running atomic counter in-process and stream the frequency of execution back to your editor.
### Key Use Cases
* Measuring branch execution (e.g., how often is the `else` block running versus the `if` block?).
* Tracking cache misses inside database queries.
* Measuring high-frequency loops (perfectly safe for paths executing millions of times per second).
***
## π 4. Custom Metrics Probes
Metric probes evaluate any mathematical or numerical expression and export the float result directly to your editor or metric dashboard.
### Example Expressions
```text theme={null}
databasePool.activeConnections
(endTime - startTime) / 1000
user.orders.count
```
### Conditionals & Hit Limits
Because metrics and counters generate minimal network payloads, their default hit limits can be scaled much higher (up to `10,000` hits) than Snapshots to build high-fidelity frequency charts.
# Quickstart: Set up HyperProbe in 2 Minutes
Source: https://docs.hyperprobe.co/quickstart
Configure your editor, drop in the agent, and capture live production variables. Zero restarts. Zero disruption.
Getting started with HyperProbe takes less than 2 minutes. Choose your environment below and let's get variables flowing.
***
## π The 2-Minute Speedrun
1. Search for **HyperProbe** in the VS Code Marketplace and click **Install** (or launch Quick Open with `Ctrl+P` / `Cmd+P`, paste `ext install hyperprobe.hyperprobe-extension`, and hit Enter).
2. Click the HyperProbe debug icon in your Activity Bar on the left.
3. Click the **Login** button inside the HyperProbe panel. You will be redirected to HyperProbe dashboard at [https://app.hyperprobe.co](https://app.hyperprobe.co)
4. Sign in via **SSO**, create a new service, and **copy your Service UUID** from the dashboard.
Create a `.hprc` file at the root of your repository to map your local workspace to your service:
```json .hprc theme={null}
{
"serviceId": ""
}
```
Add the lightweight agent dependency to your project setup:
Install the package using your preferred package manager:
```bash npm theme={null}
npm install @hyperprobe/node-sdk
```
```bash pnpm theme={null}
pnpm add @hyperprobe/node-sdk
```
```bash yarn theme={null}
yarn add @hyperprobe/node-sdk
```
Download the standard agent JAR artifact from your dashboard and save it inside your server workspace:
```bash theme={null}
curl -O https://hyperprobe-assets.s3.ap-south-1.amazonaws.com/static/hyperprobe-agent.jar
```
Initialize the HyperProbe singleton inside your codebase or launch routine:
Create a file named `hyperprobe.ts` in your source root, and import it **as early as possible** in your main entrypoint (e.g. `index.ts`):
```typescript src/hyperprobe.ts theme={null}
import { HyperProbe } from '@hyperprobe/node-sdk';
HyperProbe.start({
serviceId: '',
environment: process.env.NODE_ENV, // Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
brokerUrl: 'https://logger.app.hyperprobe.co',
commitSha: process.env.GIT_COMMIT, // CI-injected commit SHA
distLocation: 'dist'
});
```
```typescript src/index.ts theme={null}
import './hyperprobe.js'; // MUST BE AS EARLY AS POSSIBLE
import express from 'express';
...
```
Create a file named `hyperprobe.js` in your source root, and require it **as early as possible** in your main entrypoint (e.g. `index.js`):
```javascript src/hyperprobe.js theme={null}
const { HyperProbe } = require('@hyperprobe/node-sdk');
HyperProbe.start({
serviceId: '',
environment: process.env.NODE_ENV, // Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
brokerUrl: 'https://logger.app.hyperprobe.co',
commitSha: process.env.GIT_COMMIT
});
```
```javascript src/index.js theme={null}
require('./hyperprobe.js'); // MUST BE AS EARLY AS POSSIBLE
const express = require('express');
...
```
No code changes required. Attach the jar at startup using JVM arguments, mapping the parameters via environment variables:
```bash theme={null}
export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID=
export HYPERPROBE_ENVIRONMENT=production # Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
java -javaagent:/opt/hyperprobe/hyperprobe-agent.jar -jar app.jar
```
**Commit SHA Alignment:** HyperProbe relies on `commitSha` to align your local source files with the exact code running in production. If `commitSha` is missing or resolves to `'unknown'`, the agent will refuse to initialize to protect alignment.
1. Open any source file in VS Code.
2. Right-click an executable line of code and select **Insert a Snapshot**.
3. Trigger the path in your running service (e.g., hit the endpoint or perform the UI action).
**Inspect the live heap state, local variables, and the full call stack directly in your VS Code sidebar!**
Variables and stacks will populate inside your editor's sidebar panel the instant execution hits your probed line.
***
## π‘οΈ Production Safety Checklist
Before you deploy to production, verify these two configuration items:
* **Source Maps / Debug Symbols Enabled:** For TypeScript/Babel projects, ensure source-maps are enabled and compiled into your build. For JVM projects, ensure debug symbols are included in compiled JAR artifacts so byte positions align.
* **CI Pipeline Commit Injection:** Verify that your CI pipeline is injecting the active commit SHA into the environment (e.g. `GIT_COMMIT=$(git rev-parse HEAD)`).
# Java SDK Setup Guide
Source: https://docs.hyperprobe.co/sdks/java
Configure and attach the standard Java Instrumentation agent to your running JVM applications with zero code changes.
The HyperProbe Java Agent is a zero-touch JVM Instrumentation agent. By attaching the JAR at startup via the standard `-javaagent` flag, it intercepts and transforms application bytecode on-the-flyβrequiring **zero code changes, zero annotation wrappers, and zero compilation modifications**.
***
## Technical Prerequisites
* **Runtime:** Java 17 or later (compatible with Oracle HotSpot, OpenJDK, Corretto, Temurin).
* **Metadata:** Active git commit SHA (mandatory for resolving bytecode offsets to local lines).
* **Agent Jar:** The `hyperprobe-agent.jar` artifact. You can view and download all releases from [Maven Central (Sonatype)](https://central.sonatype.com/artifact/co.hyperprobe/hyperprobe-agent/versions).
***
## Downloading the Agent
Before attaching the agent, download the `hyperprobe-agent.jar` file. You can fetch it directly using `curl` or `wget` (be sure to replace `` with the current version from [Maven Central](https://central.sonatype.com/artifact/co.hyperprobe/hyperprobe-agent/versions)):
```bash curl theme={null}
curl -L -o hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent//hyperprobe-agent-.jar"
```
```bash wget theme={null}
wget -O hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent//hyperprobe-agent-.jar"
```
***
## Installation & Deployment
Attach the agent at startup using the standard `-javaagent` flag. Set the required environment variables before starting your application.
```bash theme={null}
# 1. Export deployment metadata
export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID=""
export HYPERPROBE_ENVIRONMENT=production # Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
# 2. Attach JVM Agent at runtime
java -javaagent:/opt/hyperprobe/hyperprobe-agent.jar -jar your-application.jar
```
Use environment variables for service, broker, and capture configuration. JVM system properties do not replace these settings. Custom trace ID hooks also support the system properties listed in the [configuration reference](#configuration-and-environment-variables).
***
## Deployment Templates
It is best practice to download the agent jar during build-time and bake the Git commit into the final image:
```dockerfile Dockerfile theme={null}
FROM eclipse-temurin:21-jre
# Define build arguments
ARG GIT_COMMIT
ENV GIT_COMMIT=${GIT_COMMIT}
# Setup agent directories
RUN mkdir -p /opt/hyperprobe
COPY hyperprobe-agent.jar /opt/hyperprobe/hyperprobe-agent.jar
COPY build/libs/app.jar /app/app.jar
# Inject static environment configuration
ENV HYPERPROBE_SERVICE_ID=""
ENV HYPERPROBE_ENVIRONMENT=production
ENV HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
ENTRYPOINT ["java", "-javaagent:/opt/hyperprobe/hyperprobe-agent.jar", "-jar", "/app/app.jar"]
```
Build the image in your pipeline by passing the active commit:
```bash theme={null}
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t app:latest .
```
Expose your environment parameters inside your deployment's spec definition:
```yaml deployment.yaml theme={null}
spec:
containers:
- name: billing-service
image: billing-service:latest
env:
- name: GIT_COMMIT
valueFrom:
configMapKeyRef:
name: build-metadata
key: commit-sha
- name: HYPERPROBE_SERVICE_ID
value: ""
- name: HYPERPROBE_ENVIRONMENT
value: "production"
- name: HYPERPROBE_BROKER_URL
value: "https://logger.app.hyperprobe.co"
command: ["java", "-javaagent:/opt/hyperprobe/hyperprobe-agent.jar", "-jar", "/app/app.jar"]
```
***
## π οΈ Build-Tool & Framework Setup
Attach the JVM agent inside your development environment to test probes locally before deploying.
Add the agent args to your standard Spring Boot run tasks inside `build.gradle.kts`:
```kotlin build.gradle.kts theme={null}
tasks.withType {
// 1. Add JVM Agent argument
jvmArgs("-javaagent:${rootDir}/libs/hyperprobe-agent.jar")
// 2. Inject environment parameters
environment("HYPERPROBE_SERVICE_ID", "")
environment("HYPERPROBE_ENVIRONMENT", "local")
environment("HYPERPROBE_BROKER_URL", "https://logger.app.hyperprobe.co")
environment("GIT_COMMIT", project.findProperty("gitCommit") ?: "unknown")
}
```
```groovy build.gradle theme={null}
bootRun {
jvmArgs = ["-javaagent:${rootDir}/libs/hyperprobe-agent.jar"]
environment "HYPERPROBE_SERVICE_ID", ""
environment "HYPERPROBE_ENVIRONMENT", "local"
environment "HYPERPROBE_BROKER_URL", "https://logger.app.hyperprobe.co"
environment "GIT_COMMIT", project.findProperty("gitCommit") ?: "unknown"
}
```
```xml pom.xml theme={null}
org.springframework.boot
spring-boot-maven-plugin
-javaagent:${project.basedir}/libs/hyperprobe-agent.jar
YOUR_SERVICE_UUID
local
https://logger.app.hyperprobe.co
${git.commit.id}
```
***
## Configuration and environment variables
The following example lists all supported runtime environment variables. Required values are examples; optional numeric and redaction settings show their defaults.
```bash theme={null}
# --- CORE OPTIONS (required strings) ---
export GIT_COMMIT=$(git rev-parse HEAD) # Commit used to build the deployed application
export HYPERPROBE_SERVICE_ID=""
export HYPERPROBE_ENVIRONMENT=production # Your environment name; no default
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
# --- BUFFERING & PERFORMANCE (integers) ---
export HYPERPROBE_FLUSH_INTERVAL_MS=1000 # Telemetry export interval in milliseconds
export HYPERPROBE_SYNC_INTERVAL_MS=60000 # Probe sync interval in milliseconds
# --- SAFETY GUARDRAILS (integers) ---
export HYPERPROBE_HITS_PER_SEC=20 # Agent-wide probe execution limit per second
export HYPERPROBE_BANDWIDTH_KB_PER_SEC=1024 # Telemetry bandwidth limit in KiB per second
export HYPERPROBE_COOLDOWN_SEC=10 # Delay before attempting recovery after suspension
# --- SOURCE LOCATIONS (string) ---
export HYPERPROBE_APP_ROOT="" # Prefix to strip from probe source paths
# --- DATA & REDACTION CONTROLS ---
export HYPERPROBE_REDACT_KEYS="password,secret,token,authorization,cookie,key,signature"
export HYPERPROBE_REDACT_VALUES="" # Comma-separated regex patterns; none by default
export HYPERPROBE_MAX_OBJECT_DEPTH=3 # Maximum object traversal depth
export HYPERPROBE_MAX_ARRAY_LENGTH=3 # Maximum captured array or iterable elements
export HYPERPROBE_MAX_OBJECT_PROPERTIES=50 # Maximum captured fields or map entries
export HYPERPROBE_MAX_STRING_LENGTH=1024 # String truncation limit
export HYPERPROBE_STACK_FRAME_DEPTH=3 # Maximum stack frames per snapshot
# --- OPTIONAL STARTUP & DEBUGGING (unset by default) ---
# export HYPERPROBE_DISABLED=YES # Disable the agent at startup
# export DEBUG="hyperprobe*" # Enable agent debug logging
# --- OPTIONAL TRACE ID HOOK (strings) ---
# export HYPERPROBE_TRACE_ID_CLASS="com.example.TraceIdHook"
# export HYPERPROBE_TRACE_ID_METHOD="getTraceId" # Default method name
```
### Core settings
* `GIT_COMMIT`, `HYPERPROBE_SERVICE_ID`, `HYPERPROBE_ENVIRONMENT`, and `HYPERPROBE_BROKER_URL` must be nonblank. The agent does not start if `GIT_COMMIT` is `unknown`. Java does not read `HYPERPROBE_COMMIT_SHA`.
* `HYPERPROBE_BROKER_URL` accepts an HTTP(S) URL or a raw gRPC target such as `localhost:50051`. Do not include a trailing slash or query string. HTTPS enables TLS; HTTP and raw targets use plaintext gRPC.
* `HYPERPROBE_DISABLED` disables startup only when set to `YES` (case-insensitive). `true` and `1` do not disable the agent.
### Capture and redaction
Use positive integers for numeric limits. Missing or invalid integer values fall back to defaults.
`HYPERPROBE_REDACT_KEYS` and `HYPERPROBE_REDACT_VALUES` accept comma-separated, case-insensitive regular expressions. Key patterns match field names and redact their values; value patterns redact matching portions of strings. A nonempty key list replaces the default list, so include the defaults when adding custom patterns. An empty value does not clear the default key rules.
These capture and redaction settings provide startup defaults. Broker configuration can update them, and individual snapshot probes can override numeric capture limits.
Java does not expose environment variables for queue size, RPC timeout, event-loop lag, or pause budgets. Options such as `HYPERPROBE_MAX_QUEUE_SIZE` and `HYPERPROBE_MAX_LAG_MS` from other SDKs do not apply.
### Logging and trace ID hooks
`DEBUG` accepts comma- or space-separated namespaces, such as `hyperprobe*`. It enables debug output without changing normal info, warning, or error logging.
For custom trace IDs, set `HYPERPROBE_TRACE_ID_CLASS` to a class with a public static, zero-argument method. `HYPERPROBE_TRACE_ID_METHOD` defaults to `getTraceId`. Without a custom class, the agent looks for `com.hyperprobe.hook.TraceIdHook.getTraceId()`.
You can also use `-Dhyperprobe.traceid.class=...` and `-Dhyperprobe.traceid.method=...`; these JVM properties take precedence over the corresponding environment variables.
***
## Memory Safety Shields
Because bytecode injection could theoretically impact Heap health on heavy memory spikes, the Java Agent includes an active **Memory Guardrail**:
* **Yellow Threshold (Free Memory \< 15%):** Logs a warning and paces serialization buffers.
* **Red Threshold (Free Memory \< 5%):** Instantly uninstalls and suspends all in-memory probes to shield your JVM from Out-Of-Memory (OOM) failures.
* **Auto-Recovery:** Resumes instrumentation automatically once GC recovers memory health and active cooldown cycles end.
# Kotlin SDK Setup Guide
Source: https://docs.hyperprobe.co/sdks/kotlin
Attach the HyperProbe JVM agent to your Kotlin application without changing application code.
HyperProbe supports Kotlin/JVM applications through the same agent used for [Java](/sdks/java). Attach the agent at startup to capture variables, stack frames, metrics, and logs without adding an initializer or annotations.
***
## Technical prerequisites
* **Runtime:** Kotlin/JVM on Java 17 or later. This guide does not apply to Kotlin/JS or Kotlin/Native.
* **Metadata:** The Git commit SHA used to build your deployed application.
* **Debug information:** Preserve source filenames, line numbers, and local variable metadata in your compiled classes so probes can resolve `.kt` source locations and capture locals.
***
## Installation
Download the agent JAR. Replace `` with a version from [Maven Central](https://central.sonatype.com/artifact/co.hyperprobe/hyperprobe-agent/versions):
```bash theme={null}
curl -L -o hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent//hyperprobe-agent-.jar"
```
You do not need a separate Kotlin SDK dependency. Adding the JAR as an application dependency alone does not activate the agent; you must pass `-javaagent` to the application JVM.
***
## Initialization walkthrough
Export these variables before starting your application. Replace the service ID with the UUID from your HyperProbe dashboard:
```bash theme={null}
export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID=""
export HYPERPROBE_ENVIRONMENT=production
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
```
Use `git rev-parse HEAD` for local runs. In CI/CD, set `GIT_COMMIT` to the commit used to build the deployed artifact. The agent does not start if it is missing or set to `unknown`.
Choose how you start your application. These examples assume the downloaded JAR is in your project root and the environment variables above are set.
```bash theme={null}
java -javaagent:./hyperprobe-agent.jar -jar build/libs/app.jar
```
Replace `build/libs/app.jar` with your executable application JAR.
Add the agent to your `bootRun` task:
```kotlin build.gradle.kts theme={null}
tasks.named("bootRun") {
jvmArgs("-javaagent:${rootDir}/hyperprobe-agent.jar")
}
```
```bash theme={null}
./gradlew bootRun
```
```bash theme={null}
mvn spring-boot:run \
-Dspring-boot.run.jvmArguments="-javaagent:$(pwd)/hyperprobe-agent.jar"
```
Keep your existing Kotlin `main` function unchanged. The agent starts before your application.
***
## Docker deployment
Copy the downloaded agent and your built application into the image. Adjust the application JAR path to match your build output:
```dockerfile Dockerfile theme={null}
FROM eclipse-temurin:21-jre
WORKDIR /app
ARG GIT_COMMIT
ENV GIT_COMMIT=${GIT_COMMIT}
COPY hyperprobe-agent.jar /app/hyperprobe-agent.jar
COPY build/libs/app.jar /app/app.jar
ENTRYPOINT ["java", "-javaagent:/app/hyperprobe-agent.jar", "-jar", "/app/app.jar"]
```
Build and run locally with the environment variables from the initialization step:
```bash theme={null}
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t app:latest .
docker run --rm \
-e HYPERPROBE_SERVICE_ID \
-e HYPERPROBE_ENVIRONMENT \
-e HYPERPROBE_BROKER_URL \
app:latest
```
***
## Configuration and environment variables
Kotlin uses the same environment variables and defaults as Java. See the [complete environment variable reference](/sdks/java#configuration-and-environment-variables) for performance limits, capture depth, redaction, logging, and trace ID hooks.
To disable the agent at startup, set `HYPERPROBE_DISABLED=YES`.
# Node.js SDK Setup Guide
Source: https://docs.hyperprobe.co/sdks/node
Install, initialize, and optimize the HyperProbe Node.js SDK inside in-process Node applications.
The HyperProbe Node.js SDK runs as an extremely lightweight in-process agent. It hooks directly into the V8 Virtual Machine inspector layer to execute non-blocking debugging, variable captures, metrics, and log injection in **microseconds**.
***
## Technical Prerequisites
* **Runtime:** Node.js 18 and later.
* **Metadata:** Access to the active git commit SHA (mandatory for matching local source coordinates to production builds).
* **Source Maps:** Mandatory for transpiled or bundled projects (TypeScript, Esbuild, Webpack).
***
## Installation
Add the SDK as a dependency using your package manager:
```bash npm theme={null}
npm install @hyperprobe/node-sdk
```
```bash pnpm theme={null}
pnpm add @hyperprobe/node-sdk
```
```bash yarn theme={null}
yarn add @hyperprobe/node-sdk
```
***
## πΊοΈ Configuring Source Maps for Transpilers
If your project is transpiled or bundled, **source maps are strictly mandatory** for the SDK agent to translate compiled bytecode coordinates back to your local source files.
Ensure `"sourceMap": true` is enabled in your compiler options:
```json tsconfig.json theme={null}
{
"compilerOptions": {
"sourceMap": true, // Must be true
"outDir": "./dist",
"rootDir": "./src"
}
}
```
Pass the `--sourcemap` flag inside your CLI build command, or set `sourcemap: true` in your build script API:
```javascript build.js theme={null}
import esbuild from 'esbuild';
esbuild.build({
entryPoints: ['src/index.ts'],
bundle: true,
sourcemap: true, // Must be true (generates *.js.map)
outdir: 'dist',
});
```
Set the `devtool` option inside your `webpack.config.js` to compile standard external source maps:
```javascript webpack.config.js theme={null}
module.exports = {
entry: './src/index.ts',
devtool: 'source-map', // Must be 'source-map'
output: {
path: path.resolve(__dirname, 'dist'),
filename: 'bundle.js',
},
};
```
***
## Initialization Walkthrough
Follow these steps to initialize the HyperProbe agent inside your application:
Create a dedicated file named `hyperprobe.ts` (or `hyperprobe.js`) inside your project source root. Select your module syntax below:
```typescript src/hyperprobe.ts theme={null}
import { HyperProbe } from '@hyperprobe/node-sdk';
HyperProbe.start({
serviceId: '',
environment: process.env.NODE_ENV, // Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
brokerUrl: 'https://logger.app.hyperprobe.co',
commitSha: process.env.GIT_COMMIT, // CI-injected commit SHA (reads process.env.GIT_COMMIT by default)
distLocation: 'dist', // Output directory name (e.g. 'dist' or 'build')
});
```
```javascript src/hyperprobe.js theme={null}
const { HyperProbe } = require('@hyperprobe/node-sdk');
HyperProbe.start({
serviceId: '',
environment: process.env.NODE_ENV, // Your environment name (e.g. dev, staging, production). Use whatever variable contains the env value.
brokerUrl: 'https://logger.app.hyperprobe.co',
commitSha: process.env.GIT_COMMIT, // CI-injected commit SHA (reads process.env.GIT_COMMIT by default)
distLocation: 'dist' // Output directory name (e.g. 'dist' or 'build')
});
```
In your main application entrypoint (e.g., `index.ts`, `server.ts`, or `app.js`), import your newly created `./hyperprobe` module **as early as possible** before starting your web server:
```typescript src/index.ts (ES Modules / TypeScript) theme={null}
import './hyperprobe.js'; // Import as early as possible
import express from 'express';
const app = express();
...
```
```javascript src/index.js (CommonJS) theme={null}
require('./hyperprobe.js'); // Import as early as possible
const express = require('express');
const app = express();
...
```
**Environment Variables Loading Order:** You should import `./hyperprobe` as early as possible. However, if you are configuring parameters inside `hyperprobe.ts` that rely on environment variables (such as those loaded via `dotenv`), ensure that you import/initialize `./hyperprobe` **after your environment configuration loader has run completely**, if needed.
To enable Docker-based deployments, define a `GIT_COMMIT` build argument inside your `Dockerfile` with a default value of `unknown`.
This ensures that existing local builds or developers' environments do not fail if they do not yet pass a build argumentβsafely fallback-disabling the HyperProbe agent until a valid SHA is injected:
```dockerfile Dockerfile theme={null}
# Define build argument with 'unknown' fallback to protect non-CI builds
ARG GIT_COMMIT=unknown
ENV GIT_COMMIT=${GIT_COMMIT}
```
For building and testing Docker containers locally on your laptop, inject your active git head using standard command line arguments:
```bash theme={null}
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t api:latest .
```
To protect alignment, HyperProbe refuses to start if `commitSha` resolves to `"unknown"`. Map your CI/CD platform's built-in commit SHA environment variable to `GIT_COMMIT` at deployment.
Always use your CI/CD engine's native environment variables to pass the real commit SHA:
| Platform / Engine | Configuration Option | Build Argument Syntax |
| :------------------------ | :------------------------------- | :--------------------------------------------------------------------------------- |
| **GitHub Actions** | PR-Safe HEAD Check (Recommended) | `--build-arg GIT_COMMIT=${{ github.event.pull_request.head.sha \|\| github.sha }}` |
| **GitHub Actions (Push)** | Standard Branch Push | `--build-arg GIT_COMMIT=${{ github.sha }}` |
| **GitLab CI/CD** | GitLab Variable | `--build-arg GIT_COMMIT=$CI_COMMIT_SHA` |
| **CircleCI** | CircleCI Variable | `--build-arg GIT_COMMIT=$CIRCLE_SHA1` |
| **PM2 / Systemd** | Native Linux CLI | `GIT_COMMIT=$(git rev-parse HEAD) pm2 start dist/app.js` |
**β οΈ Beware of the PR Merge Commit Trap:** By default, GitHub Actions checking out on a `pull_request` trigger checkout a **virtual merge commit** (testing how your branch merges into `main`) instead of the actual branch commit you pushed.
If you run `git rev-parse HEAD` or use `${{ github.sha }}` inside a PR workflow, **coordinate mapping will fail** because your local VS Code environment is pointing to your actual branch head.
To bypass this, always configure GitHub Actions on PRs to use: `${{ github.event.pull_request.head.sha || github.sha }}`
***
## βοΈ Configuration & Environment Variables Reference
You can configure the agent by passing properties inside your `HyperProbe.start()` options object, or by overriding them using **environment variables**.
The code block below illustrates a complete initialization containing all available options, along with their default values and corresponding **`HYPERPROBE_*` environment variables** which can override them:
```typescript src/hyperprobe.ts theme={null}
import { HyperProbe } from '@hyperprobe/node-sdk';
HyperProbe.start({
// --- CORE OPTIONS ---
serviceId: '', // Env: HYPERPROBE_SERVICE_ID
environment: process.env.NODE_ENV, // Env: HYPERPROBE_ENVIRONMENT
brokerUrl: 'https://logger.app.hyperprobe.co',
commitSha: process.env.GIT_COMMIT, // Env: GIT_COMMIT (Mandatory)
// --- BUFFERING & PERFORMANCE ---
maxQueueSize: 100, // Env: HYPERPROBE_MAX_QUEUE_SIZE - Cap on telemetry stored in memory
flushIntervalMs: 1000, // Env: HYPERPROBE_FLUSH_INTERVAL_MS - Milliseconds before draining the queue
syncIntervalMs: 60000, // Env: HYPERPROBE_SYNC_INTERVAL_MS - Sync cycle to fetch new active probes
// --- SAFETY GUARDRAILS ---
hitsPerSec: 10, // Env: HYPERPROBE_HITS_PER_SEC - Global limit on triggers per second
bandwidthKbPerSec: 1024,// Env: HYPERPROBE_BANDWIDTH_KB_PER_SEC - Throughput cap in Kilobytes/sec
maxLagMs: 80, // Env: HYPERPROBE_MAX_LAG_MS - Cooldown triggers if loop lag exceeds this (ms)
pauseBudgetMs: 30, // Env: HYPERPROBE_PAUSE_BUDGET_MS - Max cumulative CPU overhead allowed per second (ms)
cooldownSec: 10, // Env: HYPERPROBE_COOLDOWN_SEC - Duration (in seconds) the agent remains dormant after entering cooldown
// --- DATA SOURCE MAPS ---
distLocation: 'dist', // Env: HYPERPROBE_DIST_LOCATION - Compiled code folder name
appRoot: '', // Env: HYPERPROBE_APP_ROOT - Subdirectory path in monorepos
sourceMapDir: '' // Env: HYPERPROBE_SOURCE_MAP_DIR - Directory path to scan and upload source map files
// --- DATA & REDACTION CONTROLS ---
redactKeys: [ // Env: HYPERPROBE_REDACT_KEYS (comma-separated list, e.g. HYPERPROBE_REDACT_KEYS=password,secret,token,ssn,cvv)
'password', 'secret', 'token', 'authorization', 'cookie', 'key', 'signature'
], // Blacklisted keys are completely stripped and replaced with [REDACTED] in-process
redactValues: [], // Env: HYPERPROBE_REDACT_VALUES (comma-separated list) of literal strings to redact
maxObjectDepth: 3, // Env: HYPERPROBE_MAX_OBJECT_DEPTH - Max nested properties serialized
maxArrayLength: 3, // Env: HYPERPROBE_MAX_ARRAY_LENGTH - Max elements serialized per array
maxObjectProperties: 50,// Env: HYPERPROBE_MAX_OBJECT_PROPERTIES - Max key-value parameters recorded per object
maxStringLength: 1024, // Env: HYPERPROBE_MAX_STRING_LENGTH - Max character count before string truncation
stackFrameDepth: 3, // Env: HYPERPROBE_STACK_FRAME_DEPTH - Number of call stack frames captured per snapshot
});
```
**Environment Variable Precedence:** Any environment variable specified (e.g. setting `HYPERPROBE_HITS_PER_SEC=5` inside your server environment) will **automatically override** the code-level option passed to `HyperProbe.start()`.
# Python SDK Setup Guide
Source: https://docs.hyperprobe.co/sdks/python
Install, initialize, and optimize the HyperProbe Python SDK inside in-process Python applications.
The HyperProbe Python SDK runs as an extremely lightweight in-process agent. It uses Python's `sys.monitoring` APIs to capture variables, stack frames, and logs without blocking your application.
***
## Technical Prerequisites
* **Runtime:** Python 3.12 and later.
* **Metadata:** Access to the active git commit SHA (mandatory for matching local source coordinates to production builds).
***
## Installation
Add the SDK as a dependency using your package manager:
```bash pip theme={null}
pip install hyperprobe-agent
```
```bash poetry theme={null}
poetry add hyperprobe-agent
```
```bash pipenv theme={null}
pipenv install hyperprobe-agent
```
```bash uv theme={null}
uv add hyperprobe-agent
```
***
## Initialization Walkthrough
Follow these steps to initialize the HyperProbe agent inside your application:
Select one of the following initialization methods:
Create a dedicated file named `hyperprobe_init.py` in your project source root:
```python hyperprobe_init.py theme={null}
import os
from hyperprobe import HyperProbe
HyperProbe.start({
"service_id": "",
"environment": os.getenv("PYTHON_ENV"),
"broker_url": "https://logger.app.hyperprobe.co",
"commit_sha": os.getenv("GIT_COMMIT"),
})
```
Prepend your normal application startup command with the `hyperprobe-run` launcher:
```bash theme={null}
export GIT_COMMIT=$(git rev-parse HEAD)
export HYPERPROBE_SERVICE_ID=
export HYPERPROBE_ENVIRONMENT=production
export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
hyperprobe-run python main.py
```
This method works with standard Python scripts and WSGI/ASGI runners, such as `gunicorn` and `uvicorn`.
In your main application file, import `hyperprobe_init` **as early as possible** before starting your application:
```python main.py theme={null}
import hyperprobe_init
from app import create_app
app = create_app()
```
**Environment Variables Loading Order:** If `hyperprobe_init.py` reads variables loaded by a library such as `python-dotenv`, load those variables before importing `hyperprobe_init`.
To enable Docker-based deployments, define a `GIT_COMMIT` build argument inside your `Dockerfile` with a default value of `unknown`:
```dockerfile Dockerfile theme={null}
ARG GIT_COMMIT=unknown
ENV GIT_COMMIT=${GIT_COMMIT}
```
For building and testing Docker containers locally, inject your active git commit:
```bash theme={null}
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t api:latest .
```
To protect source alignment, HyperProbe refuses to start if `commit_sha` resolves to `unknown`. Pass the real commit SHA to `GIT_COMMIT` during deployment.
Always use your CI/CD platform's native commit SHA variable:
| Platform / Engine | Configuration Option | Build Argument Syntax |
| :------------------------ | :------------------------------- | :--------------------------------------------------------------------------------- |
| **GitHub Actions** | PR-Safe HEAD Check (Recommended) | `--build-arg GIT_COMMIT=${{ github.event.pull_request.head.sha \|\| github.sha }}` |
| **GitHub Actions (Push)** | Standard Branch Push | `--build-arg GIT_COMMIT=${{ github.sha }}` |
| **GitLab CI/CD** | GitLab Variable | `--build-arg GIT_COMMIT=$CI_COMMIT_SHA` |
| **CircleCI** | CircleCI Variable | `--build-arg GIT_COMMIT=$CIRCLE_SHA1` |
**Beware of the PR Merge Commit Trap:** By default, GitHub Actions checks out a virtual merge commit for a `pull_request` trigger instead of the commit from your branch.
If you use `git rev-parse HEAD` or `${{ github.sha }}` in a pull request workflow, source mapping can fail. Use `${{ github.event.pull_request.head.sha || github.sha }}` for pull request builds.
***
## Configuration & Environment Variables Reference
You can configure the agent by passing properties inside your `HyperProbe.start()` options object, or by using **environment variables**.
The following example includes the available programmatic options and their corresponding environment variables:
```python hyperprobe_init.py theme={null}
import os
from hyperprobe import HyperProbe
HyperProbe.start({
# --- CORE OPTIONS ---
"service_id": "",
"environment": os.getenv("PYTHON_ENV"),
"broker_url": "https://logger.app.hyperprobe.co",
"commit_sha": os.getenv("GIT_COMMIT"),
# --- BUFFERING & PERFORMANCE ---
"max_queue_size": 100, # Env: HYPERPROBE_MAX_QUEUE_SIZE
"flush_interval_ms": 1000, # Env: HYPERPROBE_FLUSH_INTERVAL_MS
"sync_interval_ms": 60000, # Env: HYPERPROBE_SYNC_INTERVAL_MS
# --- SAFETY GUARDRAILS ---
"hits_per_sec": 10, # Env: HYPERPROBE_HITS_PER_SEC
"bandwidth_kb_per_sec": 1024, # Env: HYPERPROBE_BANDWIDTH_KB_PER_SEC
# --- DATA & REDACTION CONTROLS ---
"redact_keys": [ # Env: HYPERPROBE_REDACT_KEYS
"password", "secret", "token", "authorization", "cookie", "key", "signature"
],
"redact_values": [], # Env: HYPERPROBE_REDACT_VALUES
"max_object_depth": 3, # Env: HYPERPROBE_MAX_OBJECT_DEPTH
"max_array_length": 3, # Env: HYPERPROBE_MAX_ARRAY_LENGTH
"max_object_properties": 50, # Env: HYPERPROBE_MAX_OBJECT_PROPERTIES
"max_string_length": 1024, # Env: HYPERPROBE_MAX_STRING_LENGTH
"stack_frame_depth": 3, # Env: HYPERPROBE_STACK_FRAME_DEPTH
})
```
***
## Safety Shields
Because dynamic monitoring could affect application performance during heavy execution spikes, the Python Agent includes active **Safety Shields**:
* **Yellow Threshold:** Logs a warning when execution lag or cumulative pause time reaches 50% of its limit.
* **Red Threshold:** Suspends tracing when execution lag exceeds 50 ms or cumulative pause time exceeds 15 ms.
* **Auto-Recovery:** Resumes instrumentation after the cooldown period when application performance stabilizes.
# Ruby SDK Setup Guide
Source: https://docs.hyperprobe.co/sdks/ruby
Install, initialize, and optimize the HyperProbe Ruby and JRuby SDK inside in-process Ruby applications.
The HyperProbe Ruby SDK runs as an in-process agent for standard Ruby (CRuby) and JRuby. It captures variable snapshots, stack frames, metrics, and logs without adding logging statements to your application. Capture overhead depends on your probes and workload.
***
## Technical Prerequisites
* **Standard Ruby (CRuby):** Ruby 3.0 and later.
* **JRuby (Ruby on JVM):** JRuby 9.3 and later on Java 11 or later (Java 17, 21, and 25 supported). Requires the JIT-preserving tracing profile in `JRUBY_OPTS`.
* **Metadata:** Access to the active git commit SHA (mandatory for matching local source coordinates to production builds).
***
## Installation
Add the SDK as a dependency using your package manager:
```ruby Gemfile theme={null}
gem 'hyperprobe-agent'
```
```bash bundle add theme={null}
bundle add hyperprobe-agent
```
```bash gem theme={null}
gem install hyperprobe-agent
```
If you added `gem 'hyperprobe-agent'` directly to your `Gemfile`, run:
```bash theme={null}
bundle install
```
***
## Initialization Walkthrough
Follow these steps to initialize the HyperProbe agent inside your application:
Create a dedicated file named `hyperprobe.rb` in your project root:
```ruby hyperprobe.rb theme={null}
require 'hyperprobe'
HyperProbe.start(
service_id: '',
environment: ENV['HYPERPROBE_ENVIRONMENT'] || ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'production',
broker_url: 'https://logger.app.hyperprobe.co',
commit_sha: ENV['GIT_COMMIT'] || ENV['HYPERPROBE_COMMIT_SHA']
)
```
In your main application entrypoint (such as `config/environment.rb` for Rails, or `app.rb` / `server.rb` for Sinatra / Rack), require `hyperprobe` **as early as possible** before starting your application:
```ruby Rails (config/environment.rb) theme={null}
require_relative '../hyperprobe' # Require as early as possible
require_relative 'application'
Rails.application.initialize!
```
```ruby Sinatra / Rack / Web Server (app.rb) theme={null}
require_relative 'hyperprobe' # Require as early as possible
require 'sinatra'
get '/' do
'Hello World'
end
```
**Environment Variables Loading Order:** If `hyperprobe.rb` reads variables loaded by a library such as `dotenv`, load those variables before requiring `hyperprobe.rb`.
If you run a multi-process web server like Puma or Unicorn in clustered mode (with forked workers) on standard Ruby (CRuby), add `defer_start: true` to your initializer and call `HyperProbe.after_fork` in your worker boot configuration:
```ruby config/puma.rb theme={null}
on_worker_boot do
HyperProbe.after_fork
end
```
**JRuby on JVM:** On JRuby, Puma runs in multi-threaded mode on the JVM without process forking, so `HyperProbe.after_fork` and `defer_start` are not required.
To enable Docker-based deployments, define a `GIT_COMMIT` build argument inside your `Dockerfile` with a default value of `unknown`.
If you are running JRuby, also set the `JRUBY_OPTS` environment variable to preserve variable scopes with JIT enabled:
```dockerfile Dockerfile theme={null}
# Define build argument with 'unknown' fallback to protect non-CI builds
ARG GIT_COMMIT=unknown
ENV GIT_COMMIT=${GIT_COMMIT}
```
```dockerfile Dockerfile theme={null}
# Set required JRuby flags to preserve line boundaries and variables with JIT enabled
ENV JRUBY_OPTS="--debug -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass"
# Define build argument with 'unknown' fallback to protect non-CI builds
ARG GIT_COMMIT=unknown
ENV GIT_COMMIT=${GIT_COMMIT}
```
For building and testing Docker containers locally, inject your active git commit:
```bash theme={null}
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t api:latest .
```
To protect source alignment, HyperProbe refuses to start if `commit_sha` resolves to `unknown`. Pass the real commit SHA to `GIT_COMMIT` during deployment.
Always use your CI/CD platform's native commit SHA variable:
| Platform / Engine | Configuration Option | Build Argument Syntax |
| :------------------------ | :------------------------------- | :--------------------------------------------------------------------------------- |
| **GitHub Actions** | PR-Safe HEAD Check (Recommended) | `--build-arg GIT_COMMIT=${{ github.event.pull_request.head.sha \|\| github.sha }}` |
| **GitHub Actions (Push)** | Standard Branch Push | `--build-arg GIT_COMMIT=${{ github.sha }}` |
| **GitLab CI/CD** | GitLab Variable | `--build-arg GIT_COMMIT=$CI_COMMIT_SHA` |
| **CircleCI** | CircleCI Variable | `--build-arg GIT_COMMIT=$CIRCLE_SHA1` |
**Beware of the PR Merge Commit Trap:** By default, GitHub Actions checks out a virtual merge commit for a `pull_request` trigger instead of the commit from your branch.
If you use `git rev-parse HEAD` or `${{ github.sha }}` in a pull request workflow, source mapping can fail. Use `${{ github.event.pull_request.head.sha || github.sha }}` for pull request builds.
***
## β JRuby Support (Ruby on the JVM)
HyperProbe provides native, first-class support for JRuby applications running on the JVM.
### Prerequisites for JRuby
1. **JRuby Version:** JRuby **9.3 and later** (Java 8 is not supported; JRuby 10.1 requires Java 21+).
2. **Java Runtime:** Java 11, 17, 21, or 25.
3. **Launch Profile:** JRuby must be launched with the required JIT-preserving tracing profile:
```bash theme={null}
--debug -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass
```
### Why the Launch Profile is Required on JRuby
JRuby's JIT compiler optimizes hot methods into raw JVM bytecode, stripping out line-level checkpoints and local variable names by default. Passing this profile instructs JRuby to retain line checkpoints and local variable scopes without disabling JIT compilation, so probes trigger reliably on compiled methods.
### How to Launch JRuby with HyperProbe
Add the environment variable inside your `Dockerfile` or Deployment manifest:
```dockerfile Dockerfile theme={null}
ENV JRUBY_OPTS="--debug -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass"
```
Set the `JRUBY_OPTS` variable before starting your application:
```bash theme={null}
export JRUBY_OPTS="--debug -J-Djruby.ir.passes=AddCallProtocolInstructions,AddMissingInitsPass -J-Djruby.ir.jit.passes=AddCallProtocolInstructions,AddMissingInitsPass"
bundle exec jruby app.rb
# Or with Puma:
bundle exec puma -C config/puma.rb
```
*(Note: If running JRuby 9.3 on Java 17, also include `-J--add-opens=java.base/sun.nio.ch=ALL-UNNAMED -J--add-opens=java.base/java.io=ALL-UNNAMED` for JRuby's native I/O access).*
**Zero C-Extensions & Zero Runtime Downloads:** On JRuby, Bundler automatically installs the Java gem artifact (`hyperprobe-agent--java.gem`). It bundles an internal, shaded Netty gRPC transport and patched protobuf codec. No C compiler, Maven, or runtime downloads are required on the client machine.
***
## Configuration & Environment Variables Reference
You can configure the agent by passing properties inside your `HyperProbe.start()` options hash, or by using **environment variables**.
The following example includes the available programmatic options and their corresponding environment variables:
```ruby hyperprobe.rb theme={null}
require 'hyperprobe'
HyperProbe.start(
# --- CORE OPTIONS ---
service_id: '', # Env: HYPERPROBE_SERVICE_ID
environment: ENV['HYPERPROBE_ENVIRONMENT'], # Env: HYPERPROBE_ENVIRONMENT (e.g. 'production', 'staging')
broker_url: 'https://logger.app.hyperprobe.co',# Env: HYPERPROBE_BROKER_URL
commit_sha: ENV['GIT_COMMIT'], # Env: GIT_COMMIT or HYPERPROBE_COMMIT_SHA (Mandatory)
# --- BUFFERING & PERFORMANCE ---
max_queue_size: 100, # Env: HYPERPROBE_MAX_QUEUE_SIZE - Cap on telemetry stored in memory
flush_interval_ms: 1000, # Env: HYPERPROBE_FLUSH_INTERVAL_MS - Milliseconds before draining the queue
sync_interval_ms: 60000, # Env: HYPERPROBE_SYNC_INTERVAL_MS - Sync cycle to fetch new active probes
# --- SAFETY GUARDRAILS ---
hits_per_sec: 10, # Env: HYPERPROBE_HITS_PER_SEC - Global limit on triggers per second
bandwidth_kb_per_sec: 1024,# Env: HYPERPROBE_BANDWIDTH_KB_PER_SEC - Throughput cap in Kilobytes/sec
max_lag_ms: 50, # Env: HYPERPROBE_MAX_LAG_MS - Thread-lag threshold in ms (CRuby only)
pause_budget_ms: 15, # Env: HYPERPROBE_PAUSE_BUDGET_MS - Probe-handler time budget in ms/sec (CRuby only)
cooldown_sec: 10, # Env: HYPERPROBE_COOLDOWN_SEC - Duration (in seconds) the agent remains dormant in cooldown
rpc_timeout_sec: 10, # Env: HYPERPROBE_RPC_TIMEOUT_SEC - gRPC request timeout in seconds
# --- DATA & REDACTION CONTROLS ---
redact_keys: [ # Env: HYPERPROBE_REDACT_KEYS (comma-separated list)
'password', 'secret', 'token', 'authorization', 'cookie', 'key', 'signature'
], # Blacklisted keys are stripped and replaced with [REDACTED] in-process
redact_values: [], # Env: HYPERPROBE_REDACT_VALUES (comma-separated list of regex patterns)
max_object_depth: 3, # Env: HYPERPROBE_MAX_OBJECT_DEPTH - Max nested properties serialized
max_array_length: 3, # Env: HYPERPROBE_MAX_ARRAY_LENGTH - Max elements serialized per array
max_object_properties: 50, # Env: HYPERPROBE_MAX_OBJECT_PROPERTIES - Max key-value parameters recorded per object
max_string_length: 1024, # Env: HYPERPROBE_MAX_STRING_LENGTH - Max character count before string truncation
stack_frame_depth: 3 # Env: HYPERPROBE_STACK_FRAME_DEPTH - Number of call stack frames captured per snapshot
)
```
* **Option Precedence:** Explicit options passed to `HyperProbe.start()` take precedence over environment variables.
* **Disabling the Agent:** Set `HYPERPROBE_DISABLED=YES` in your environment to completely disable the agent at startup.
* **Option Naming:** Both `snake_case` (e.g., `service_id`, `commit_sha`) and `camelCase` (e.g., `serviceId`, `commitSha`) parameter keys are accepted.
On CRuby, snapshots include locals from the hit frame and available caller frames, including blocks, up to `stack_frame_depth`. On JRuby, only the hit frame has locals; caller frames show `{}`.
***
## Safe evaluation
Safe evaluation is enabled by default on Ruby and JRuby. To allow custom method calls in probe expressions, opt in before starting your application:
```bash theme={null}
export HYPERPROBE_DISABLE_SAFE_EVALUATION=true
```
Alternatively, add `disable_safe_evaluation: true` to your existing `HyperProbe.start` options. An explicit `false` keeps safe evaluation enabled, even if the environment variable is `true`.
Disabling safe evaluation lets conditions, watches, log placeholders, metrics, and duration correlations execute Ruby code with your application's permissions. This code can change state, block, or terminate the process. Only enable it for trusted probes. The SDK logs a warning once at startup when enabled.
***
## Safety shields
The SDK automatically suspends probes when its safety limits are exceeded:
* **CRuby:** Uses repeated thread-lag readings and a probe-handler time budget (default 15 ms per second).
* **JRuby:** Checks JVM heap headroom every 5 seconds. Below 15% of maximum heap triggers a warning; below 5% suspends probes. Timing-budget breaches do not log warnings or suspend probes.
* **Auto-recovery:** Resumes probes after the cooldown period (default 10 seconds), once health returns to GREEN.
# Integration using AI agent
Source: https://docs.hyperprobe.co/sdks/with-ai-agent
Please prompt your AI agent with the documentation link below to integrate the Hyperprobe SDK seamlessly into your project.
**Prompt:**
```markdown theme={null}
Install and integrate the Hyperprobe SDK into my project using
https://docs.hyperprobe.co/sdks/ai-agent-installation-prompt.md as your guide.
```
The AI agent will explain the steps, provide relevant information regarding the integration and ask for details if any are required to complete the task.
# Self-Hosting Deployment Guide
Source: https://docs.hyperprobe.co/self-hosting
Deploy the HyperProbe server, database, and telemetry broker on your own infrastructure using Docker Compose.
For teams with strict compliance mandates or isolated VPC requirements, you can self-host the entire HyperProbe architecture (Dashboard UI, Telemetry Broker, Database, and Traefik reverse proxy) on a single Linux VM.
***
## π₯οΈ System Requirements
Ensure your host VM meets these minimum hardware profiles:
| Resource | Recommended Minimum |
| :------------------- | :--------------------------------- |
| **Operating System** | Ubuntu 22.04 LTS or 24.04 LTS |
| **CPU** | 4 vCPU |
| **RAM** | 16 GB |
| **Storage** | 50 GB SSD |
| **Docker** | Docker v26+ and Docker Compose v2+ |
***
## π οΈ Step-by-Step Installation
Verify that your VM is running the latest Docker Engine:
```bash theme={null}
docker -v
```
If Docker is not yet installed or is below version 25, run the official utility script to bootstrap it:
```bash theme={null}
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
```
Create a secure home directory and fetch the official HyperProbe starter bundle:
```bash theme={null}
sudo mkdir -p /opt/hyperprobe
cd /opt/hyperprobe
sudo curl -O https://hyperprobe-assets.s3.ap-south-1.amazonaws.com/static/hyperprobe.tar.xz
sudo tar -xf hyperprobe.tar.xz
```
Inside the extracted bundle, open the `.env` file and customize the port bindings and versions. Ensure these ports are open on your VM's firewall/security group rules:
* `HOST_BACKEND_PORT_TRAEFIK` - The port used by developers to access the HyperProbe web dashboard.
* `HOST_LOGGER_PORT_TRAEFIK` - The secure port that connected SDK agents will use to transmit dynamic log, counter, and snapshot payloads.
* `HOST_CONSUL_HTTP_PORT_TRAEFIK` - Internal registry port.
* `HYPERTEST_VERSION` - The platform version tag to pull. Set this to the latest `@hyperprobe/node-sdk` tag shown below. Platform and Node SDK always share the same the release tag value.
To avoid hitting pull rate limits (`toomanyrequests: Rate exceeded`) when pulling images from `public.ecr.aws`, authenticate Docker with AWS ECR before running Docker Compose.
**Note:** Authentication with AWS ECR Public requires `--region us-east-1` regardless of your default AWS region setup.
```bash theme={null}
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
Run Docker Compose in detached mode to download and launch the services:
Complete aws login for better
```bash theme={null}
sudo docker compose up -d
```
Navigate your browser to:
```text theme={null}
http://:
```
Sign in, create your primary admin account, and enter your license key to activate the workspace!
* Go to teams page from left navigation menu.
* Click **Create Team** and enter the required details to set up a non-admin team.
*Note: Only non-admin teams can be associated with services.*
* Create a service under your non-admin team.
* Integrate the HyperProbe SDK automatically by clickingΒ [Integration using AI agent](/sdks/with-ai-agent)Β or select your programming language from options below to follow steps and set up manually.
[Node.js SDK Setup Guide](/sdks/node)
[Java Agent Setup Guide](/sdks/java)
[Python SDK Setup Guide](/sdks/python)
[Ruby SDK Setup Guide](/sdks/ruby)
# Troubleshooting Glossary & FAQ
Source: https://docs.hyperprobe.co/troubleshooting/guide
Step-by-step solutions to common errors, connectivity issues, and frequently asked questions.
Find instant solutions to setup errors, network connection blocks, and common usage questions.
***
## π οΈ Step-by-Step Error Resolutions
### 1. Agent Fails to Start: Missing `commitSha`
**Error Message:**
```text theme={null}
[HyperProbe] CRITICAL: Failed to start agent. A valid "commitSha" is required via options or the GIT_COMMIT environment variable...
```
* **Cause:** `HyperProbe.start()` was called without a `commitSha` option, and the `GIT_COMMIT` environment variable is either empty or set to `"unknown"`. The agent refuses to run because it cannot map source code coordinates safely without a specific git reference.
* **Solution:** Provide the active commit SHA during build-time or runtime:
```bash theme={null}
# Recommended: Set it in your startup script
GIT_COMMIT=$(git rev-parse HEAD) node dist/index.js
```
***
### 2. Probe Gutter Icon Shows Hollow Orange Dot (Agent Not Going Live)
* **What you see:** A probe is successfully inserted inside VS Code, but the gutter indicator stays orange.
* **Cause:** The VS Code extension has registered the probe on the server, but the SDK agent is either offline, unreachable, or configured with mismatched service coordinates.
* **Solution:**
Open your local project's `.hprc` file and compare its `serviceId` exactly (case-sensitive) with the `serviceId` passed to `HyperProbe.start()` in your server code:
```json .hprc theme={null}
{ "serviceId": "billing-api" }
```
```typescript src/app.ts theme={null}
HyperProbe.start({ serviceId: 'billing-api' }); // Must match .hprc!
```
Ensure your container can resolve and access the Broker server. Try curling the health endpoint directly from inside the application's hosting shell:
```bash theme={null}
curl https://logger.app.hyperprobe.co/health
```
Verify that the environment dropdown selected inside your VS Code extension panel (e.g., `production`) matches the `environment` parameter in your SDK initialization.
***
### 3. Gutter Gutter Icon Shows Error Status (Solid Red Dot)
* **What you see:** A probe's status instantly transitions to `ERROR`.
* **Cause:** The agent received the instruction but could not parse the line coordinates or compile the breakpoint hook.
* **Solution:**
* **Non-Executable Line:** Check if you placed the probe on a line containing comments, blank spaces, imports, type annotations (`interface`, `type`), or curly braces. **Move the probe to an executable line containing a statement.**
* **Missing Source Maps:** For TypeScript or compiled projects, ensure `"sourceMap": true` is enabled in your compiler config, and that`distLocation` point to your built outputs so the agent can match coordinates.
***
### 4. Local Docker Connection Fails (`http://localhost:3001`)
* **What you see:** When running the SDK agent inside Docker but hosting the HyperProbe broker locally, the agent fails to connect.
* **Cause:** Inside a Docker container, `localhost` resolves to the container's own loopback interface, not your machine's host ports.
* **Solution:** Update your containerized agent's `brokerUrl` config to use the host loopback alias:
```typescript theme={null}
HyperProbe.start({
// ...
brokerUrl: 'http://host.docker.internal:3001' // Routes to your machine's host localhost!
});
```
***
## β Frequently Asked Questions
No. Unlike traditional debuggers that lock threads or pause execution loops, HyperProbe runs fully asynchronously. It connects non-blocking callbacks to the native runtime engine (V8 Inspector/JVM transformation) that complete inside **microseconds**.
If the agent ever registers event loop lag crossing your limit (default: 50ms), it automatically activates its **cooldown shield**, instantly unregistering all probes to protect host resource health.
HyperProbe uses **in-process redaction**. Match lists (`password`, `secret`, `token`, `cookie`) are sanitized **inside your container** before any payload is compiled or sent. Plaintext credentials never touch network ports.
Yes, if your code executes directly without transpilations (e.g. standard ES6 Node.js). If you use TypeScript, Babel, Esbuild, or Webpack, **source maps are strictly required** for the agent to match your source files back to compiled JS on disk.
HyperProbe utilizes standard namespace debug log flags. Export the `DEBUG` flag before launching your service to isolate issues:
```bash theme={null}
# Show everything
DEBUG=hyperprobe:* node dist/index.js
# Isolate specific layers
DEBUG=hyperprobe:agent # General lifecycle and probe compilation
DEBUG=hyperprobe:broker # Outbound sync and gRPC communication
DEBUG=hyperprobe:safety # Event loop lag tracking and memory stats
```